How kubernetes-sigs/cluster-api-provider-azure works
Main Components
• CRDs / API Definitions: Represented by the “api” directory (with versions v1alpha1 and v1beta1). These define the objects (e.g., AzureCluster, AzureManagedCluster, AzureMachinePool, etc.) that are managed declaratively.
• Controllers / Reconcilers: Found in the “controllers” directory; these are the control loops that monitor CRD state and reconcile desired against actual state.
• Azure Integration and Abstraction Layer: This includes the “azure” package and its submodules (such as converters, scopes, services, and clients) that encapsulate the interactions with the Azure APIs – managing things like virtual machines, load balancers, networks, disks, and other cloud resources.
• Kubernetes Manifests and Operator Deployment: Represented by the “config” and “templates” directories, providing deployment manifests (manager, webhook, CRDs) and various cluster templates (“flavors”) for different deployment scenarios.
• Supporting Libraries & Utilities: Under “pkg”, “util”, and “hack”, providing common functionality such as caching, logging, version handling, and reconciliation helpers.
• Testing / Mocks: Test directories and mocks (test, exp, internal/test) that support validation of controllers and integration with Azure APIs.
Relationships and Interactions
• The Kubernetes API Server (external to CAPZ) holds the desired state via CRDs.
• Controllers continuously watch these CRDs. When a change is detected, these controllers invoke reconciliation loops to ensure the actual state in Azure matches the declared state.
• The Controllers interact with the Azure integration layer; this layer abstracts the creation, updating, and deletion of Azure resources. It uses a set of specialized components (clients, converters, scopes) to map Kubernetes state to Azure operations.
• The Azure integration layer communicates with external Azure cloud services through REST APIs.
• In addition, there is automated observability (e.g., logging, telemetry, metrics) inside the CAPZ controllers, as seen in packages under “pkg/ot” and “util/tele”.
Architectural Patterns and Principles
• Reconciler Pattern: Central to the design, with dedicated controllers for different resource kinds (clusters, machine pools, etc.).
• Separation of Concerns: Clear division between CRD definitions, controller logic, and Azure service integrations.
• Modularity and Extensibility: The use of distinct directories for API, controllers, Azure-specific functions, and external templates supports a modular design and extensibility.
• Testability: The presence of mocks and a rich testing framework to consistently validate each component.
Relevant Technologies, Frameworks, and Libraries
• Golang as the programming language.
• Kubernetes APIs, Custom Resource Definitions (CRDs), and controller-runtime libraries.
• Azure Go SDK or custom REST client abstractions for Azure interactions.
• Standard Kubernetes configuration (YAML manifests) and kustomize for managing deployments and templates.
• Testing frameworks like Ginkgo/Gomega, and automated CI workflows (as visible in the .github/workflows directory).
Additional Suggestions
• Annotations explaining key responsibilities (e.g., “Reconciler updates resource state”, “Azure service client manages VM lifecycle”).