Cluster API v1beta1: Production-Ready Declarative Cluster Management

Introduction

In late 2021, Cluster API reached a major milestone with the release of v1beta1, marking the project’s transition from experimental alpha to production-ready. This release introduced ClusterClass for template-based cluster definitions and Managed Topologies for declarative cluster lifecycle management, fundamentally changing how teams could standardize and scale Kubernetes cluster operations.

This mattered because v1beta1 represented the first stable API that teams could rely on for production workloads. The introduction of ClusterClass solved a critical problem: how to define consistent cluster configurations across environments without duplicating YAML. Managed Topologies enabled true declarative cluster management, where cluster lifecycle (creation, upgrades, scaling) could be managed through simple spec updates.

Historical note: v1beta1 was released in October 2021, following v1alpha4. The beta designation signaled API stability and production readiness, with a commitment to backward compatibility within the beta API version.

What Made v1beta1 Production-Ready

API Stability Commitment

v1beta1 introduced a stability guarantee: no breaking changes within the v1beta1 API version. This meant teams could adopt Cluster API with confidence that their cluster definitions would continue to work as the project evolved.

Backward Compatibility: v1beta1 resources remain compatible across minor versions.
Deprecation Policy: Clear deprecation timelines for any future changes.
Migration Paths: Well-documented migration guides for future API versions.
Long-Term Support: Beta APIs receive extended support compared to alpha.

Provider Maturity

By 2021, infrastructure providers had reached production maturity:

AWS (CAPA): Production-ready with comprehensive AWS service integration.
Azure (CAPZ): Strong feature parity and production deployments.
GCP (CAPG): Stable and feature-complete.
vSphere (CAPV): Mature on-premises support.
Docker (CAPD): Robust testing and development experience.
Metal3 (CAPM3): Production-ready bare metal support.

ClusterClass: Template-Based Cluster Definitions

The Problem ClusterClass Solved

Before ClusterClass, teams had to duplicate cluster definitions for each environment:

# Production cluster
apiVersion: cluster.x-k8s.io/v1alpha4
kind: Cluster
metadata:
  name: prod-cluster
spec:
  infrastructureRef:
    kind: AWSCluster
    name: prod-cluster
  # ... repeated configuration

---
# Staging cluster (duplicated config)
apiVersion: cluster.x-k8s.io/v1alpha4
kind: Cluster
metadata:
  name: staging-cluster
spec:
  infrastructureRef:
    kind: AWSCluster
    name: staging-cluster
  # ... same configuration, different values

This led to:

Configuration Drift: Manual changes causing inconsistencies.
Maintenance Burden: Updates required across multiple cluster definitions.
Error-Prone: Copy-paste errors and missed updates.

ClusterClass Solution

ClusterClass provides a template-based approach to cluster definitions:

apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
metadata:
  name: standard-cluster-class
spec:
  infrastructure:
    ref:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: AWSClusterTemplate
      name: standard-aws-template
  controlPlane:
    ref:
      apiVersion: controlplane.cluster.x-k8s.io/v1beta1
      kind: KubeadmControlPlaneTemplate
      name: standard-controlplane-template
  workers:
    machineDeployments:
    - class: default-worker
      template:
        metadata:
          labels:
            pool: default
        spec:
          infrastructure:
            ref:
              apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
              kind: AWSMachineTemplate
              name: standard-worker-template

Creating Clusters from ClusterClass

With ClusterClass, creating clusters becomes simple:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: prod-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 3
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 5
        name: worker-pool-1

Benefits:

Consistency: All clusters use the same template.
Simplicity: Minimal cluster definition required.
Maintainability: Update ClusterClass to update all clusters.
Standardization: Enforce organizational standards.

Managed Topologies: Declarative Cluster Lifecycle

What Are Managed Topologies?

Managed Topologies enable declarative cluster lifecycle management through the topology field in Cluster resources. With managed topologies, you can:

Create clusters by specifying desired state.
Upgrade clusters by updating the version field.
Scale clusters by updating replica counts.
Modify configurations by updating topology settings.

Managed Topology Example

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: my-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 3
      metadata:
        labels:
          environment: production
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 5
        name: worker-pool-1
        metadata:
          labels:
            pool: default
      - class: gpu-worker
        replicas: 2
        name: gpu-pool-1
        metadata:
          labels:
            pool: gpu

Upgrading with Managed Topologies

Upgrading a cluster becomes a simple spec update:

# Upgrade cluster to v1.23.0
kubectl patch cluster my-cluster --type merge -p '{
  "spec": {
    "topology": {
      "version": "v1.23.0"
    }
  }
}'

Cluster API handles the upgrade process automatically:

Control Plane Upgrade: Upgrades control plane nodes first.
Worker Upgrade: Upgrades worker nodes after control plane.
Rolling Update: Uses rolling updates to minimize downtime.
Health Checks: Validates cluster health during upgrade.

Scaling with Managed Topologies

Scaling is equally simple:

# Scale worker pool
kubectl patch cluster my-cluster --type merge -p '{
  "spec": {
    "topology": {
      "workers": {
        "machineDeployments": [{
          "class": "default-worker",
          "replicas": 10,
          "name": "worker-pool-1"
        }]
      }
    }
  }
}'

Multi-Cluster Management Patterns

Pattern 1: Environment Standardization

Use ClusterClass to standardize clusters across environments:

# Development cluster
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: dev-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 1  # Single control plane for dev
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 2  # Fewer workers for dev

---
# Production cluster
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: prod-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 3  # HA control plane for prod
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 10  # More workers for prod

Pattern 2: Regional Clusters

Manage clusters across regions with consistent configurations:

# US West cluster
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: us-west-2-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 3
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 5

---
# EU West cluster
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: eu-west-1-cluster
spec:
  clusterClassRef:
    name: standard-cluster-class
  topology:
    version: v1.22.0
    controlPlane:
      replicas: 3
    workers:
      machineDeployments:
      - class: default-worker
        replicas: 5

Pattern 3: GitOps Integration

ClusterClass and managed topologies work seamlessly with GitOps:

# Cluster definitions in Git
clusters/
├── production/
│   ├── cluster.yaml
│   └── clusterclass.yaml
├── staging/
│   ├── cluster.yaml
│   └── clusterclass.yaml
└── development/
    ├── cluster.yaml
    └── clusterclass.yaml

# ArgoCD syncs to management cluster
# Cluster API provisions and manages clusters

Provider Maturity in v1beta1

AWS Provider (CAPA)

Production Ready: Used in production by major organizations.
Feature Complete: Comprehensive AWS service integration.
Documentation: Extensive documentation and examples.
Support: Active community and commercial support options.

Azure Provider (CAPZ)

Feature Parity: Strong alignment with CAPA.
Azure Integration: Deep integration with Azure services.
Managed Disks: Production-ready managed disk support.
Identity: Azure AD integration patterns.

GCP Provider (CAPG)

GCP Services: Comprehensive GCP service integration.
Service Accounts: Production-ready service account management.
Networking: GCP networking best practices.
Stability: Proven reliability in production.

GitOps Integration Patterns

ArgoCD Integration

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: workload-clusters
spec:
  source:
    repoURL: https://github.com/org/cluster-definitions
    path: clusters/production
  destination:
    server: https://management-cluster:6443
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

FluxCD Integration

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: workload-clusters
spec:
  sourceRef:
    kind: GitRepository
    name: cluster-definitions
  path: ./clusters/production
  interval: 5m
  prune: true

Practical Considerations

ClusterClass Design

Reusability: Design ClusterClass for multiple use cases.
Flexibility: Allow customization through topology overrides.
Standards: Enforce organizational standards through templates.
Versioning: Version ClusterClass for controlled updates.

Managed Topology Best Practices

Version Management: Pin Kubernetes versions initially, then upgrade gradually.
Scaling Strategy: Plan scaling based on workload requirements.
Upgrade Windows: Schedule upgrades during maintenance windows.
Testing: Test topology changes in non-production first.

Management Cluster Requirements

High Availability: HA management cluster for production.
Resources: Adequate resources for Cluster API controllers.
Network Access: Access to cloud provider APIs and workload clusters.
Backup: Regular backups of management cluster state.

Migration from v1alpha4 to v1beta1

Migration Strategy

Backup Resources: Export all Cluster API resources.
Update API Versions: Update manifests to v1beta1.
Update Providers: Upgrade infrastructure providers to v1beta1.
Test Migration: Validate in non-production first.
Gradual Rollout: Migrate clusters incrementally.

Migration Example

# Check migration readiness
clusterctl upgrade plan

# Perform migration
clusterctl upgrade apply

# Verify migration
kubectl get clusters
kubectl get clusterclasses

Comparison: v1alpha4 vs v1beta1

Feature	v1alpha4	v1beta1
API Stability	Alpha (breaking changes)	Beta (stable)
ClusterClass	Not available	Available
Managed Topologies	Not available	Available
Production Ready	Approaching	Yes
Provider Maturity	Growing	Mature
Documentation	Improving	Comprehensive

Caveats & Limitations

Learning Curve: ClusterClass and managed topologies require understanding new concepts.
Provider Support: Not all providers support all features immediately.
Migration Effort: Migration from v1alpha4 requires planning and testing.
Tooling: Some tooling still evolving with new features.

Common Issues

ClusterClass Not Found: Ensure ClusterClass exists before creating clusters.
Topology Validation: Validate topology settings before applying.
Provider Compatibility: Verify provider versions support v1beta1 features.
Upgrade Failures: Monitor upgrade progress and have rollback plans.

Conclusion

Cluster API v1beta1 in late 2021 marked a transformative milestone for Kubernetes cluster management. The introduction of ClusterClass and Managed Topologies solved fundamental problems in cluster standardization and lifecycle management, making Cluster API truly production-ready.

The beta designation signaled API stability and long-term support, giving teams confidence to adopt Cluster API for production workloads. The template-based approach of ClusterClass eliminated configuration duplication, while managed topologies enabled declarative cluster lifecycle management through simple spec updates.

For organizations managing multiple clusters, v1beta1 provided the foundation for scalable, consistent, and maintainable cluster operations. The combination of API stability, provider maturity, and powerful new features made Cluster API a compelling choice for multi-cloud and multi-cluster deployments.

The patterns established in v1beta1—ClusterClass templates, managed topologies, and GitOps integration—would become standard practices as Cluster API continued to evolve. v1beta1 was not just a version number; it was the moment Cluster API became a production-grade infrastructure management platform.

Table of Contents