rke2spray vs. Kubespray

Key takeaways

• The direct Ansible comparison is between the inventory, playbook, role, variable, tag, and validation contracts of Kubespray and rke2spray
• The bootstrap, runtime, and PKI differences between kubeadm and RKE2 belong to the Kubernetes execution-engine layer rather than the Ansible repository layer
• Kubespray is the upstream kubeadm-based implementation, while rke2spray is a separate Ansible implementation that translates its public API into an RKE2 lifecycle
• Shared cluster.yml, inventory groups, and role paths preserve names and operational intent without guaranteeing identical task bodies, variable semantics, or resulting state
• rke2spray provides only the reusable core and sample inventory, while jamie-kr-gitops owns the real jamie-kr inventory as consumer code
• Selection must consider both Ansible reuse and whether the team wants to own kubeadm component choice or RKE2 standardization

The comparison separates three layers

• The Ansible layer interprets inventory and commands before passing them to the execution-engine layer
• The engine difference causes the implementation differences in Ansible roles, variables, and tags
• The rke2spray findings follow the verified main code and docs/kubespray-api-compatibility.yml

Download source

jamie-kr-gitops owns the real inventory

• rke2spray and jamie-kr-gitops are separated as provider and consumer
  • rke2spray provides reusable playbooks, roles, plugins, defaults, and inventory/sample
  • jamie-kr-gitops owns real hosts, group variables, host variables, encrypted Vault values, and execution wrappers
• The dependency remains one-way, with jamie-kr-gitops selecting a pinned rke2spray release
  • The rke2spray core does not reference jamie-kr names, addresses, domains, or topology
  • jamie-kr-gitops invokes rke2spray through a Collection or pinned checkout

jamie-kr-gitops/
├── inventory/
│   └── jamie-kr/
│       ├── hosts.yml
│       ├── group_vars/
│       └── host_vars/
├── ansible/
│   └── rke2spray.rev
└── apps/
    └── ...
            │
            └── consumes a pinned rke2spray checkout

rke2spray/
├── cluster.yml
├── roles/
├── plugins/
└── inventory/
    └── sample/

• jamie-kr-gitops manages both Ansible IaC and Argo CD GitOps declarations for the environment
  • inventory/ and ansible/rke2spray.rev are reconciliation inputs used before the Kubernetes API exists
  • bootstrap/ and apps/ are reconciliation inputs used by Argo CD after the Kubernetes API exists
• After the inventory migration, commands run from the jamie-kr-gitops repository

make inventory-vault-check
make inventory-preflight
make cluster-converge
make gitops-bootstrap

• GitOps in the repository name describes the management model and does not exclude Ansible IaC ownership
  • Inventory is declarative cluster desired state consumed before the Kubernetes API exists
  • apps/ is platform desired state reconciled by Argo CD after the Kubernetes API exists
  • Both states can be reviewed as one environment release while rke2spray and Argo CD remain separate execution engines

The Ansible layer interprets the public API differently

• The central Ansible difference is which task graph a shared public name resolves to
  • Kubespray's kubernetes/kubeadm role executes kubeadm tasks
  • The rke2spray role at that path connects RKE2 bootstrap, node, and control-plane adapters
• A variable present in rke2spray does not automatically mean that the Kubespray feature is supported
  • container_manager: docker, container_manager: crio, kubeadm patches, and direct external CNI installation are currently rejected
  • Registry mirror, authentication, and TLS inputs that can be represented losslessly map to RKE2 registries.yaml
• Shared inventory and playbook names can reduce runbook translation cost without creating drop-in compatibility

The kubeadm layer describes Kubespray's execution model

• This layer describes the kubeadm-based cluster model automated by Kubespray, not the Ansible API difference between the two repositories

• The kubeadm model provides flexibility to select and replace Kubernetes components individually
• Its tradeoff is that the team owns compatibility, upgrade ordering, and failure boundaries across more combinations

The RKE2 layer describes rke2spray's execution model

• This layer describes the RKE2 distribution automated by rke2spray, not the Ansible interface difference

• The RKE2 model standardizes the runtime, PKI, and control-plane lifecycle around a release and service unit
• Its tradeoff is that requirements such as alternate runtimes, kubeadm phases, and external or custom CNIs become constraints outside the current standard contract
• A feature technically possible in RKE2 must be distinguished from one supported by the current rke2spray adapter

Engine differences translate into Ansible contracts

• An adapter translates intent without reproducing the original implementation
• Conditional means the public API is valid only when a datastore or topology prerequisite holds
• Unsupported can mean that the current rke2spray contract lacks a safe adapter, not that RKE2 can never implement the feature

Shared playbooks preserve intent only

• rke2spray adds health, snapshots, certificate rotation, and add-on plan, converge, and prune operations under extra_playbooks/
• Destructive removal, recovery, and ownership-transfer paths add confirmation and preflight gates

Selection evaluates Ansible reuse and the execution model together

• Moving an existing Kubespray cluster to rke2spray is a Kubernetes engine migration rather than an Ansible repository swap
  • Shared inventory groups do not convert current cluster state, PKI, datastore, or CNI state
  • Existing variables and custom roles must be audited against the supported, adapter, conditional, and unsupported classifications

Conclusion and next actions

• At the Ansible layer, Kubespray is the original implementation and rke2spray is an RKE2 adapter that preserves public names
• At the execution layer, kubeadm composes components while RKE2 integrates the distribution, service, and release lifecycle
• At the ownership layer, jamie-kr-gitops owns the real inventory while rke2spray remains the reusable installation engine
• A proof of concept should validate variable mappings, tag reachability, upgrades, node removal, and snapshot recovery in addition to running the shared cluster.yml entrypoint

Sources

• rke2spray Kubespray comparison
• rke2spray Kubespray API compatibility contract
• Kubespray repository and supported components
• Kubespray Ansible inventory
• Kubespray upgrades
• RKE2 architecture
• RKE2 server configuration
• RKE2 network options
• RKE2 backup and restore