Cluster API Fleet Management

Petra supports managing fleets of workload clusters through the Kubernetes Cluster API (CAPI). A management cluster runs CAPI controllers and a Petra ClusterClass that encodes your cluster topology, security policies, and addon configuration.

Architecture

Management Cluster (Petra standalone)
  +-- CAPI Core Controller
  +-- CAPA (AWS Infrastructure Provider)
  +-- CABPK3s (k3s Bootstrap Provider)
  +-- CACPK3s (k3s Control Plane Provider)
  +-- Petra ClusterClass
       |
       +-- Workload Cluster A
       +-- Workload Cluster B
       +-- Workload Cluster C

Bootstrap a Management Cluster

Define a management cluster spec:

apiVersion: petra.sh/v1alpha1
kind: Cluster
metadata:
  name: petra-mgmt
spec:
  kubernetes:
    version: v1.35.3+k3s1
  profile: standard
  target:
    type: aws
    region: us-west-1
  nodes:
    controlPlane:
      count: 1
      instanceType: m5a.xlarge
    workers:
      count: 1
      instanceType: m5a.large
  management:
    capiVersion: v1.9.5
    capaVersion: v2.7.4
    cabpK3sVersion: v0.3.1
    cacpK3sVersion: v0.3.1
    certManagerVersion: v1.17.1
  addons:
    cilium:
      enabled: true
    flux:
      enabled: true

petra capi init -f management.yaml

This boots a Petra cluster, installs cert-manager, then installs all CAPI controllers, and applies the Petra ClusterClass.

Create Workload Clusters

Workload clusters use the same spec format without the management section:

apiVersion: petra.sh/v1alpha1
kind: Cluster
metadata:
  name: workload-dev
spec:
  kubernetes:
    version: v1.35.3+k3s1
  profile: standard
  target:
    type: aws
    region: us-west-1
  nodes:
    controlPlane:
      count: 1
      instanceType: m5a.large
    workers:
      count: 2
      instanceType: m5a.large
  addons:
    cilium:
      enabled: true
    flux:
      enabled: true

petra capi create -f workload-dev.yaml

The CLI translates the Petra spec to a CAPI Cluster CR referencing the petra ClusterClass, applies it to the management cluster, and waits for provisioning to complete.

List and Manage

# List all workload clusters
petra capi list

# Get workload cluster kubeconfig
petra capi cluster-kubeconfig -f workload-dev.yaml

# Delete a workload cluster
petra capi delete -f workload-dev.yaml

# Tear down the management cluster
petra capi destroy -f management.yaml

ClusterClass

The Petra ClusterClass defines topology variables that map from the Petra spec:

Variable	Source	Default
region	spec.target.region	(required)
controlPlaneInstanceType	spec.nodes.controlPlane.instanceType	m5a.large
workerInstanceType	spec.nodes.workers.instanceType	m5a.large
profile	spec.profile	standard