Architecture and execution model

How Kubespray public paths and variables translate into the RKE2 server and agent model.

Core summary

Shared Playbook, Role, and Inventory names preserve operational intent.
The actual bootstrap uses RKE2 servers, agents, and bundled containerd instead of kubeadm.
A public Role performs a native action, an RKE2 adapter action, or an explicit preflight failure.
Embedded etcd is the default; a separate etcd group selects the external datastore boundary.
A matching name does not guarantee identical Kubespray task bodies or resulting state.

Concern	Kubespray-compatible shape	RKE2 execution meaning
Entrypoint	Root Playbook names	Internal lifecycle orchestration
Roles	Public Role paths and tags	Replaced kubeadm and kubelet tasks
Targets	Inventory group names	Server and agent role resolution
Configuration	`kube_version` and CNI variables	RKE2 config and release locks
AddOns	`kubernetes-apps` boundary	RKE2 `HelmChart` or manifest

Path	Responsibility
`cluster.yml`, `scale.yml`, `upgrade-cluster.yml`	Kubespray-shaped root API
`playbooks/`	RKE2 lifecycle orchestration
`roles/`	Public Roles and RKE2 adapters
`inventory/sample/`	Reusable examples without secrets
`extra_playbooks/`	Health, snapshot, certificate, and AddOn operations
`docs/kubespray-api-compatibility.yml`	Canonical mappings and exceptions
`KUBESPRAY_BASELINE`	Pinned upstream commit

A root Playbook imports the matching lifecycle from playbooks/.
kubespray_defaults normalizes Kubespray variables and RKE2 extensions.
validate_inventory checks topology, versions, runtime, and raw-config conflicts.
Public Roles run native tasks, adapters, or explicit failures.
The lifecycle verifies services, the API, and Node readiness.

kubernetes/kubeadm is an RKE2 bootstrap adapter, not a kubeadm executor.
kubernetes/control-plane manages rke2-server and API readiness.
kubernetes/node manages RKE2 configuration and the agent lifecycle.
container-engine manages the bundled-containerd boundary rather than installing a standalone runtime.
etcd chooses embedded or external datastore behavior from topology.

Treat rke2spray as an adapter that translates a public operational shape into RKE2, not as a task-for-task Kubespray copy.
Determine support from Compatibility and preflight results, not from path existence alone.