rancher/cluster-api-provider-rke2

1. This repository is a Cluster API provider for RKE2, split into two independent provider surfaces: a Bootstrap Provider under bootstrap/ and a Control Plane Provider under controlplane/. Both are Kubernetes controllers that watch Cluster API custom resources and reconcile generated machine bootstrap data or control plane state.

2. The bootstrap side owns RKE2Config and RKE2ConfigTemplate APIs in bootstrap/api/v1beta1 and bootstrap/api/v1beta2. Its controller logic lives in bootstrap/internal/controllers, and its main job is to turn user-specified config into machine bootstrap payloads for joining RKE2 nodes.

3. The control plane side owns RKE2ControlPlane and RKE2ControlPlaneTemplate APIs in controlplane/api/v1beta1 and controlplane/api/v1beta2. Its controller logic in controlplane/internal/controllers manages the desired control plane size, lifecycle, remediation, status, and update behavior for RKE2 control plane machines.

4. A major architectural boundary is versioning. Both providers expose parallel v1beta1 and v1beta2 API packages with conversion code, deepcopy generation, and webhook validation/defaulting. The repo is structured to support cross-version compatibility while keeping provider-specific behavior isolated.

5. The bootstrap data path goes through helper packages in bootstrap/internal/cloudinit and bootstrap/internal/ignition. These generate the actual node initialization material, including cloud-init and ignition/butane output, before it is handed back to Cluster API for use by infrastructure machines.

6. The control plane data path is centered on pkg/rke2 plus pkg/capi helpers. pkg/rke2 contains RKE2-specific logic for control plane configuration, registries, workload cluster interaction, etcd handling, and machine filtering. pkg/capi contains reusable Cluster API integration code such as runtime client wrappers, extension config handling, patch utilities, in-place upgrade support, and registry/hooks helpers.

7. Several shared utility packages form the lower-level service layer for both providers: pkg/kubeconfig for connecting to clusters, pkg/secret for certificate handling, pkg/locking for coordinating control-plane initialization, pkg/proxy for transport/proxying, pkg/registration for node registration behavior, and pkg/etcd for etcd client and cluster state logic.

8. The control plane controller has additional internal submodules that map closely to reconciliation responsibilities: scale management, status computation, remediation, lifecycle hooks, and in-place update coordination. This separation suggests the controller orchestrates multiple policy decisions rather than being a single linear reconcile loop.

9. The repo is built and deployed as two controller images/managers, one for bootstrap and one for control plane. Each side has its own main.go, config/ tree, CRDs, RBAC, webhook manifests, and default Kustomize overlays under bootstrap/config and controlplane/config.

10. Webhooks and CRDs are first-class architecture components. Both providers define webhook validation/defaulting logic in the API packages, and the generated manifests in config/crd and config/webhook wire certificate injection and service endpoints for admission control.

11. The repository also contains a strong test and validation layer. Unit tests are spread through controller, API, and utility packages; envtest-based suites validate webhook and controller behavior; and test/e2e contains full integration scenarios like cluster class workflows, upgrades, pivoting, remediation, and external datastore support.

12. Supporting infrastructure includes documentation, examples, and image-building assets. docs/ hosts the user and developer book, examples/ provides cluster templates for multiple infrastructure providers, and image-builder/ plus bootstrap/ support producing RKE2 node images and bootstrap artifacts for air-gapped or specialized deployments.

13. Operationally, the controllers depend on Kubernetes APIs, Cluster API CRDs, admission webhooks, and generated manifests rather than external SaaS services. The main runtime boundary is the management cluster: controllers reconcile management-cluster custom resources and drive changes into workload cluster machines and control plane state.

14. For an architecture diagram, the core flow is: user submits Cluster API provider CRs and templates -> webhooks validate/default -> bootstrap and control plane controllers reconcile -> helper packages generate config, cloud-init/ignition, kubeconfigs, and RKE2-specific cluster operations -> Cluster API and infrastructure providers consume the results to create/update machine and cluster resources.