2023-11-10 21:11:59 +01:00
# Build a Kubernetes cluster using K3s via Ansible
2019-04-26 21:10:27 +02:00
2020-03-04 10:47:40 +01:00
Author: < https: / / github . com / itwars >
2023-11-10 21:11:59 +01:00
Current Maintainer: < https: / / github . com / dereknola >
2019-05-18 19:58:25 +02:00
2023-11-10 21:11:59 +01:00
Easily bring up a cluster on machines running:
2019-04-26 21:10:27 +02:00
2020-03-04 10:47:40 +01:00
- [X] Debian
2020-05-22 18:01:03 +02:00
- [X] Ubuntu
2023-11-10 21:11:59 +01:00
- [X] Raspberry Pi OS
- [X] RHEL Family (CentOS, Redhat, Rocky Linux...)
- [X] SUSE Family (SLES, OpenSUSE Leap, Tumbleweed...)
2023-11-08 19:31:51 +01:00
- [X] ArchLinux
2019-04-26 21:10:27 +02:00
2023-11-10 21:11:59 +01:00
on processor architectures:
2019-04-26 21:10:27 +02:00
- [X] x64
- [X] arm64
- [X] armhf
2020-03-04 10:47:40 +01:00
## System requirements
2019-04-26 21:10:27 +02:00
2023-11-10 21:11:59 +01:00
The control node must have Ansible 2.10.0+
2023-11-09 19:56:47 +01:00
2023-11-10 21:11:59 +01:00
All managed nodes in inventory must have:
2023-11-09 19:56:47 +01:00
- Passwordless SSH access
- Root access (or a user with equivalent permissions)
2023-11-10 21:11:59 +01:00
It is also recommended that all managed nodes disable firewalls and swap. See [K3s Requirements ](https://docs.k3s.io/installation/requirements ) for more information.
2019-04-26 21:10:27 +02:00
## Usage
2023-01-30 19:46:09 +01:00
First copy the sample inventory to `inventory.yml` .
2020-06-06 10:52:12 +02:00
```bash
2023-01-30 19:46:09 +01:00
cp inventory-sample.yml inventory.yml
2020-06-06 10:52:12 +02:00
```
2023-01-30 19:46:09 +01:00
Second edit the inventory file to match your cluster setup. For example:
2020-03-04 10:47:40 +01:00
```bash
2023-01-30 19:46:09 +01:00
k3s_cluster:
children:
server:
hosts:
192.16.35.11
agent:
hosts:
192.16.35.12
192.16.35.13
```
2019-04-26 21:10:27 +02:00
2023-01-30 19:46:09 +01:00
If needed, you can also edit `vars` section at the bottom to match your environment.
2019-04-26 21:10:27 +02:00
2023-01-30 19:46:09 +01:00
If multiple hosts are in the server group the playbook will automatically setup k3s in HA mode with embedded etcd.
2023-11-09 00:19:13 +01:00
An odd number of server nodes is required (3,5,7). Read the offical documentation below for more information and options.
2023-01-30 19:46:09 +01:00
https://rancher.com/docs/k3s/latest/en/installation/ha-embedded/
2023-11-10 21:11:59 +01:00
Setting up a loadbalancer or VIP beforehand to use as the API endpoint is possible but not covered here.
2019-04-26 21:10:27 +02:00
2020-06-06 10:52:12 +02:00
2019-04-26 21:10:27 +02:00
Start provisioning of the cluster using the following command:
2020-03-04 10:47:40 +01:00
```bash
2023-01-30 19:46:09 +01:00
ansible-playbook playbook/site.yml -i inventory.yml
2019-04-26 21:10:27 +02:00
```
2023-11-09 19:56:47 +01:00
## Upgrading
2023-11-10 21:11:59 +01:00
A playbook is provided to upgrade K3s on all nodes in the cluster. To use it, update `k3s_version` with the desired version in `inventory.yml` and run:
2023-11-09 19:56:47 +01:00
```bash
ansible-playbook playbook/upgrade.yml -i inventory.yml
```
2019-05-18 19:58:25 +02:00
## Kubeconfig
2023-11-10 21:11:59 +01:00
After successful bringup, the kubeconfig of the cluster is copied to the control node and set as default (`~/.kube/config`).
2023-11-09 00:19:13 +01:00
Assuming you have [kubectl ](https://kubernetes.io/docs/tasks/tools/#kubectl ) installed, you to confirm access to your **Kubernetes** cluster use the following:
2020-03-04 10:47:40 +01:00
```bash
2023-02-02 18:57:02 +01:00
kubectl get nodes
2020-03-04 10:47:40 +01:00
```
2023-11-09 00:19:13 +01:00
## Local Testing
2023-11-10 21:11:59 +01:00
A Vagrantfile is provided that provision a 5 nodes cluster using Vagrant (LibVirt or Virtualbox as provider). To use it:
2023-11-09 00:19:13 +01:00
```bash
vagrant up
```
2023-11-10 21:11:59 +01:00
By default, each node is given 2 cores and 2GB of RAM and runs Ubuntu 20.04. You can customize these settings by editing the `Vagrantfile` .
## Need More Features?
This project is intended to provide a "vanilla" K3s install. If you need more features, such as:
- Private Registry
- Advanced Storage (Longhorn, Ceph, etc)
- External Database
- External Load Balancer or VIP
- Alternative CNIs
See these other projects:
- https://github.com/PyratLabs/ansible-role-k3s
- https://github.com/techno-tim/k3s-ansible
- https://github.com/jon-stumpf/k3s-ansible
- https://github.com/alexellis/k3sup