Cluster API Operator

The Cluster API Operator is a Kubernetes Operator that enables cluster administrators to manage the lifecycle of Cluster API providers in a management cluster using a declarative approach.

Instead of using imperative commands, you use a declarative API to automate workflows, which is particularly useful for GitOps-driven environments. It extends the capabilities of the clusterctl CLI by providing more flexible configuration options and a way to interact with Cluster API components directly through Kubernetes resources.

The project uses a combination of Prow, GitHub Actions, and Google Cloud Build to manage continuous integration.

• Prow Jobs: Managed via Testgrid. You can view the dashboards for ProwJobs at https://testgrid.k8s.io/sig-cluster-lifecycle-cluster-api-operator.
• GitHub Actions: Handles linting, PR title verification, Dependabot updates, releases, and documentation (book) publishing.
• Google Cloud Build: Used for postsubmit image pushing tasks.

The Cluster API Operator provides several capabilities for managing Cluster API providers:

• Declarative API: Simplifies provider management and enables GitOps workflows.
• Provider Lifecycle Management: Facilitates provider upgrades and downgrades, making it suitable for distributed teams and CI pipelines.
• Air-gapped Support: Designed to support environments without direct access to GitHub or GitLab.
• Flexible Configuration: Leverages the controller-runtime configuration API for setting up Cluster API providers.
• Transparent Interaction: Provides an effective way to interact with various Cluster API components on the management cluster.

An InfrastructureProvider provisions the underlying computational resources required by a Cluster or its Machines (e.g., Virtual Machines, networking, etc.).

Examples include:

• Cloud Providers: AWS, Azure, Google.
• Bare Metal Providers: VMware, MAAS, metal3.io.

A BootstrapProvider is responsible for transforming a server into a functional Kubernetes node. Its primary responsibilities include:

1. Generating cluster certificates (if not explicitly specified otherwise).
2. Initializing the control plane and gating the creation of subsequent nodes until initialization is complete.
3. Joining both control plane and worker nodes to the cluster.

The Cluster API Operator defines several specialized provider types to manage different aspects of Cluster API. These types are namespaced, which allows for RBAC restrictions and the ability to run multiple versions of controllers simultaneously within the same management cluster by grouping them into different namespaces.

The primary provider types are:

• CoreProvider
• BootstrapProvider
• ControlPlaneProvider
• InfrastructureProvider
• AddonProvider
• IPAMProvider

The operator provides sensible defaults for fetching configurations based on the metadata.name of the provider. If you use standard Cluster API provider names such as aws, vsphere, azure, kubeadm, talos, or cluster-api, the operator will automatically fetch configuration from the corresponding official GitHub release URL without requiring an explicit fetchConfig block.

apiVersion: operator.cluster.x-k8s.io/v1alpha2
kind: InfrastructureProvider
metadata:
 name: vsphere
 namespace: capv-system
spec:
 version: v1.6.1
 configSecret:
   name: vsphere-variables

The Cluster API Operator manages six types of objects: CoreProvider, BootstrapProvider, ControlPlaneProvider, InfrastructureProvider, AddonProvider, and IPAMProvider.

Most provider types (Core, Bootstrap, ControlPlane, and Infrastructure) share the same API structure, utilizing ProviderSpec for the desired state and ProviderStatus for the observed state.

AddonProvider is unique in that it uses AddonProviderSpec and AddonProviderStatus instead of the shared types.

All provider CRDs are namespaced, which allows for RBAC enforcement and the ability to run multiple versions of different controllers in the same management cluster by grouping them into different namespaces.

The spec.patches field is the modern, flexible way to customize provider manifests. Unlike the legacy method, it allows for explicit targeting and supports both strategic merge patches and RFC 6902 JSON patches.

Each entry in spec.patches consists of a patch (the change to apply) and a target (the selector used to find the object).

# Strategic merge patch example
apiVersion: operator.cluster.x-k8s.io/v1alpha2
kind: CoreProvider
metadata:
  name: cluster-api
  namespace: capi-system
spec:
  patches:
    - patch: |
        apiVersion: v1
        kind: Service
        metadata:
          labels:
            test-label: test-value
      target:
        kind: Service