# rancher/cluster-api-provider-rke2 architecture

> Architecture diagram of the GitHub repository rancher/cluster-api-provider-rke2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rancher/cluster-api-provider-rke2
- Repository: https://github.com/rancher/cluster-api-provider-rke2

## Overview

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.

Main entry points: [`controlplane/internal/controllers`](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/internal/controllers) (CP Ctrl), [`bootstrap/internal/controllers`](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/controllers) (Bootstrap Ctrl), [`bootstrap/api`](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/api) (Bootstrap API), [`controlplane/api`](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/api) (Control Plane API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap Provider"]
  node_bootstrap_api["Bootstrap API<br/>CRD versions"]
  node_bootstrap_controller["Bootstrap Ctrl<br/>reconciler"]
  node_bootstrap_render["Node Init<br/>renderers"]
  node_bootstrap_ignition["Ignition<br/>butane adapter"]
  node_bootstrap_config["Bootstrap Manifests<br/>deploy manifests"]
end

subgraph group_controlplane["Control Plane Provider"]
  node_controlplane_api["Control Plane API<br/>CRD versions"]
  node_controlplane_controller["CP Ctrl<br/>reconciler"]
  node_cp_scale["Scale<br/>capacity logic<br/>[scale.go]"]
  node_cp_status["Status<br/>condition synthesis<br/>[status.go]"]
  node_cp_remediation["Remediation<br/>health recovery<br/>[remediation.go]"]
  node_cp_inplace["In-place Updates<br/>update coordination<br/>[inplace.go]"]
  node_cp_lifecycle["Lifecycle Hooks<br/>hook handling<br/>[lifecycle_hook.go]"]
  node_controlplane_config["CP Manifests<br/>deploy manifests"]
  node_cp_util["CP Utilities<br/>ssa/hash helpers"]
end

subgraph group_pkg["Shared Packages"]
  node_pkg_rke2["RKE2 Logic<br/>domain services"]
  node_pkg_capi["CAPI Helpers<br/>integration helpers"]
  node_shared_utils["Shared Services<br/>cluster utilities"]
end

subgraph group_docs["Docs & Examples"]
  node_docs_examples["Docs & Examples<br/>book/templates/assets"]
end

node_runtime_manifests["Runtime Surfaces<br/>manager binaries<br/>[main.go]"]

node_bootstrap_config -->|"serves"| node_bootstrap_api
node_bootstrap_api -->|"watched by"| node_bootstrap_controller
node_bootstrap_controller -->|"builds"| node_bootstrap_render
node_bootstrap_render -->|"converts"| node_bootstrap_ignition
node_bootstrap_controller -->|"uses"| node_shared_utils
node_bootstrap_controller -->|"integrates"| node_pkg_capi
node_controlplane_config -->|"serves"| node_controlplane_api
node_controlplane_api -->|"watched by"| node_controlplane_controller
node_controlplane_controller -->|"orchestrates"| node_cp_scale
node_controlplane_controller -->|"orchestrates"| node_cp_status
node_controlplane_controller -->|"orchestrates"| node_cp_remediation
node_controlplane_controller -->|"orchestrates"| node_cp_inplace
node_controlplane_controller -->|"orchestrates"| node_cp_lifecycle
node_controlplane_controller -->|"uses"| node_pkg_rke2
node_controlplane_controller -->|"uses"| node_pkg_capi
node_pkg_rke2 -->|"uses"| node_shared_utils
node_pkg_rke2 -->|"uses"| node_pkg_capi
node_pkg_capi -->|"uses"| node_shared_utils
node_runtime_manifests -->|"deploys"| node_bootstrap_config
node_runtime_manifests -->|"deploys"| node_controlplane_config
node_docs_examples -->|"documents"| node_bootstrap_api
node_docs_examples -->|"documents"| node_controlplane_api
node_bootstrap_api -.->|"version-paired"| node_controlplane_api

click node_bootstrap_api "https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/api"
click node_bootstrap_controller "https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/controllers"
click node_bootstrap_render "https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/cloudinit"
click node_bootstrap_ignition "https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/ignition"
click node_bootstrap_config "https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/config"
click node_controlplane_api "https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/api"
click node_controlplane_controller "https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/internal/controllers"
click node_cp_scale "https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/scale.go"
click node_cp_status "https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/status.go"
click node_cp_remediation "https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/remediation.go"
click node_cp_inplace "https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/inplace.go"
click node_cp_lifecycle "https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/lifecycle_hook.go"
click node_controlplane_config "https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/config"
click node_cp_util "https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/internal/util"
click node_pkg_rke2 "https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg/rke2"
click node_pkg_capi "https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg/capi"
click node_shared_utils "https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg"
click node_runtime_manifests "https://github.com/rancher/cluster-api-provider-rke2/blob/main/bootstrap/main.go"
click node_docs_examples "https://github.com/rancher/cluster-api-provider-rke2/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap_api,node_bootstrap_controller,node_bootstrap_render,node_bootstrap_ignition,node_bootstrap_config toneBlue
class node_controlplane_api,node_controlplane_controller,node_cp_scale,node_cp_status,node_cp_remediation,node_cp_inplace,node_cp_lifecycle,node_controlplane_config,node_cp_util toneAmber
class node_pkg_rke2,node_pkg_capi,node_shared_utils toneMint
class node_docs_examples toneRose
class node_runtime_manifests toneNeutral
```

## Components

### Bootstrap Provider

RKE2 bootstrap API and controller surface

- [Bootstrap API](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/api): CRD versions · RKE2Config and RKE2ConfigTemplate versions, conversions, defaults, and validation · `bootstrap/api`
- [Bootstrap Ctrl](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/controllers): reconciler · Reconciles bootstrap configs into machine bootstrap data · `bootstrap/internal/controllers`
- [Node Init](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/cloudinit): renderers · Generates cloud-init, ignition, and butane output for node startup · `bootstrap/internal/cloudinit`
- [Ignition](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/internal/ignition): butane adapter · Transforms bootstrap content into ignition-compatible material · `bootstrap/internal/ignition`
- [Bootstrap Manifests](https://github.com/rancher/cluster-api-provider-rke2/tree/main/bootstrap/config): deploy manifests · Controller image, RBAC, CRDs, webhooks, and kustomize overlays · `bootstrap/config`

### Control Plane Provider

RKE2 control plane API and controller surface

- [Control Plane API](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/api): CRD versions · RKE2ControlPlane and RKE2ControlPlaneTemplate versions, conversions, defaults, and validation · `controlplane/api`
- [CP Ctrl](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/internal/controllers): reconciler · Orchestrates size, lifecycle, remediation, status, and update behavior · `controlplane/internal/controllers`
- [Scale](https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/scale.go): capacity logic · Maintains desired replicas and machine selection · `controlplane/internal/controllers/scale.go`
- [Status](https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/status.go): condition synthesis · Computes control plane readiness and rollout state · `controlplane/internal/controllers/status.go`
- [Remediation](https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/remediation.go): health recovery · Detects unhealthy machines and drives recovery actions · `controlplane/internal/controllers/remediation.go`
- [In-place Updates](https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/inplace.go): update coordination · Coordinates in-place machine updates and trigger logic · `controlplane/internal/controllers/inplace.go`
- [Lifecycle Hooks](https://github.com/rancher/cluster-api-provider-rke2/blob/main/controlplane/internal/controllers/lifecycle_hook.go): hook handling · Processes lifecycle hook state during reconciliation · `controlplane/internal/controllers/lifecycle_hook.go`
- [CP Manifests](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/config): deploy manifests · Controller image, RBAC, CRDs, webhooks, and kustomize overlays · `controlplane/config`
- [CP Utilities](https://github.com/rancher/cluster-api-provider-rke2/tree/main/controlplane/internal/util): ssa/hash helpers · Reusable utilities for server-side apply, hashing, and patch intent · `controlplane/internal/util`

### Shared Packages

Reusable domain and utility packages

- [RKE2 Logic](https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg/rke2): domain services · RKE2 control plane config, registries, workload cluster, etcd, and machine filtering · `pkg/rke2`
- [CAPI Helpers](https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg/capi): integration helpers · Cluster API runtime client, extension config, patch, in-place, registry, and hooks support · `pkg/capi`
- [Shared Services](https://github.com/rancher/cluster-api-provider-rke2/tree/main/pkg): cluster utilities · Kubeconfig, secret handling, locking, proxying, registration, and etcd support · `pkg`

### Docs & Examples

Documentation, examples, and image assets

- [Docs & Examples](https://github.com/rancher/cluster-api-provider-rke2/tree/main/docs): book/templates/assets · Documentation, examples, and image-building assets for operators and developers · `docs`

### Other components

- [Runtime Surfaces](https://github.com/rancher/cluster-api-provider-rke2/blob/main/bootstrap/main.go): manager binaries · Two controller binaries plus generated manifests and admission wiring · `bootstrap/main.go`

## Connections

- Bootstrap Manifests → Bootstrap API: serves · CRDs and webhooks are generated from bootstrap API types
- Bootstrap API → Bootstrap Ctrl: watched by · Validated bootstrap resources are reconciled into node bootstrap data
- Bootstrap Ctrl → Node Init: builds · Controller turns config into cloud-init or ignition payloads
- Node Init → Ignition: converts · Ignition helpers handle butane and ignition rendering
- Bootstrap Ctrl → Shared Services: uses · Bootstrap reconciliation relies on shared kubeconfig, secret, and etcd helpers
- Bootstrap Ctrl → CAPI Helpers: integrates · Bootstrap controller cooperates with Cluster API extension and patch helpers
- CP Manifests → Control Plane API: serves · CRDs and webhooks are generated from control plane API types
- Control Plane API → CP Ctrl: watched by · Validated control plane resources are reconciled into cluster state
- CP Ctrl → Scale: orchestrates · Scale logic manages desired replica count and machine selection
- CP Ctrl → Status: orchestrates · Status logic computes rollout and readiness conditions
- CP Ctrl → Remediation: orchestrates · Remediation logic handles unhealthy control plane machines
- CP Ctrl → In-place Updates: orchestrates · In-place update logic coordinates machine upgrades
- CP Ctrl → Lifecycle Hooks: orchestrates · Lifecycle hooks gate reconciliation transitions
- CP Ctrl → RKE2 Logic: uses · Core RKE2 domain logic powers control plane reconciliation
- CP Ctrl → CAPI Helpers: uses · Controller relies on Cluster API integration helpers
- RKE2 Logic → Shared Services: uses · RKE2 domain logic depends on cluster, secret, and etcd services
- RKE2 Logic → CAPI Helpers: uses · RKE2 logic composes CAPI runtime and patch utilities
- CAPI Helpers → Shared Services: uses · Cluster API helpers build on common transport and secret primitives
- Runtime Surfaces → Bootstrap Manifests: deploys · Bootstrap manager image, RBAC, and webhook wiring are packaged here
- Runtime Surfaces → CP Manifests: deploys · Control plane manager image, RBAC, and webhook wiring are packaged here
- Docs & Examples → Bootstrap API: documents · Documentation and examples describe bootstrap API usage
- Docs & Examples → Control Plane API: documents · Documentation and examples describe control plane API usage
- Bootstrap API → Control Plane API: version-paired · Parallel API versions share the repo-wide compatibility boundary