infra/home-cluster
2
0 Fork 0
Code Issues Pull Requests 40 Actions Packages Projects Releases Wiki Activity

chore: add admonishes to readme

Browse Source
This commit is contained in:
Devin Buhl authored and GitHub committed 2023-12-10 09:04:54 -05:00
1 parent e14d5f5071
commit e504f6119d
1 file changed
+34 -40
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+34 -40
View File
@@ -24,7 +24,8 @@ This template implements Flux in a way that promotes legibility and ease of use
## 📝 Pre-start checklist ## 📝 Pre-start checklist
Before we get started everything below must be taken into consideration, you must... > [!CAUTION]
> Before we get started everything below must be taken into consideration, you must...
- [ ] have some experience with the following: Git/SCM, containers, networking and scripting. - [ ] have some experience with the following: Git/SCM, containers, networking and scripting.
- [ ] bring a **positive attitude** and be ready to learn and fail a lot. _The more you fail, the more you can learn from._ - [ ] bring a **positive attitude** and be ready to learn and fail a lot. _The more you fail, the more you can learn from._
@@ -39,11 +40,10 @@ Before we get started everything below must be taken into consideration, you mus
### System requirements ### System requirements
📍 _k3s default behaviour is that all nodes are able to run workloads, including contol nodes. Worker nodes are therefore optional._ > [!IMPORTANT]
> 1. The default behaviour of k3s is that all nodes are able to run workloads, **including** control nodes. Worker nodes are therefore optional.
📍 _If you have 3 or more nodes it is strongly recommended to make 3 of them control nodes for a highly available control plane._ > 2. Do you have 3 or more nodes? It is strongly recommended to make 3 of them control nodes for a highly available control plane.
> 3. Running the cluster on Proxmox VE? My thoughts and recommendations about that are documented [here](https://onedr0p.github.io/home-ops/notes/proxmox-considerations.html).
📍 _Ideally you will run the cluster on bare metal machines. If you intend to run your cluster on Proxmox VE, my thoughts and recommendations about that are documented [here](https://onedr0p.github.io/home-ops/notes/proxmox-considerations.html)._
| Role | Cores | Memory | System Disk | | Role | Cores | Memory | System Disk |
|---------|----------|---------------|---------------------------| |---------|----------|---------------|---------------------------|
@@ -97,9 +97,9 @@ Before we get started everything below must be taken into consideration, you mus
### Debian for RasPi4 ### Debian for RasPi4
📍 _If you choose to use a Raspberry Pi 4 for the cluster, it is recommended to have an 8GB model. Most important is to **boot from an external SSD/NVMe** rather than an SD card. This is supported [natively](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html), however if you have an early model you may need to [update the bootloader](https://www.tomshardware.com/how-to/boot-raspberry-pi-4-usb) first._ > [!CAUTION]
> 1. It is recommended to have an 8GB RasPi model. Most important is to **boot from an external SSD/NVMe** rather than an SD card. This is [supported natively](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html), however if you have an early model you may need to [update the bootloader](https://www.tomshardware.com/how-to/boot-raspberry-pi-4-usb) first.
📍 _Be sure to check the [power requirements](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply) if using a PoE Hat and a SSD/NVMe dongle._ > 2. Check the [power requirements](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply) if using a PoE Hat and a SSD/NVMe dongle.
1. Download the latest stable release of Debian from [here](https://raspi.debian.net/tested-images). _**Do not** use Raspbian or DietPi or any other flavor Linux OS._ 1. Download the latest stable release of Debian from [here](https://raspi.debian.net/tested-images). _**Do not** use Raspbian or DietPi or any other flavor Linux OS._
@@ -130,7 +130,8 @@ Before we get started everything below must be taken into consideration, you mus
Once you have installed Debian on your nodes, there are six stages to getting a Flux-managed cluster up and runnning. Once you have installed Debian on your nodes, there are six stages to getting a Flux-managed cluster up and runnning.
📍 _For all stages below the commands **MUST** be ran on your personal workstation within your repository directory_ > [!CAUTION]
> For all stages below the commands **MUST** be ran on your personal workstation within your repository directory
### 🎉 Stage 1: Create a Git repository ### 🎉 Stage 1: Create a Git repository
@@ -140,22 +141,16 @@ Once you have installed Debian on your nodes, there are six stages to getting a
### 🌱 Stage 2: Setup your local workstation environment ### 🌱 Stage 2: Setup your local workstation environment
📍 _Let's get the required workstation tools installed and configured._ 1. Install the most recent version of [task](https://taskfile.dev/), see the task [installation docs](https://taskfile.dev/installation/) for other supported platforms.
1. Install the most recent version of [task](https://taskfile.dev/)
📍 _See the task [installation docs](https://taskfile.dev/installation/) for other platforms_
```sh ```sh
# Brew # Brew
brew install go-task brew install go-task
``` ```
2. Install the most recent version of [direnv](https://direnv.net/) 2. Install the most recent version of [direnv](https://direnv.net/), see the direnv [installation docs](https://direnv.net/docs/installation.html) for other supported platforms.
📍 _See the direnv [installation docs](https://direnv.net/docs/installation.html) for other platforms_ 📍 _After installing `direnv` be sure to **[hook it into your shell](https://direnv.net/docs/hook.html)** and after that is done run `direnv allow` while in your repos' directory._
📍 _After installing `direnv` be sure to [hook it into your shell](https://direnv.net/docs/hook.html) and after that is done run `direnv allow` while in your repos directory._
```sh ```sh
# Brew # Brew
@@ -173,6 +168,8 @@ Once you have installed Debian on your nodes, there are six stages to getting a
4. Install the required tools: [age](https://github.com/FiloSottile/age), [flux](https://toolkit.fluxcd.io/), [cloudflared](https://github.com/cloudflare/cloudflared), [kubectl](https://kubernetes.io/docs/tasks/tools/), [sops](https://github.com/getsops/sops) 4. Install the required tools: [age](https://github.com/FiloSottile/age), [flux](https://toolkit.fluxcd.io/), [cloudflared](https://github.com/cloudflare/cloudflared), [kubectl](https://kubernetes.io/docs/tasks/tools/), [sops](https://github.com/getsops/sops)
📍 _Not using brew? Make sure to look up how to install the latest version of each of these CLI tools yourself._
```sh ```sh
# Brew # Brew
task brew:deps task brew:deps
@@ -180,7 +177,7 @@ Once you have installed Debian on your nodes, there are six stages to getting a
### 🔧 Stage 3: Do bootstrap configuration ### 🔧 Stage 3: Do bootstrap configuration
📍 _Both `bootstrap/vars/config.yaml` and `bootstrap/vars/addons.yaml` files contain necessary information that is needed by bootstrap process._ 📍 _Both `bootstrap/vars/config.yaml` and `bootstrap/vars/addons.yaml` files contain necessary information that is **vital** to the bootstrap process._
1. Generate the `bootstrap/vars/config.yaml` and `bootstrap/vars/addons.yaml` configuration files. 1. Generate the `bootstrap/vars/config.yaml` and `bootstrap/vars/addons.yaml` configuration files.
@@ -255,14 +252,14 @@ Once you have installed Debian on your nodes, there are six stages to getting a
task configure task configure
``` ```
📍 _The configure task will create a `./ansible` directory and the following directories under `./kubernetes`._ > [!IMPORTANT]
> The configure task will create a `./ansible` directory and the following directories under `./kubernetes`.
```sh > ```sh
📁 kubernetes # Kubernetes cluster defined as code > 📁 kubernetes # Kubernetes cluster defined as code
├─📁 bootstrap # Flux installation (not tracked by Flux) > ├─📁 bootstrap # Flux installation (not tracked by Flux)
├─📁 flux # Main Flux configuration of repository > ├─📁 flux # Main Flux configuration of repository
└─📁 apps # Apps deployed into the cluster grouped by namespace > └─📁 apps # Apps deployed into the cluster grouped by namespace
``` > ```
### ⚡ Stage 4: Prepare your nodes for k3s ### ⚡ Stage 4: Prepare your nodes for k3s
@@ -396,18 +393,15 @@ The `external-dns` application created in the `networking` namespace will handle
`k8s_gateway` will provide DNS resolution to external Kubernetes resources (i.e. points of entry to the cluster) from any device that uses your home DNS server. For this to work, your home DNS server must be configured to forward DNS queries for `${bootstrap_cloudflare_domain}` to `${bootstrap_k8s_gateway_addr}` instead of the upstream DNS server(s) it normally uses. This is a form of **split DNS** (aka split-horizon DNS / conditional forwarding). `k8s_gateway` will provide DNS resolution to external Kubernetes resources (i.e. points of entry to the cluster) from any device that uses your home DNS server. For this to work, your home DNS server must be configured to forward DNS queries for `${bootstrap_cloudflare_domain}` to `${bootstrap_k8s_gateway_addr}` instead of the upstream DNS server(s) it normally uses. This is a form of **split DNS** (aka split-horizon DNS / conditional forwarding).
📍 _Below is how to configure a Pi-hole for split DNS. Other platforms should be similar._ > [!TIP]
> Below is how to configure a Pi-hole for split DNS. Other platforms should be similar.
1. Apply this file on the server > 1. Apply this file on the server
> ```sh
```sh > # /etc/dnsmasq.d/99-k8s-gateway-forward.conf
# /etc/dnsmasq.d/99-k8s-gateway-forward.conf > server=/${bootstrap_cloudflare_domain}/${bootstrap_k8s_gateway_addr}
server=/${bootstrap_cloudflare_domain}/${bootstrap_k8s_gateway_addr} > ```
``` > 2. Restart dnsmasq on the server.
> 3. Query an internal-only subdomain from your workstation (any `internal` class ingresses): `dig @${home-dns-server-ip} hubble.${bootstrap_cloudflare_domain}`. It should resolve to `${bootstrap_internal_ingress_addr}`.
2. Restart dnsmasq on the server.
3. Query an internal-only subdomain from your workstation (any `internal` class ingresses): `dig @${home-dns-server-ip} hubble.${bootstrap_cloudflare_domain}`. It should resolve to `${bootstrap_internal_ingress_addr}`.
If you're having trouble with DNS be sure to check out these two GitHub discussions: [Internal DNS](https://github.com/onedr0p/flux-cluster-template/discussions/719) and [Pod DNS resolution broken](https://github.com/onedr0p/flux-cluster-template/discussions/635). If you're having trouble with DNS be sure to check out these two GitHub discussions: [Internal DNS](https://github.com/onedr0p/flux-cluster-template/discussions/719) and [Pod DNS resolution broken](https://github.com/onedr0p/flux-cluster-template/discussions/635).