This fork of the upstream k3s-ansible project is designed to stand up a K3s cluster on an Oxide rack. Our goal is to integrate Oxide’s Terraform provider into the deployment process while leaving the upstream Ansible playbooks untouched. This enables us to sync changes from upstream while adding our custom infrastructure logic.
-
Oxide Rack Infrastructure: A complete Terraform configuration under
./infra/oxideuses the Oxide provider to create the required infrastructure (project, VPC, subnets, instances, disks, and firewall rules) on an Oxide rack. -
Custom Inventory Generation: Terraform generates an Ansible inventory file (via templates in
./infra/oxide/templates) that splits hosts into server and agent groups. Additional variables are appended to support our custom K3s configuration (e.g. using the internal IP for the API endpoint and constructing TLS SANs). -
Kubeconfig Post-Processing: A separate Ansible playbook (
./infra/oxide/fix-kubeconfig.yml) is provided to update the generated kubeconfig file—replacing the internal IP with the external IP so remote access via kubectl works correctly. -
Makefile Automation: A Makefile is included with tasks to validate Terraform, bring up/destroy infrastructure, deploy the environment via Ansible, run kubectl checks, and more. This simplifies the overall deployment workflow.
-
Environment Variable Checks: The Makefile includes a target to ensure that essential environment variables (such as
OXIDE_HOSTandOXIDE_TOKEN) are set before deployment.
-
Terraform 1.x: Ensure Terraform is installed and available in your PATH.
-
Ansible 8.0+ (ansible-core 2.15+): The control node must have a recent version of Ansible installed.
-
kubectl: Installed on the control node for cluster interaction.
-
OXIDE_HOST and OXIDE_TOKEN: These environment variables must be set for the Oxide provider to authenticate. Use the provided Makefile target to check these.
-
Clone the repository and change into the directory:
git clone https://github.com/<your-username>/k3s-ansible.git
cd k3s-ansible-
Set the required environment variables:
export OXIDE_HOST=<your-oxide-host>
export OXIDE_TOKEN=<your-oxide-token>The Oxide-specific Terraform variables are defined in ./infra/oxide/terraform.tfvars. Verify or update these values as needed:
project_name = "<your-project-name"
vpc_name = "<your-vpc-name>"
vpc_dns_name = "<your-dns-name>"
vpc_description = "<your-description>"
instance_count = 3
memory = 4294967296
ncpus = 2
disk_size = 34359738368
ubuntu_image_id = "<your-ubuntu-image-id>"
public_ssh_key = "<your-ssh-pubkey>"
ansible_user = "ubuntu"
k3s_version = "v1.30.2+k3s1"
k3s_token = "changeme!"
server_count = 1The provided Makefile automates the deployment. Use these targets:
-
Full Deployment: This target runs validate, infra-up, deploy, fix-kubeconfig, and check in sequence.
make full-deploy-
Individual Targets:
-
Validate Terraform:
make validate -
Bring up infrastructure:
make infra-up -
Deploy with Ansible:
make deploy -
Fix kubeconfig:
make fix-kubeconfig -
Check cluster status:
make check -
Destroy infrastructure:
make destroy -
Verify environment variables:
make env-check
-
-
Upgrade: To upgrade the cluster, update the desired variables in
inventory.ymlorterraform.tfvarsand run the provided upgrade playbook (refer to upstream instructions). -
Destroy: Tear down the infrastructure with:
make destroy-
Testing has been primarily done with Ubuntu, but the K3s-Ansible upstream project has been built to deploy on Debian, RedHat, and SUSE as well.
-
We designed the fork to maintain upstream compatibility. Our modifications (such as inventory generation and kubeconfig post-processing) are implemented in separate files so that you can easily sync with upstream changes. Most of these are in ./infra/oxide, with the exception of this README and the Makefile.
-
Contributions or issues specific to the Oxide integration can be submitted via this fork’s GitHub repository.