How kubernetes-sigs/cluster-api works
Main Components
• API & CRD Layer: Represent the custom resource definitions defined in the “api”, “internal/apis”, and “exp/api” directories. This layer is the interface for the cluster, machine, clusterclass, and add-on objects.
• Controllers and Control Loops: Highlight the various controllers found in directories like “controllers”, “internal/controllers”, “controlplane”, “controllers/external”, and the migration or topology reconcilers. These components implement the reconciliation loops that ensure the desired state of clusters.
• Webhooks: Include the webhook components (under “webhooks” and “internal/webhooks”) that enforce validations, conversions, and admission control.
• Providers & Extensions: Show the extension points for infrastructure, bootstrap, and control plane providers. These are built on top of core APIs and include provider-specific implementations (e.g., in “bootstrap”, “cmd/clusterctl”, and “internal/contract”) that enable integration with AWS, Azure, vSphere, or other environments.
• Configuration & Deployment: Illustrate the manifest management and deployment configurations from directories such as “config”, “docs”, and “hack” that support environment setup, release generation, and CI/CD workflows.
• Testing & Observability: Optionally include the test directories (like “test”, “internal/test”, “hack/observability”) and utility packages that provide integration tests, logging, and metrics for the controllers.
Relationships and Interactions
• Connections between webhooks and the API layer for validation and conversion, ensuring data consistency.
• How provider-specific modules (bootstrap, control plane, infrastructure providers) interact with the controllers to manage external underlying systems (like VMs, load balancers, networking resources).
• If desired, include a feedback loop where monitoring/observability components gather data from controllers and infrastructure to feed back into higher-level dashboards or logging.
Architectural Patterns and Design Principles
• The architecture follows a declarative model where the desired state (expressed as CRDs) is continuously reconciled by controllers. Emphasize this control loop approach.
• The layered design – splitting API definitions, controllers, tooling, and provider integrations – should be clearly visible.
• That extensibility is key: multiple “provider” integrations and experimental (exp/) components mean the ecosystem is pluggable.