Architecture Overview

Overview

KubePanel is a Kubernetes-native web hosting control panel built on a strict separation of concerns. Three components handle three distinct responsibilities:

The Three Layers

Django Dashboard — Business Logic

The Django application handles everything that requires business rules: who owns which domain, what resource limits apply, billing tiers, multi-tenancy, and audit trails. It communicates with Kubernetes exclusively through the Domain CR API.

Domain CR — The Contract

The Domain Custom Resource is the single source of truth for a domain's desired infrastructure state. Django writes to it; the operator reads from it. Status flows back the other way: the operator writes SFTP port, database credentials reference, phase, and conditions; Django reads them to display in the UI.

apiVersion: kubepanel.io/v1alpha1
kind: Domain
metadata:
  name: example-com
spec:
  domainName: example.com
  workload:
    type: php
    version: "8.2"
    image: docker.io/kubepanel/php82:v1.0
    port: 9001
    proxyMode: fastcgi
  resources:
    storage: 10Gi
    limits:
      cpu: "500m"
      memory: 512Mi
  email:
    enabled: true
    dkimSecretRef: dkim-example-com
status:
  phase: Ready
  sftp:
    port: 30042
    username: example-com
  database:
    host: mariadb.kubepanel.svc.cluster.local
    name: example_com

Kopf Operator — Infrastructure Manager

The operator is a Python application using the Kopf framework. It watches all Domain CRs cluster-wide and reconciles the full infrastructure stack for each domain. Key behaviors:

• On create: provisions the full stack — namespace, PVC, secrets, ConfigMaps, Deployment, Services, Ingress, MariaDB database, DKIM keys
• On update: patches only what changed (e.g. workload image, resource limits, nginx config)
• On delete: removes all Kubernetes resources, drops the MariaDB database, removes DKIM keys from central OpenDKIM
• On resume: operator restart — skips full reconciliation if the domain is already Ready
• Timer (every 5 min): reconciliation loop that corrects any drift from desired state

Request Flow

A typical HTTP request from a visitor to a KubePanel-hosted site:

Kubernetes Resources Per Domain

Every domain gets its own namespace (dom-example-com) containing the following resources:

Storage — Linstor / DRBD

KubePanel uses Linstor (Piraeus Operator) with DRBD for replicated block storage. Each domain's data PVC is replicated across nodes in real time. If a node fails, the PVC is immediately available on a healthy node.

Networking & Ingress

External HTTP/HTTPS traffic flows through nginx-ingress with ModSecurity WAF enabled. SFTP is exposed via NodePort services on the cluster's public node IPs.

Email Stack

All email services run in the kubepanel namespace and serve all hosted domains from a single shared stack.

DKIM private keys for all domains are stored in the dkim-keys Secret. The operator updates this secret and restarts OpenDKIM whenever a domain is added, updated, or deleted. See Email Hosting for the full DKIM flow.

Database

A single shared MariaDB instance runs in the kubepanel namespace. Each hosted domain gets its own database and user with auto-generated credentials stored only in a Kubernetes Secret — never in Django's database.

Isolation Model

Each domain is fully isolated from every other domain at multiple layers:

Secrets Management

KubePanel never stores sensitive credentials in Django's database. All secrets are generated by the operator and stored in Kubernetes Secrets within the domain's namespace.

Namespaces

Custom Resource Definitions

Port Reference