Skip to main content

Architecture Overview

Qumulus implements a layered architecture that enables running OpenStack on Kubernetes while maintaining operational simplicity and multi-tenancy.

System Architecture​

The platform consists of three main layers:

┌─────────────────────────────────────────┐
│           OpenStack Services            │
│    (Nova, Neutron, Cinder, etc.)        │
├─────────────────────────────────────────┤
│        Tenant Kubernetes Clusters       │
│     (Workload clusters for tenants)     │
├─────────────────────────────────────────┤
│        Management Kubernetes Cluster    │
│    (Kamaji, Control Plane Management)   │
└─────────────────────────────────────────┘

Core Components​

Management Cluster​

The management cluster serves as the central control point for the entire platform. It runs:

  • Kamaji: A Kubernetes operator that manages tenant control planes as pods rather than separate VMs, significantly reducing resource overhead
  • Cluster API: Provides declarative cluster lifecycle management
  • Platform Services: Monitoring, logging, and other shared services

Tenant Control Planes​

Each tenant receives a dedicated Kubernetes control plane managed by Kamaji. These control planes:

  • Run as pods within the management cluster
  • Provide full Kubernetes API compatibility
  • Are isolated from other tenants
  • Can be scaled and upgraded independently

Kamaji​

Kamaji is a key component that enables efficient multi-tenancy by:

  • Running control plane components (API server, controller manager, scheduler) as containers
  • Sharing the underlying etcd infrastructure when appropriate
  • Reducing the resource footprint compared to traditional VM-based control planes
  • Simplifying control plane lifecycle management

How the Layers Interact​

Cluster Provisioning Flow​

  1. A tenant requests a new Kubernetes cluster through the platform API
  2. The management cluster creates a TenantControlPlane resource
  3. Kamaji provisions the control plane components as pods
  4. Worker nodes are provisioned and joined to the tenant cluster
  5. The tenant receives kubeconfig credentials to access their cluster

OpenStack Deployment​

OpenStack services run on tenant Kubernetes clusters:

  1. Tenant cluster is provisioned with appropriate resources
  2. OpenStack Helm charts are deployed to the cluster
  3. Services are configured and interconnected
  4. OpenStack APIs become available to end users

Resource Model​

TenantControlPlane​

The TenantControlPlane custom resource defines a tenant's Kubernetes control plane:

apiVersion: kamaji.clastix.io/v1alpha1
kind: TenantControlPlane
metadata:
  name: my-cluster
  namespace: tenant-namespace
spec:
  kubernetes:
    version: "1.28.0"
  controlPlane:
    replicas: 3

Accessing Tenant Clusters​

Administrators can retrieve tenant cluster credentials:

# Get the kubeconfig secret
kubectl get secret <cluster-id>-admin-kubeconfig -n <tenant-namespace> \
  -o jsonpath='{.data.admin\.conf}' | base64 -d > ~/.kube/config.<cluster-id>

Security Model​

  • Namespace Isolation: Each tenant operates within dedicated namespaces
  • RBAC: Role-based access control limits what tenants can do
  • Network Policies: Network traffic is segmented between tenants
  • Control Plane Isolation: Tenant control planes are logically separated

Scaling Considerations​

The architecture supports horizontal scaling at multiple levels:

  • Management Cluster: Add nodes to support more tenant control planes
  • Tenant Clusters: Scale worker nodes based on workload requirements
  • OpenStack Services: Scale individual services independently