From a2b96119f5ff9654b176effc7e8f55f96565cbb9 Mon Sep 17 00:00:00 2001 From: Derek Nola Date: Fri, 10 Nov 2023 12:11:59 -0800 Subject: [PATCH] Reword README (#245) * Add mention of other projects * Add gitattributes to fix language reporting in GH * Add debug playbook to gitignore * Add more info around what this project will not cover * Remove construction label, reword Signed-off-by: Derek Nola --- .gitattributes | 2 ++ .gitignore | 1 + README.md | 47 +++++++++++++++++++++++++++++++---------------- 3 files changed, 34 insertions(+), 16 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..637f8e5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.yml linguist-detectable=true +*.yml linguist-language=YAML \ No newline at end of file diff --git a/.gitignore b/.gitignore index 8a73ca1..b750e27 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .vscode .vagrant inventory.yml +playbook/debug.yml \ No newline at end of file diff --git a/README.md b/README.md index 619cc1a..1772449 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,18 @@ -# Under Construction :construction: - -# Build a Kubernetes cluster using k3s via Ansible +# Build a Kubernetes cluster using K3s via Ansible Author: +Current Maintainer: -## K3s Ansible Playbook - -Build a Kubernetes cluster using Ansible with k3s. The goal is easily install a Kubernetes cluster on machines running: +Easily bring up a cluster on machines running: - [X] Debian - [X] Ubuntu -- [X] CentOS +- [X] Raspberry Pi OS +- [X] RHEL Family (CentOS, Redhat, Rocky Linux...) +- [X] SUSE Family (SLES, OpenSUSE Leap, Tumbleweed...) - [X] ArchLinux -on processor architecture: +on processor architectures: - [X] x64 - [X] arm64 @@ -21,13 +20,13 @@ on processor architecture: ## System requirements -Deployment environment must have Ansible 2.4.0+ +The control node must have Ansible 2.10.0+ -All nodes in inventory must have: +All managed nodes in inventory must have: - Passwordless SSH access - Root access (or a user with equivalent permissions) -It is also recommended that all nodes disable firewalls and swap. See [K3s Requirements](https://docs.k3s.io/installation/requirements) for more information. +It is also recommended that all managed nodes disable firewalls and swap. See [K3s Requirements](https://docs.k3s.io/installation/requirements) for more information. ## Usage @@ -55,7 +54,8 @@ If needed, you can also edit `vars` section at the bottom to match your environm If multiple hosts are in the server group the playbook will automatically setup k3s in HA mode with embedded etcd. An odd number of server nodes is required (3,5,7). Read the offical documentation below for more information and options. https://rancher.com/docs/k3s/latest/en/installation/ha-embedded/ -Using a loadbalancer or VIP as the API endpoint is preferred but not covered here. + +Setting up a loadbalancer or VIP beforehand to use as the API endpoint is possible but not covered here. Start provisioning of the cluster using the following command: @@ -66,7 +66,7 @@ ansible-playbook playbook/site.yml -i inventory.yml ## Upgrading -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: +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: ```bash ansible-playbook playbook/upgrade.yml -i inventory.yml @@ -75,7 +75,7 @@ ansible-playbook playbook/upgrade.yml -i inventory.yml ## Kubeconfig -After successful bringup, the kubeconfig of the cluster is copied to the control-node and set as default (`~/.kube/config`). +After successful bringup, the kubeconfig of the cluster is copied to the control node and set as default (`~/.kube/config`). Assuming you have [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) installed, you to confirm access to your **Kubernetes** cluster use the following: ```bash @@ -84,10 +84,25 @@ kubectl get nodes ## Local Testing -A Vagrantfile is provided that provision a 5 nodes cluster using LibVirt or Virtualbox and Vagrant. To use it: +A Vagrantfile is provided that provision a 5 nodes cluster using Vagrant (LibVirt or Virtualbox as provider). To use it: ```bash vagrant up ``` -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`. \ No newline at end of file +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