diff --git a/.ansible-lint b/.ansible-lint index 8cb9eca..4c7d813 100644 --- a/.ansible-lint +++ b/.ansible-lint @@ -131,10 +131,11 @@ profile: null # :end-before: "###\n" # ``` skip_list: - - skip_this_tag - command-instead-of-shell - - no-changed-when - loop-var-prefix[missing] + - no-changed-when + - risky-shell-pipe + - skip_this_tag ### # Define required Ansible's variables to satisfy syntax check # extra_vars: diff --git a/.gitignore b/.gitignore index 0cf0cd6..dc4381a 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ package.json roles/reset/files/*.reset.md roles/join/files/join.md roles/init/files/admin.conf +roles/join/files/kcp02* +roles/join/files/kcp03* diff --git a/index.md b/index.md index 9709671..c240fe5 100644 --- a/index.md +++ b/index.md @@ -1,11 +1,12 @@ --- -abstract: This is a collection of Ansible playbooks that will create a CA usable - for Kubernetes and etcd clusters. +abstract: >- + This is a set of roles that will initialize a primary control plane, + then join secondary and tertiary control planes to a HA k8s cluster. authors: - name: Xander Harris email: xandertheharris@gmail.com date: 2024-03-08 -title: Ansible Bare Metal K8S +title: Ansible Bare Metal HA K8S --- ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/edwardtheharris/ansible-kcp/ansible.yml?branch=main&style=flat-square&logo=ansible&label=Ansible%20Lint) @@ -24,7 +25,7 @@ title: Ansible Bare Metal K8S ### Roles ```{toctree} -:maxdepth: 1 +:maxdepth: 3 :caption: roles roles/index @@ -52,8 +53,32 @@ security - [community.crypto.x509_certificate](https://docs.ansible.com/ansible/latest/collections/community/crypto/x509_certificate_module.html) - [How to create a small CA](https://docs.ansible.com/ansible/latest/collections/community/crypto/docsite/guide_ownca.html) -## Indices and tables +### Indices and tables - {ref}`genindex` - {ref}`modindex` - {ref}`search` + +### Glossary + +```{glossary} +HA + High Availability; in this context we mean specifically HA k8s clusters + as described + [here](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/). + +kubeconfig + A file that contains context and authentication information for one or more + {term}`K8S` clusters. Usually kept in a folder in a user's home directory + ({file}`.kube/config`). + +kube-vip + A network stack that can be used to enable cloud-style network resources + on a bare metal {term}`K8S` cluster. More information is available + [here](https://kube-vip.io/docs/installation/static/). + +K8S + Kubernetes; Ancient Greek for navigator or guide, in modern English usage + it is a container orchestration system designed by Google and documented + [here](https://kubernetes.io). +``` diff --git a/license.md b/license.md index 4518e56..bfde78d 100644 --- a/license.md +++ b/license.md @@ -1,5 +1,4 @@ --- - abstract: The license, or lack thereof. date: 2024-03-08 title: Unlicensed diff --git a/roles/index.md b/roles/index.md index 0659848..a8f94f6 100644 --- a/roles/index.md +++ b/roles/index.md @@ -6,18 +6,77 @@ authors: - name: Xander Harris email: xandertheharris@gmail.com date: 2024-07-23 -title: Bare Metal k8s roles +title: Bare Metal HA k8s roles --- ## Roles +There are three roles here, they should be run in a specific order as described +in the usage section below. + +### HA K8S Ansible Usage + +To use these roles effectively, you'll need have an inventory file available +at {file}`/etc/ansible/hosts.yml` that describes all of the groups listed +in the {file}`site.yml` at the root of this repository. With that in hand, +the way to use these roles is this. + +1. Reset any existing cluster. + + ```{code-block} shell + ansible-playbook -t reset site.yml + ``` + +2. Initialize the primary control plane. + + ```{code-block} shell + ansible-playbook -t init site.yml + ``` + +3. Join remaining control planes. + + ```{code-block} shell + ansible-playbook -t join site.yml + ``` + +4. Copy your updated {term}`kubeconfig` from the init role's file folder to + the appropriate directory. + + ```{code-block} shell + cp roles/init/files/admin.conf $HOME/.kube/config + ``` + +5. Verify that your connection works and the cluster is up. + + ```{code-block} shell + kubectl get nodes + ``` + + If everything worked you should see output similar to this. + + ```{code-block} shell + NAME STATUS ROLES AGE VERSION + kcp01.example.com Ready control-plane 51m v1.30.3 + kcp02.example.com Ready control-plane 50m v1.30.3 + kcp03.example.com Ready control-plane 50m v1.30.3 + ``` + +### Individual role details + ```{toctree} :maxdepth: 1 :caption: roles init/index +join/index reset/index ``` +```{index} roles init +``` + +```{index} roles; join +``` + ```{index} roles; reset ``` diff --git a/roles/init/index.md b/roles/init/index.md index d1878a0..b308f24 100644 --- a/roles/init/index.md +++ b/roles/init/index.md @@ -1,16 +1,15 @@ --- - -abstract: This roles installs a Kubernetes Control Plane Node. -authors: Xander Harris -date: 2024-03-01 -title: Kubernetes Control Plane +abstract: >- + This role initializes a k8s Control Plane suitable for a high + availability cluster. +authors: + - name: Xander Harris + email: xandertheharris@gmail.com +date: 2024-07-24 +title: K8S HA Control Plane Init --- -Presently only a single Control Plane cluster is supported, but support for -high availability clusters will hopefully be available soon. - -[HA Clusters with Kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/) -is helped with use of the tool +{term}`HA` Clusters with Kubeadm is helped with use of the tool [kube-vip](https://kube-vip.io/docs/installation/static/). More information about the process for HA setup is available @@ -21,6 +20,9 @@ A handy tool for switching k8s contexts is called ## Tasks +The role uses {term}`kubeadm` to handle the initialization of the primary +control plane. + ```{literalinclude} /roles/init/tasks/main.yml :language: yaml ``` diff --git a/roles/join/index.md b/roles/join/index.md new file mode 100644 index 0000000..b76f5a6 --- /dev/null +++ b/roles/join/index.md @@ -0,0 +1,29 @@ +--- +abstract: >- + This role joins additional control planes to a high availability k8s + cluster. +authors: + - name: Xander Harris + email: xandertheharris@gmail.com +date: 2024-07-24 +title: HA K8S Join Control Planes +--- + +[HA Clusters with Kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/) +is helped with use of the tool +[kube-vip](https://kube-vip.io/docs/installation/static/). + +More information about the process for HA setup is available +[here](https://github.com/kubernetes/kubeadm/blob/main/docs/ha-considerations.md#kube-vip). + +A handy tool for switching k8s contexts is called +[kubie](https://github.com/sbstp/kubie). + +## Tasks + +```{literalinclude} /roles/join/tasks/main.yml +:language: yaml +``` + +```{sectionauthor} Xander Harris +``` diff --git a/roles/join/tasks/main.yml b/roles/join/tasks/main.yml index c27cdf8..33781a1 100644 --- a/roles/join/tasks/main.yml +++ b/roles/join/tasks/main.yml @@ -1,4 +1,27 @@ --- -- name: Output nothing - ansible.builtin.debug: - msg: "nothing here" +- name: Load join command + ansible.builtin.shell: + cmd: grep -A 3 'kubeadm join' roles/join/files/join.md | head -3 + register: join_cmd + delegate_to: localhost +- name: Output join command + ansible.builtin.shell: + cmd: "{{ join_cmd.stdout }} > /root/join_result.md" + register: join_result +- name: Fetch join results + ansible.builtin.fetch: + src: /root/join_result.md + dest: "roles/join/files/{{ inventory_hostname }}/join_result.md" + flat: true +- name: Copy admin.conf + ansible.builtin.copy: + src: roles/init/files/admin.conf + dest: "{{ item.path }}" + owner: "{{ item.owner }}" + group: kube + mode: u+rw,o-rwx + loop: + - path: /root/.kube/config + owner: root + - path: "/home/{{ join_nonroot }}/.kube/config" + owner: "{{ join_nonroot }}" diff --git a/site.yml b/site.yml index c549ec9..bf6d34e 100644 --- a/site.yml +++ b/site.yml @@ -16,9 +16,16 @@ tags: - reset - name: Initialize the first control plane - hosts: kcp01 + hosts: kcp01_init become: true roles: - role: init tags: - init +- name: Join the secondary and tertiary control planes + hosts: kcp_join + become: true + roles: + - role: join + tags: + - join