DOCSEARCHbyAlgolia
Submit Docs

Cluster API Documentation

repository·main·Indexed 26 days ago

https://github.com/kubernetes-sigs/cluster-api

A Kubernetes subproject providing declarative APIs and tooling to automate the provisioning, upgrading, and management of multiple Kubernetes clusters across various infrastructure environments. Includes documentation for the clusterctl CLI, provider extensibility, and internal utilities like metadata-version-validator and prowjob-gen.

Tokens
135.9K
Snippets
203
Records
774
Agent score
87%

What's inside Cluster API

  1. Overview of Kubeadm Based Control Plane Management

    main
    Cluster API manages Kubernetes control plane machines as a single unified concept. This management includes upgrading the control plane, scaling the number of control plane nodes, and modifying the underlying machine images (e.g., AMIs) for control plane nodes. The control plane managed includes the Kubernetes API server, scheduler, controller manager, DNS, proxy services, and the etcd data store.

  2. Overview of Kubernetes Cluster API

    main
    Cluster API (CAPI) is a Kubernetes sub-project that provides declarative APIs and tooling to automate the provisioning, upgrading, and operation of multiple Kubernetes clusters. It uses Kubernetes-style APIs and patterns to manage cluster lifecycles, allowing platform operators to define infrastructure (VMs, networks, load balancers, VPCs) and cluster configurations in a consistent, repeatable way across various environments (on-premises and cloud).

  3. Overview of clusterctl CLI

    main
    The clusterctl CLI tool manages the lifecycle of a Cluster API management cluster. It is designed to provide a quick start experience by automating the fetching and installation of YAML files that define provider components. It also enforces best practices for managing providers, helping users avoid misconfigurations and manage day 2 operations like upgrades.

  4. Overview of the CAPI Provider Operator

    main

    The CAPI Provider Operator is a solution designed to enable declarative management of the lifecycle of Cluster API and its providers within a management cluster. While the clusterctl CLI is optimized for Day 0 and Day 1 imperative operations, the Operator is intended for cluster administrators who want to use declarative approaches, such as GitOps workflows, to manage providers.

    Key benefits include:

    • Declarative Management: Enables GitOps workflows by replacing imperative CLI commands with a declarative API.
    • Controller Configuration: Leverages controller-runtime's component config to allow configuration of the controller manager and resource limits for provider deployments.
    • Improved Upgrades: Simplifies cluster upgrades by removing the need to re-supply all initial configuration information (previously required by clusterctl init) during the upgrade process.

  5. Overview of Runtime Hooks for Add-on Management

    main

    Runtime Hooks are a foundational mechanism in Cluster API designed to enable add-on orchestration (e.g., using Helm, ArgoCD, Flux, or kapp) in sync with the cluster lifecycle. These hooks allow external tools to plug into specific cluster events, such as:

    • Provisioning: Installing add-ons during the cluster creation workflow.
    • Upgrading: Managing add-on updates during cluster upgrades.
    • Deletion: Handling add-on cleanup or state management during cluster deletion.

    By using these hooks, an orchestration solution can trigger processes based on the current state of the cluster, such as starting an operation after a specific state is reached or blocking cluster-wide operations (like deletion) until the add-on lifecycle task is complete.

  6. Overview of the Cluster API testing framework

    main

    The Cluster API testing framework is a pluggable set of generic behavioral end-to-end (e2e) tests designed for Cluster API Providers. Instead of each provider implementing its own non-uniform testing logic, they can import this framework as a Go library to ensure their provider behaves according to Cluster API's expected standards.

    Key Characteristics:

    • Implementation: Built using the Ginkgo/Gomega behavioral testing framework.
    • Distribution: Distributed as a Go module (sigs.k8s.io/cluster-api). Providers import it as a standard dependency.
    • Scope: Focuses on generic Cluster API behaviors that span all providers (e.g., cluster lifecycle, machine management) rather than provider-specific edge cases.
    • Execution: Tests can be run in parallel and organized so providers can specify which tests to run (e.g., fast-focus for PR blocking vs. slow tests for periodic runs).
    • Not Conformance: This is not a conformance suite and does not produce a distributed binary like the Kubernetes conformance tool.

  7. Propagate taints from Cluster API to Kubernetes Nodes

    main

    This proposal introduces taints as a first-class citizen in Cluster API's core types. This allows users to declaratively manage Kubernetes Node taints through higher-level Cluster API resources such as Cluster, ClusterClass, MachineSet, MachineDeployment, and MachinePool.

    There are two propagation modes for taints:

    • Always: Taints are continuously reconciled and maintained on nodes.
    • OnInitialization: Taints are set once during node initialization and then left unmanaged.

    This feature enables reserving nodes for specific workloads (e.g., GPU or network functions) without relying on bootstrap provider-specific implementations or manual post-creation updates.

  8. Understand the Cluster API Repository Layout

    main

    The Cluster API repository is organized into several functional directories. Key directories include:

    • api/: Core CAPI types (e.g., Cluster, Machine, MachineSet) and their spec/status definitions.
    • bootstrap/: Reference implementation of the Kubeadm bootstrap provider (CABPK).
    • controlplane/: Reference implementation of the KubeadmControlPlane provider.
    • cmd/clusterctl/: Source code for the clusterctl CLI.
    • config/: Kubernetes manifests (Kustomize YAML) for CAPI components.
    • controllers/: Reconciler types that allow users to run CAPI controllers in external programs.
    • internal/: Private implementation details, including controller logic and webhooks not intended for direct external use.
    • util/: Shared utilities used across CAPI packages and providers.
    • feature/: Shared feature gate management implementation.
    • errors/: Standardized error types used by CAPI and its providers.
    • exp/: Experimental features that are unreliable until promoted to the main repository.

  9. Goals and Non-goals of Add-On Orchestration

    main

    Goals

    • Design a solution for orchestrating Cluster add-ons.
    • Leverage existing package management tools (like Helm) for repositories, templating, configuration, and lifecycle operations.
    • Make add-on management modular and pluggable via a Cluster API Add-on Provider model, similar to infrastructure and bootstrap providers.

    Non-goals

    • Implementing a new package management tool within CAPI.
    • Providing mechanisms to customize individual Kubernetes resources (e.g., Deployments, Services) within an add-on; add-ons are treated as opaque components.
    • Forcing users to use a specific package management tool.
    • Managing add-ons on the management cluster itself.

  10. Understand Managed Kubernetes API Design Approaches in CAPI

    main

    The Cluster API (CAPI) ecosystem considers different architectural patterns for representing Managed Kubernetes (like GKE, EKS, or AKS). There are two primary design approaches discussed in the proposals:

    1. Single Resource Kind (Combined Control Plane and Infrastructure)

    In this model, a single resource kind (e.g., GCPManagedControlPlane) represents both the managed control plane and the underlying cloud infrastructure.

    • Pros: Simple design with a single resource kind and controller.
    • Cons: Incompatible with ClusterClass (which expects separate ControlPlane and Infrastructure kinds); lacks separation of responsibilities; makes managed clusters look different from unmanaged clusters.
    • Historical Note: This was the original design used for EKS in CAPA.

    2. Two Resource Kinds (Separated Control Plane and Shared Infrastructure)

    This model follows the standard CAPI separation of concerns. A specific managed control plane kind (e.g., GCPManagedControlPlane) handles GKE-specific provisioning, while a general infrastructure kind (e.g., GCPCluster) handles the cloud operating infrastructure (networking, projects, etc.).

    • Pros: Works with ClusterClass; provides clear separation between infrastructure and the managed control plane; uses a single infrastructure kind regardless of whether the cluster is managed or unmanaged.
    • Cons: Increases complexity in the infrastructure controller, as it must differentiate between unmanaged and managed cluster workflows (e.g., deciding whether to create a load balancer or use a managed endpoint).

  11. New features in Cluster API v1.7.0

    main

    Cluster API v1.7.0 introduced several new features:

    • clusterctl: Added the k0smotron provider.
    • MachineDeployment: Added a MachineSetReady condition and implemented node tainting with PreferNoSchedule during rollouts.
    • MachineHealthCheck: Added an annotation to allow manually marking machines for remediation.
    • API: Enabled kubeadm feature gates mutation.
    • Control-plane: Allowed mutation of all fields that should be mutable.

  12. Understand Cluster API Core Concepts

    main

    Cluster API (CAPI) uses custom resources to manage the lifecycle of Kubernetes clusters. It follows a pattern similar to Kubernetes workloads (like Deployments or StatefulSets) but applied to infrastructure.

    Key architectural components include:

    • Management Cluster: The central Kubernetes cluster where CAPI and its providers run to manage workload clusters.
    • Workload Cluster (Cluster): The target Kubernetes cluster whose lifecycle is managed by CAPI.
    • Providers: Specialized components that extend CAPI functionality:
      • Infrastructure Provider: Provisions computational resources (e.g., VMs, networking) via providers like AWS, Azure, GCP, or vSphere.
      • Control Plane Provider: Manages the Kubernetes control plane (e.g., KubeadmControlPlane).
      • Bootstrap Provider: Turns a server into a Kubernetes node by generating initialization data (BootstrapData) and joining nodes to the cluster.