From e1c1d1689b9cb4143974a04e7e4a355ef317df81 Mon Sep 17 00:00:00 2001 From: Devin Buhl Date: Mon, 9 May 2022 16:54:31 -0400 Subject: [PATCH] chore: Add homebrew task to taskfile and update README.md Signed-off-by: Devin Buhl --- .taskfiles/AnsibleTasks.yml | 67 +++++++++++++ .../{pre-commit.yml => PrecommitTasks.yml} | 1 + .../{terraform.yml => TerraformTasks.yml} | 0 .taskfiles/ansible.yml | 67 ------------- README.md | 93 ++++++++----------- Taskfile.yml | 42 +++++++-- 6 files changed, 144 insertions(+), 126 deletions(-) create mode 100644 .taskfiles/AnsibleTasks.yml rename .taskfiles/{pre-commit.yml => PrecommitTasks.yml} (99%) rename .taskfiles/{terraform.yml => TerraformTasks.yml} (100%) delete mode 100644 .taskfiles/ansible.yml diff --git a/.taskfiles/AnsibleTasks.yml b/.taskfiles/AnsibleTasks.yml new file mode 100644 index 00000000..b0d094e0 --- /dev/null +++ b/.taskfiles/AnsibleTasks.yml @@ -0,0 +1,67 @@ +--- +version: "3" + +env: + ANSIBLE_CONFIG: "{{.PROJECT_DIR}}/ansible.cfg" + +vars: + ANSIBLE_PLAYBOOK_DIR: "{{.ANSIBLE_DIR}}/playbooks" + ANSIBLE_INVENTORY_DIR: "{{.ANSIBLE_DIR}}/inventory" + +tasks: + + init: + desc: Install / Upgrade Ansible galaxy deps + dir: provision/ansible + cmds: + - ansible-galaxy install -r requirements.yml --roles-path ~/.ansible/roles --force + - ansible-galaxy collection install -r requirements.yml --collections-path ~/.ansible/collections --force + + list: + desc: List all the hosts + dir: provision/ansible + cmds: + - ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --list-hosts + + prepare: + desc: Prepare all the k8s nodes for running k3s + dir: provision/ansible + cmds: + - ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/ubuntu-prepare.yml + + install: + desc: Install Kubernetes on the nodes + dir: provision/ansible + cmds: + - ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/k3s-install.yml + + nuke: + desc: Uninstall Kubernetes on the nodes + dir: provision/ansible + cmds: + - ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/k3s-nuke.yml + - defer: ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl reboot' --become + + ping: + desc: Ping all the hosts + dir: provision/ansible + cmds: + - ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --one-line -m 'ping' + + uptime: + desc: Uptime of all the hosts + dir: provision/ansible + cmds: + - ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --one-line -a 'uptime' + + reboot: + desc: Reboot all the k8s nodes + dir: provision/ansible + cmds: + - ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl reboot' --become + + poweroff: + desc: Shutdown all the k8s nodes + dir: provision/ansible + cmds: + - ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl poweroff' --become diff --git a/.taskfiles/pre-commit.yml b/.taskfiles/PrecommitTasks.yml similarity index 99% rename from .taskfiles/pre-commit.yml rename to .taskfiles/PrecommitTasks.yml index 476507f9..1e94c280 100644 --- a/.taskfiles/pre-commit.yml +++ b/.taskfiles/PrecommitTasks.yml @@ -7,6 +7,7 @@ tasks: desc: Initialize pre-commit hooks cmds: - pre-commit install --install-hooks + run: desc: Run pre-commit cmds: diff --git a/.taskfiles/terraform.yml b/.taskfiles/TerraformTasks.yml similarity index 100% rename from .taskfiles/terraform.yml rename to .taskfiles/TerraformTasks.yml diff --git a/.taskfiles/ansible.yml b/.taskfiles/ansible.yml deleted file mode 100644 index e190318a..00000000 --- a/.taskfiles/ansible.yml +++ /dev/null @@ -1,67 +0,0 @@ ---- -version: "3" - -env: - ANSIBLE_CONFIG: "{{.PROJECT_DIR}}/ansible.cfg" - -vars: - ANSIBLE_PLAYBOOK_DIR: "{{.ANSIBLE_DIR}}/playbooks" - ANSIBLE_INVENTORY_DIR: "{{.ANSIBLE_DIR}}/inventory" - -tasks: - - init: - desc: Upgrade Ansible galaxy deps - dir: provision/ansible - cmds: - - "ansible-galaxy install -r requirements.yml --roles-path ~/.ansible/roles --force" - - "ansible-galaxy collection install -r requirements.yml --collections-path ~/.ansible/collections --force" - - list: - desc: List all the hosts - dir: provision/ansible - cmds: - - "ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --list-hosts" - - prepare: - desc: Prepare all the k8s nodes for running k3s - dir: provision/ansible - cmds: - - "ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/ubuntu-prepare.yml" - - install: - desc: Install Kubernetes on the nodes - dir: provision/ansible - cmds: - - "ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/k3s-install.yml" - - nuke: - desc: Uninstall Kubernetes on the nodes - dir: provision/ansible - cmds: - - "ansible-playbook -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml {{.ANSIBLE_PLAYBOOK_DIR}}/k3s-nuke.yml" - - "ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl reboot' --become" - - ping: - desc: Ping all the hosts - dir: provision/ansible - cmds: - - "ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --one-line -m 'ping'" - - uptime: - desc: Uptime of all the hosts - dir: provision/ansible - cmds: - - ansible all -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml --one-line -a 'uptime' - - reboot: - desc: Reboot all the k8s nodes - dir: provision/ansible - cmds: - - "ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl reboot' --become" - - poweroff: - desc: Shutdown all the k8s nodes - dir: provision/ansible - cmds: - - "ansible kubernetes -i {{.ANSIBLE_INVENTORY_DIR}}/hosts.yml -a '/usr/bin/systemctl poweroff' --become" diff --git a/README.md b/README.md index e332d1b4..a850f3ea 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Highly opinionated template for deploying a single [k3s](https://k3s.io) cluster with [Ansible](https://www.ansible.com) and [Terraform](https://www.terraform.io) backed by [Flux](https://toolkit.fluxcd.io/) and [SOPS](https://toolkit.fluxcd.io/guides/mozilla-sops/). -The purpose here is to showcase how you can deploy an entire Kubernetes cluster and show it off to the world using the [GitOps](https://www.weave.works/blog/what-is-gitops-really) tool [Flux](https://toolkit.fluxcd.io/). When completed, your Git repository will be driving the state of your Kubernetes cluster. In addition with the help of the [Ansible](https://github.com/ansible-collections/community.sops), [Terraform](https://github.com/carlpett/terraform-provider-sops) and [Flux](https://toolkit.fluxcd.io/guides/mozilla-sops/) SOPS integrations you'll be able to commit Age encrypted secrets to your public repo. +The purpose here is to showcase how you can deploy an entire Kubernetes cluster and show it off to the world using the [GitOps](https://www.weave.works/blog/what-is-gitops-really) tool [Flux](https://toolkit.fluxcd.io/). When completed, your Git repository will be driving the state of your Kubernetes cluster. In addition with the help of the [Ansible](https://github.com/ansible-collections/community.sops), [Terraform](https://github.com/carlpett/terraform-provider-sops) and [Flux](https://toolkit.fluxcd.io/guides/mozilla-sops/) SOPS integrations you'll be able to commit [Age](https://github.com/FiloSottile/age) encrypted secrets to your public repo. ## Overview @@ -10,29 +10,26 @@ The purpose here is to showcase how you can deploy an entire Kubernetes cluster - [Prerequisites](https://github.com/k8s-at-home/template-cluster-k3s#-prerequisites) - [Repository structure](https://github.com/k8s-at-home/template-cluster-k3s#-repository-structure) - [Lets go!](https://github.com/k8s-at-home/template-cluster-k3s#-lets-go) -- [Post installation](https://github.com/k8s-at-home/template-cluster-k3s#-installation) +- [Post installation](https://github.com/k8s-at-home/template-cluster-k3s#-post-installation) +- [Troubleshooting](https://github.com/k8s-at-home/template-cluster-k3s#-troubleshooting) +- [What's next](https://github.com/k8s-at-home/template-cluster-k3s#-whats-next) - [Thanks](https://github.com/k8s-at-home/template-cluster-k3s#-thanks) ## 👋 Introduction -The following components will be installed in your [k3s](https://k3s.io/) cluster by default. They are only included to get a minimum viable cluster up and running. You are free to add / remove components to your liking but anything outside the scope of the below components are not supported by this template. +The following components will be installed in your [k3s](https://k3s.io/) cluster by default. Most are only included to get a minimum viable cluster up and running. -Feel free to read up on any of these technologies before you get started to be more familiar with them. +- [flux](https://toolkit.fluxcd.io/) - GitOps operator for managing Kubernetes clusters from a Git repository +- [kube-vip](https://kube-vip.io/) - Load balancer for the Kubernetes control plane nodes +- [metallb](https://metallb.universe.tf/) - Load balancer for Kubernetes services +- [cert-manager](https://cert-manager.io/) - Operator to request SSL certificates and store them as Kubernetes resources +- [calico](https://www.tigera.io/project-calico/) - Container networking interface for inter pod and service networking +- [external-dns](https://github.com/kubernetes-sigs/external-dns) - Operator to publish DNS records to Cloudflare (and other providers) based on Kubernetes ingresses +- [k8s_gateway](https://github.com/ori-edge/k8s_gateway) - DNS resolver that provides local DNS to your Kubernetes ingresses +- [traefik](https://traefik.io) - Kubernetes ingress controller used for a HTTP reverse proxy of Kubernetes ingresses +- [local-path-provisioner](https://github.com/rancher/local-path-provisioner) - provision persistent local storage with Kubernetes -- [cert-manager](https://cert-manager.io/) - SSL certificates - with Cloudflare DNS challenge -- [calico](https://www.tigera.io/project-calico/) - CNI (container network interface) -- [echo-server](https://github.com/Ealenn/Echo-Server) - REST Server Tests (Echo-Server) API (useful for debugging HTTP issues) -- [external-dns](https://github.com/kubernetes-sigs/external-dns) - Automatically configure external DNS servers for Kubernetes Ingresses and Services -- [flux](https://toolkit.fluxcd.io/) - GitOps tool for deploying manifests from the `cluster` directory -- [hajimari](https://github.com/toboshii/hajimari) - start page with ingress discovery -- [k8s_gateway](https://github.com/ori-edge/k8s_gateway) - DNS resolver for all types of external Kubernetes resources -- [kube-vip](https://kube-vip.io/) - layer 2 load balancer for the Kubernetes control plane -- [local-path-provisioner](https://github.com/rancher/local-path-provisioner) - default storage class provided by k3s -- [metallb](https://metallb.universe.tf/) - bare metal load balancer -- [reloader](https://github.com/stakater/Reloader) - restart pods when Kubernetes `configmap` or `secret` changes -- [reflector](https://github.com/emberstack/kubernetes-reflector) - mirror `configmap`s or `secret`s to other Kubernetes namespaces -- [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller) - (opt-in) automate upgrading k3s -- [traefik](https://traefik.io) - ingress controller +_Additional applications include [hajimari](https://github.com/toboshii/hajimari), [echo-server](https://github.com/Ealenn/Echo-Server), [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller), [reflector](https://github.com/emberstack/kubernetes-reflector), and [reloader](https://github.com/stakater/Reloader)_ For provisioning the following tools will be used: @@ -42,7 +39,7 @@ For provisioning the following tools will be used: ## 📝 Prerequisites -**Note:** This template has not been tested on cloud providers like AWS EC2, Hetzner, Scaleway etc... Those cloud offerings probably have a better way of provsioning a Kubernetes cluster and it's advisable to use those instead of the Ansible playbooks included here. This repository can still be used for the GitOps/Flux portion if there's a cluster working in one those environments. +**Note:** _This template has not been tested on cloud providers like AWS EC2, Hetzner, Scaleway etc... Those cloud offerings probably have a better way of provsioning a Kubernetes cluster and it's advisable to use those instead of the Ansible playbooks included here. This repository can still be used for the GitOps/Flux portion if there's a cluster working in one those environments._ ### 💻 Systems @@ -54,52 +51,42 @@ For provisioning the following tools will be used: 📍 It is recommended to have 3 master nodes for a highly available control plane. -### 🔧 Tools +### 🔧 Workstation Tools -📍 You should install the below CLI tools on your workstation. Make sure you pull in the latest versions. +1. Install the **most recent versions** of the following CLI tools on your workstation, if you are using [Homebrew](https://brew.sh/) on MacOS or Linux skip to steps 2 and 3. -#### Required + * Required: [age](https://github.com/FiloSottile/age), [ansible](https://www.ansible.com), [flux](https://toolkit.fluxcd.io/), [gitleaks](https://github.com/zricethezav/gitleaks), [go-task](https://github.com/go-task/task), [ipcalc](http://jodies.de/ipcalc), [jq](https://stedolan.github.io/jq/), [kubectl](https://kubernetes.io/docs/tasks/tools/), [pre-commit](https://github.com/pre-commit/pre-commit), [sops](https://github.com/mozilla/sops), [terraform](https://www.terraform.io), [yq](https://github.com/mikefarah/yq) -| Tool | Purpose | -|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| [ansible](https://www.ansible.com) | Preparing Ubuntu for Kubernetes and installing k3s | -| [direnv](https://github.com/direnv/direnv) | Exports env vars based on present working directory | -| [flux](https://toolkit.fluxcd.io/) | Operator that manages your k8s cluster based on your Git repository | -| [age](https://github.com/FiloSottile/age) | A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability. | -| [go-task](https://github.com/go-task/task) | A task runner / simpler Make alternative written in Go | -| [ipcalc](http://jodies.de/ipcalc) | Used to verify settings in the configure script | -| [jq](https://stedolan.github.io/jq/) | Used to verify settings in the configure script | -| [yq](https://github.com/mikefarah/yq) | Used to verify settings in the configure script | -| [kubectl](https://kubernetes.io/docs/tasks/tools/) | Allows you to run commands against Kubernetes clusters | -| [sops](https://github.com/mozilla/sops) | Encrypts k8s secrets with Age | -| [terraform](https://www.terraform.io) | Prepare a Cloudflare domain to be used with the cluster | + * Recommended: [direnv](https://github.com/direnv/direnv), [helm](https://helm.sh/), [kustomize](https://github.com/kubernetes-sigs/kustomize), [prettier](https://github.com/prettier/prettier), [stern](https://github.com/stern/stern), [yamllint](https://github.com/adrienverge/yamllint) -#### Optional +2. Install [go-task](https://github.com/go-task/task) -| Tool | Purpose | -|--------------------------------------------------------|----------------------------------------------------------| -| [helm](https://helm.sh/) | Manage Kubernetes applications | -| [kustomize](https://kustomize.io/) | Template-free way to customize application configuration | -| [pre-commit](https://github.com/pre-commit/pre-commit) | Runs checks pre `git commit` | -| [gitleaks](https://github.com/zricethezav/gitleaks) | Scan git repos (or files) for secrets | -| [prettier](https://github.com/prettier/prettier) | Prettier is an opinionated code formatter. | + ```sh + brew install go-task/tap/go-task + ``` + +3. Install workstation dependencies + + ```sh + task init + ``` ### ⚠️ pre-commit It is advisable to install [pre-commit](https://pre-commit.com/) and the pre-commit hooks that come with this repository. -[sops-pre-commit](https://github.com/k8s-at-home/sops-pre-commit) and [gitleaks](https://github.com/zricethezav/gitleaks) will check to make sure you are not by accident committing your secrets un-encrypted. +[sops-pre-commit](https://github.com/k8s-at-home/sops-pre-commit) and [gitleaks](https://github.com/zricethezav/gitleaks) will check to make sure you are not by accident committing un-encrypted secrets. -After pre-commit is installed on your machine run: +1. Enable Pre-Commit -```sh -task pre-commit:init -``` + ```sh + task precommit:init + ``` -This command checks for new versions of hooks, though it will occasionally make mistakes, so verify its results. +2. Update Pre-Commit, though it will occasionally make mistakes, so verify its results. -```sh -task pre-commit:update -``` + ```sh + task precommit:update + ``` ## 📂 Repository structure @@ -140,7 +127,7 @@ Clone the repo to you local workstation and `cd` into it. ### 🔐 Setting up Age -📍 Here we will create a Age Private and Public key. Using SOPS with Age allows us to encrypt and decrypt secrets. +📍 Here we will create a Age Private and Public key. Using [SOPS](https://github.com/mozilla/sops) with [Age](https://github.com/FiloSottile/age) allows us to encrypt secrets and use them in Ansible, Terraform and Flux. 1. Create a Age Private / Public Key diff --git a/Taskfile.yml b/Taskfile.yml index e36cc600..3b954e0a 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -14,18 +14,48 @@ env: KUBECONFIG: "{{.PROJECT_DIR}}/provision/kubeconfig" includes: - ansible: .taskfiles/ansible.yml - pre-commit: .taskfiles/pre-commit.yml - terraform: .taskfiles/terraform.yml + ansible: .taskfiles/AnsibleTasks.yml + precommit: .taskfiles/PrecommitTasks.yml + terraform: .taskfiles/TerraformTasks.yml tasks: + init: + desc: Initialize workstation dependencies with Brew + cmds: + - brew install {{.DEPS}} {{.CLI_ARGS}} + preconditions: + - sh: command -v brew + msg: | + Homebrew is not installed. Using MacOS, Linux or WSL? + Head over to https://brew.sh to get up and running. + vars: + DEPS: >- + age + ansible + direnv + fluxcd/tap/flux + gitleaks + go-task/tap/go-task + helm + ipcalc + jq + kubernetes-cli + kustomize + pre-commit + prettier + sops + stern + terraform + yamllint + yq + verify: desc: Verify env settings cmds: - - bash configure --verify + - ./configure --verify configure: - desc: Configure repository + desc: Configure repository from env settings cmds: - - bash configure + - ./configure