Deploy Kubernetes clusters (RKE2, K3s) and Rancher across AWS, GCP, Harvester, or your own nodes. This repo combines OpenTofu for infrastructure provisioning with Ansible for product deployment.
| I want to… | Guide |
|---|---|
| Deploy RKE2 on AWS | rke2-default-aws |
| Deploy RKE2 on my own nodes (BYO / on-premise) | rke2-default-byo |
| Deploy RKE2 in an airgap on AWS | rke2-airgap-aws |
| Deploy K3s on AWS | k3s-default-aws |
| Deploy K3s on my own nodes (BYO / on-premise) | k3s-default-byo |
| Install Rancher on an existing cluster | rancher-ha |
| Add a new cloud provider | adding-a-provider |
| See all guides | docs/guides/ |
Full RKE2 cluster + Rancher on AWS in three commands:
# 1. Configure tofu/aws/modules/cluster_nodes/terraform.tfvars (see guide)
# 2. Configure ansible/rke2/default/vars.yaml (see guide)
make all # provisions infra → deploys RKE2 → installs RancherFor an airgap deployment: make all ENV=airgap. For K3s: make all DISTRO=k3s.
See prerequisites first.
| Document | Description |
|---|---|
| Getting Started | Project overview, supported configurations, where to go next |
| Prerequisites | Tools, Python packages, cloud credentials, SSH keys |
| Architecture | How the Tofu and Ansible layers work together |
| Makefile Reference | All make targets, variables, and examples |
| Inventory Format | Ansible inventory schema for BYO and Tofu-generated inventories |
| Variables Reference | All Ansible variables across playbooks and roles |
| Troubleshooting | Common issues and fixes |
| FAQ | Frequently asked questions |
├── ansible/ # Product deployment (provider-agnostic)
│ ├── rke2/ # RKE2 playbooks (default, airgap)
│ ├── k3s/ # K3s playbooks (default)
│ ├── rancher/ # Rancher playbooks (HA, downstream)
│ └── roles/ # Reusable Ansible roles
│
├── tofu/ # Infrastructure provisioning
│ ├── aws/modules/ # AWS (cluster_nodes, airgap, ...)
│ ├── gcp/modules/ # GCP (elemental_nodes, ...)
│ └── harvester/modules/ # Harvester (vm, loadbalancer, ...)
│
├── docs/ # Documentation
│ ├── guides/ # End-to-end deployment guides
│ └── reference/ # Reference material
│
└── scripts/ # Helper scripts (inventory generation, etc.)
All are welcome and encouraged to contribute! Please keep changes generalized, easy to understand, and reusable.
- Follow the OpenTofu style guide and Ansible best practices
- New Ansible playbooks and Tofu modules must include a README with usage, inputs, outputs, and examples
- Reusable task collections should be Ansible roles
- Use variables for environment-specific values with descriptions
- Add yourself to CODEOWNERS for paths you own
If you're familiar with Terraform but not OpenTofu, see migrating from Terraform to Tofu — they are nearly identical.