💾 Ansible K3s Cluster Deployment

Automated deployment and management of a K3s Kubernetes cluster using Ansible. This project enables easy setup and teardown of a multi-node K3s cluster, connecting to an external database, and dedicated control plane and agent nodes.

✨ Features

• Automated K3s cluster deployment and uninstallation
• Multi-node support with control plane and agent nodes
• External database integration
• Comprehensive templating for K3s server and agent configurations
• Detailed status reporting and health checks
• Idempotent operations - safe to re-run

🚀 Quick Start

1. Configure your inventory and variables (see Configuration section)

2. Install K3s cluster:

   ansible-playbook -i hosts k3s-install.yaml -K

3. Uninstall K3s cluster (if needed):

   ansible-playbook -i hosts k3s-uninstall.yaml -K

🔧 Configuration

1. Configure your inventory in hosts:

   [control_plane]
   cp1 ansible_host=192.168.1.2
   cp2 ansible_host=192.168.1.3
   
   [agents]
   agent1 ansible_host=192.168.1.4
   agent2 ansible_host=192.168.1.5

2. Set K3s version in group_vars/all.yaml:

   k3s_version: "v1.31.5+k3s1"

3. Configure K3s server settings in templates/k3s-server-config.yaml.j2:

   • Uncomment and set values as needed
   • Permanent flags (cannot be changed after first boot): datastore-endpoint, cluster-cidr, service-cidr, flannel-backend, token, etc.
   • CNI options: Set flannel-backend: "none" to use Cilium or Calico instead of Flannel
   • Component flags: Disable traefik, servicelb, etc. as needed

4. Configure K3s agent settings in templates/k3s-agent-config.yaml.j2:

   • Uncomment and set values as needed
   • Configure server and token to join the cluster

5. (Optional) For external etcd with TLS, place certificates in certs/ directory:

   certs/
   ├── etcd-ca.crt
   ├── apiserver-etcd-client.crt
   └── apiserver-etcd-client.key
   

   Note: The client certificate must have Extended Key Usage (EKU) set to Client Authentication (clientAuth).

   These will be automatically copied to /etc/rancher/k3s/certs/ on control plane nodes.

🧹 CNI Cleanup Script

If you have previously installed K3s or another Kubernetes distribution, there may be leftover CNI files (Calico, Flannel, Cilium) that can cause conflicts with a new installation.

A cleanup script rm_cni.sh is provided to find and remove these files. This functionality is intentionally not built into the Ansible playbook due to the risk of accidental multiple file deletions across the filesystem.

Usage:

# Copy the script to each node and run as root
sudo ./rm_cni.sh

The script will:

1. Search the entire filesystem for files containing calico, flannel, or cilium
2. Display a numbered list of found files
3. Prompt for action:
   • a - Delete all files (with confirmation)
   • 1,3,5 - Exclude specific file numbers from deletion
   • e - Exit without deleting

Note: Run this script on each node before running the K3s installation playbook if you suspect leftover CNI files from previous installations.

📝 Directory Structure

ansible-k3s/
├── certs/                              # (Optional) etcd TLS certificates
│   ├── etcd-ca.crt
│   ├── apiserver-etcd-client.crt
│   └── apiserver-etcd-client.key
├── group_vars/
│   └── all.yaml                        # K3s version configuration
├── templates/
│   ├── k3s-server-config.yaml.j2       # K3s server configuration template
│   └── k3s-agent-config.yaml.j2        # K3s agent configuration template
├── hosts                               # Ansible inventory file
├── k3s-install.yaml                    # Cluster installation playbook
├── k3s-uninstall.yaml                  # Cluster uninstallation playbook
├── rm_cni.sh                           # CNI cleanup script (run manually per node)
├── LICENSE
└── README.md

🔍 Health Check

1. Check node status:

   kubectl get nodes

2. Check cluster health:

   kubectl get --raw /healthz

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

If you encounter any issues or need support, please file an issue on the GitHub repository.

📄 License

This project is licensed under the GNU GENERAL PUBLIC LICENSE v3.0 - see the LICENSE file for details.