public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-14 10:16:27 +00:00
Code Issues Releases Wiki Activity

Experiment with PDF generation

Browse Source 
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
2022-08-19 16:40:53 +12:00
parent c051e0bdad
commit abf9309cb1
317 changed files with 124 additions and 546 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/kubernetes/deployment/flux/design.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: Using fluxcd/fluxv2 to deploy from helm with GitOps
description: This page details a deployment design pattern which facilitates the use of fluxcd/fluxv2 to provided a tiered structure of helm releases, so that you can manage your cluster services via GitOps using a single repository.
---
# Using helm with GitOps via fluxv2/fluxv2
!!! question "Shouldn't a design **precede** installation instructions?"
In this case, I felt that an [installation](/kubernetes/deployment/flux/install/) and a practical demonstration upfront, would help readers to understand the flux design, and make it simpler to then explain how to [operate](/kubernetes/deployment/flux/operate/) flux themselves! 💪
Flux is power and flexible enough to fit many use-cases. After some experience and dead-ends, I've worked out a way to deploy Flux with enough flexibility but structure to make it an almost-invisible part of how my cluster "just works" on an ongoing basis..
## Illustration
Consider this entity relationship diagram:
``` mermaid
erDiagram
repo-path-flux-system ||..|{ app-namespace : "contains yaml for"
repo-path-flux-system ||..|{ app-kustomization : "contains yaml for"
repo-path-flux-system ||..|{ helmrepositories : "contains yaml for"
app-kustomization ||..|| repo-path-app : "points flux at"
flux-system-kustomization ||..|| repo-path-flux-system : "points flux at"
repo-path-app ||..|{ app-helmreleases: "contains yaml for"
repo-path-app ||..|{ app-configmap: "contains yaml for"
repo-path-app ||..|o app-sealed-secrets: "contains yaml for"
app-configmap ||..|| app-helmreleases : configures
helmrepositories ||..|| app-helmreleases : "host charts for"
app-helmreleases ||..|{ app-containers : deploys
app-containers }|..|o app-sealed-secrets : references
```
## Description
And here's what it all means, starting from the top...
1. The flux-system **Kustomization** tells flux to look in the repo in `/flux-system`, and apply any YAMLs it finds (*with optional kustomize templating, if you're an uber-ninja!*).
2. Within `/bootstrap`, we've defined (for convenience), 3 subfolders, containing YAML for:
1. `namespaces` : Any other **Namespaces** we want to deploy for our apps
2. `helmrepositories` : Any **HelmRepositories** we later want to pull helm charts from
3. `kustomizations` : An **Kustomizations** we need to tell flux to import YAMLs from **elsewhere** in the repository
3. In turn, each app's **Kustomization** (*which we just defined above*) tells flux to look in the repo in the `/<app name>` path, and apply any YAMLs it finds (*with optional kustomize templating, if you're an uber-ninja!*).
4. Within the `/<app name>` path, we define **at least** the following:
1. A **HelmRelease** for the app, telling flux which version of what chart to apply from which **HelmRepository**
2. A **ConfigMap** for the HelmRelease, which contains all the custom (*and default!*) values for the chart
5. Of course, we can also put any **other** YAML into the `/<app name>` path in the repo, which may include additional ConfigMaps, SealedSecrets (*for safely storing secrets in a repo*), Ingresses, etc.
!!! question "That seems overly complex!"
> "Why not just stick all the YAML into one folder and let flux reconcile it all-at-once?"
Several reasons:
* We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for Keycloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository
* As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems!
## Got it?
Good! I describe how to put this design into action on the [next page](/kubernetes/deployment/flux/operate/)...
[^1]: ERDs are fancy diagrams for nERDs which [represent cardinality between entities](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model#Crow's_foot_notation) scribbled using the foot of a crow 🐓
--8<-- "recipe-footer.md"

11
docs/kubernetes/deployment/flux/index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: Using flux for deployment in Kubernetes
---
# Deployment
In a break from tradition, the flux design is best understood *after* installing it, so this section makes the most sense read in the following order:
1. [Install](/kubernetes/deployment/flux/install/)
2. [Design](/kubernetes/deployment/flux/design/)
3. [Operate](/kubernetes/deployment/flux/operate/)

136
docs/kubernetes/deployment/flux/install.md Normal file
View File

@@ -0,0 +1,136 @@
---
title: Install fluxcd/fluxv2 with custom layout for future flexibility
description: Installing fluxcd/fluxv2 is a trivial operation, but sometimes the defaults are not conducive to future flexibility. This pages details a few tricks to ensure Flux can be easily managed / extended over time.
---
# Install fluxcd/fluxv2
[Flux](https://fluxcd.io/) is a set of continuous and progressive delivery solutions for Kubernetes that are open and extensible.
Using flux to manage deployments into the cluster means:
1. All change is version-controlled (*i.e. "GitOps"*)
2. It's not necessary to expose the cluster API (*i.e., which would otherwise be the case if you were using CI*)
3. Deployments can be paused, rolled back, examine, debugged using Kubernetes primitives and tooling
!!! summary "Ingredients"
* [x] [Install the flux CLI tools](https://fluxcd.io/docs/installation/#install-the-flux-cli) on a host which has access to your cluster's apiserver.
* [x] Create a GitHub [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) that can create repositories by checking all permissions under repo.
* [x] Create a private GitHub repository dedicated to your flux deployments
## Fluxv2 components
Here's a simplified way to think about the various flux components..
1. You need a source for flux to look at. This is usually a Git repository, although it can also be a helm repository, an S3 bucket. A source defines the entire repo (*not a path or a folder structure*).
2. Within your source, you define one or more kustomizations. Each kustomization is a _location_ on your source (*i.e., myrepo/nginx*) containing YAML files to be applied directly to the API server.
3. The YAML files inside the kustomization include:
1. HelmRepositories (*think of these as the repos you'd add to helm with `helm repo`*)
2. HelmReleases (*these are charts which live in HelmRepositories*)
3. Any other valid Kubernetes YAML manifests (*i.e., ConfigMaps, etc)*
## Preparation
### Install flux CLI
This section is a [direct copy of the official docs](https://fluxcd.io/docs/installation/#install-the-flux-cli), to save you having to open another tab..
=== "HomeBrew (MacOS/Linux)"
With [Homebrew](https://brew.sh/) for macOS and Linux:
```bash
brew install fluxcd/tap/flux
```
=== "Bash (MacOS/Linux)"
With Bash for macOS and Linux:
```bash
curl -s https://fluxcd.io/install.sh | sudo bash
```
=== "Chocolatey"
With [Chocolatey](https://chocolatey.org/) for Windows:
```bash
choco install flux
```
### Create GitHub Token
Create a GitHub [personal access token](https://github.com/settings/tokens) that can create repositories by checking all permissions under repo, as well as all options under `admin:public_key `. (*we'll use the token in the bootstrapping step below*)
### Create GitHub Repo
Now we'll create a repo for flux - it can (*and probably should!*) be private. I've created a [template repo to get you started](https://github.com/geek-cookbook/template-flux/generate), but you could simply start with a blank repo too (*although you'll need at least a `bootstrap` directory included or the command below will fail*).[^1]
### Bootstrap Flux
Having prepared all of the above, we're now ready to deploy flux. Before we start, take a look at all the running pods in the cluster, with `kubectl get pods -A`. You should see something like this...
```bash
root@shredder:~# k3s kubectl get pods -A
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-7448499f4d-qfszx 1/1 Running 0 6m32s
kube-system local-path-provisioner-5ff76fc89d-rqh52 1/1 Running 0 6m32s
kube-system metrics-server-86cbb8457f-25688 1/1 Running 0 6m32s
```
Now, run a customized version of the following:
```bash
GITHUB_TOKEN=<your-token>
flux bootstrap github \
--owner=my-github-username \
--repository=my-github-username/my-repository \
--personal \
--path bootstrap
```
Once the flux bootstrap is completed without errors, list the pods in the cluster again, with `kubectl get pods -A`. This time, you see something like this:
```bash
root@shredder:~# k3s kubectl get pods -A
NAMESPACE NAME READY STATUS RESTARTS AGE
flux-system helm-controller-f7c5b6c56-nk7rm 1/1 Running 0 5m48s
flux-system kustomize-controller-55db56f44f-4kqs2 1/1 Running 0 5m48s
flux-system notification-controller-77f68bf8f4-9zlw9 1/1 Running 0 5m48s
flux-system source-controller-8457664f8f-8qhhm 1/1 Running 0 5m48s
kube-system coredns-7448499f4d-qfszx 1/1 Running 0 15m
kube-system local-path-provisioner-5ff76fc89d-rqh52 1/1 Running 0 15m
kube-system metrics-server-86cbb8457f-25688 1/1 Running 0 15m
traefik svclb-traefik-ppvhr 2/2 Running 0 5m31s
traefik traefik-f48b94477-d476p 1/1 Running 0 5m31s
root@shredder:~#
```
### What just happened?
Flux installed its controllers into the `flux-system` namespace, and created two new objects:
1. A **GitRepository** called `flux-system`, pointing to your GitHub repo.
2. A **Kustomization** called `flux-system`, pointing to the `flux-system` directory in the above repo.
If you used my template repo, some extra things also happened..
1. I'd pre-populated the `bootstrap` directory in the template repo with 3 folders:
1. [helmrepositories](https://github.com/geek-cookbook/template-flux/tree/main/bootstrap/helmrepositories), for storing repositories used for deploying helm charts
2. [kustomizations](https://github.com/geek-cookbook/template-flux/tree/main/bootstrap/kustomizations), for storing additional kustomizations *(which in turn can reference other paths in the repo*)
3. [namespaces](https://github.com/geek-cookbook/template-flux/tree/main/bootstrap/namespaces), for storing namespace manifests (*since these need to exist before we can deploy helmreleases into them*)
2. Because the `bootstrap` Kustomization includes everything **recursively** under `bootstrap` path in the repo, all of the above were **also** applied to the cluster
3. I'd pre-prepared a [Namespace](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/namespaces/namespace-podinfo.yaml), [HelmRepository](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/helmrepositories/helmrepository-podinfo.yaml), and [Kustomization](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/kustomizations/kustomization-podinfo.yaml) for "podinfo", a simple example application, so these were applied to the cluster
4. The kustomization we added for podinfo refers to the `/podinfo` path in the repo, so everything in **this** folder was **also** applied to the cluster
5. In the `/podinfo` path of the repo is a [HelmRelease](https://github.com/geek-cookbook/template-flux/blob/main/podinfo/helmrelease-podinfo.yaml) (*an object describing how to deploy a helm chart*), and a [ConfigMap](https://github.com/geek-cookbook/template-flux/blob/main/podinfo/configmap-pofinfo-helm-chart-value-overrides-configmap.yaml) (*which ontain the `values.yaml` for the podinfo helm chart*)
6. Flux recognized the podinfo **HelmRelease**, applied it along with the values in the **ConfigMap**, and consequently we have podinfo deployed from the latest helm chart, into the cluster, and managed by Flux! 💪
## Wait, but why?
That's best explained on the [next page](/kubernetes/deployment/flux/design/), describing the design we're using...
--8<-- "recipe-footer.md"
[^1]: The [template repo](https://github.com/geek-cookbook/template-flux/) also "bootstraps" a simple example re how to [operate flux](/kubernetes/deployment/flux/operate/), by deploying the podinfo helm chart.

160
docs/kubernetes/deployment/flux/operate.md Normal file
View File

@@ -0,0 +1,160 @@
---
title: Using fluxcd/fluxv2 to "GitOps" multiple helm charts from a single repository
description: Having described a installation and design pattern for fluxcd/fluxv2, this page describes how to _use_ and extend the design to manage multilpe helm releases in your cluster, from a single repository.
---
# Operate fluxcd/fluxv2 from a single repository
Having described [how to install flux](/kubernetes/deployment/flux/install/), and [how our flux deployment design works](/kubernetes/deployment/flux/design/), let's finish by exploring how to **use** flux to deploy helm charts into a cluster!
## Deploy App
We'll need 5 files per-app, to deploy and manage our apps using flux. The example below will use the following highlighted files:
```hl_lines="4 6 8 10 11"
├── README.md
├── bootstrap
│   ├── flux-system
│   ├── helmrepositories
│   │   └── helmrepository-podinfo.yaml
│   ├── kustomizations
│   │   └── kustomization-podinfo.yaml
│   └── namespaces
│   └── namespace-podinfo.yaml
└── podinfo
├── configmap-podinfo-helm-chart-value-overrides.yaml
└── helmrelease-podinfo.yaml
```
???+ question "5 files! That seems overly complex!"
> "Why not just stick all the YAML into one folder and let flux reconcile it all-at-once?"
Several reasons:
* We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for Keycloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository
* As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems!
* I like to use the one-object-per-yaml-file approach. Kubernetes is complex enough without trying to define multiple objects in one file, or having confusingly-generic filenames such as `app.yaml`! 🤦‍♂️
### Identify target helm chart
Identify your target helm chart. Let's take podinfo as an example. Here's the [official chart](https://github.com/stefanprodan/podinfo/tree/master/charts/podinfo), and here's the [values.yaml](https://github.com/stefanprodan/podinfo/tree/master/charts/podinfo/values.yaml) which describes the default values passed to the chart (*and the options the user has to make changes*).
### Create HelmRepository
The README instructs users to add the repo "podinfo" with the URL `ttps://stefanprodan.github.io/podinfo`, so
create a suitable HelmRepository YAML in `bootstrap/helmrepositories/helmrepository-podinfo.yaml`. Here's [my example](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/helmrepositories/helmrepository-podinfo.yaml).
!!! question "Why such obtuse file names?"
> Why not just call the HelmRepository YAML `podinfo.yaml`? Why prefix the filename with the API object `helmrepository-`?
We're splitting the various "bits" which define this app into multiple YAMLs, and we'll soon have multiple apps in our repo, each with their own set of "bits". It gets very confusing quickly, when comparing git commit diffs, if you're not explicitly clear on what file you're working on, or which changes you're reviewing. Plus, adding the API object name to the filename provides extra "metadata" to the file structure, and makes "fuzzy searching" for quick-opening of files in tools like VSCode more effective.
### Create Namespace
Create a namespace for the chart. Typically you'd name this the same as your chart name. Here's [my namespace-podinfo.yaml](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/namespaces/namespace-podinfo.yaml).
??? example "Here's an example Namespace..."
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: podinfo
```
### Create Kustomization
Create a kustomization for the chart, pointing flux to a path in the repo where the chart-specific YAMLs will be found. Here's my [kustomization-podinfo.yaml](https://github.com/geek-cookbook/template-flux/blob/main/bootstrap/kustomizations/kustomization-podinfo.yaml).
??? example "Here's an example Kustomization..."
```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 15m
path: podinfo
prune: true # remove any elements later removed from the above path
timeout: 2m # if not set, this defaults to interval duration, which is 1h
sourceRef:
kind: GitRepository
name: flux-system
validation: server
healthChecks:
- apiVersion: apps/v1
kind: Deployment
name: podinfo
namespace: podinfo
```
### Create HelmRelease
Now create a HelmRelease for the chart - the HelmRelease defines how the (generic) chart from the HelmRepository will be installed into our cluster. Here's my [podinfo/helmrelease-podinfo.yaml](https://github.com/geek-cookbook/template-flux/blob/main/podinfo/helmrelease-podinfo.yaml).
??? example "Here's an example HelmRelease..."
```yaml
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: podinfo
namespace: podinfo
spec:
chart:
spec:
chart: podinfo # Must be the same as the upstream chart name
version: 10.x # Pin to semver major versions to avoid breaking changes but still get bugfixes/updates
sourceRef:
kind: HelmRepository
name: podinfo # References the HelmRepository you created earlier
namespace: flux-system # All HelmRepositories exist in the flux-system namespace
interval: 15m
timeout: 5m
releaseName: podinfo # _may_ be different from the upstream chart name, but could cause confusion
valuesFrom:
- kind: ConfigMap
name: podinfo-helm-chart-value-overrides # Align with the name of the ConfigMap containing all values
valuesKey: values.yaml # This is the default, but best to be explicit for clarity
```
### Create ConfigMap
Finally, create a ConfigMap to be used to pass helm chart values to the chart. Note that it is **possible** to pass values directly in the HelmRelease, but.. it's messy. I find it easier to let the HelmRelease **describe** the release, and to let the configmap **configure** the release. It also makes tracking changes more straightforward.
As a second note, it's strictly only necessary to include in the ConfigMap the values you want to **change** from the chart's defaults. I find this to be too confusing as charts are continually updated by their developers, and this can obsucre valuable options over time. So I place in my ConfigMaps the **entire** contents of the chart's `values.yaml` file, and then I explicitly overwrite the values I want to change.
!!! tip "Making chart updates simpl(er)"
This also makes updating my values for an upstream chart refactor a simple process - I duplicate the ConfigMap, paste-overwrite with the values.yaml for the refactored/updated chart, and compare the old and new versions side-by-side, to ensure I'm still up-to-date.
It's too large to display nicely below, but here's my [podinfo/configmap-podinfo-helm-chart-value-overrides.yaml](https://github.com/geek-cookbook/template-flux/blob/main/podinfo/configmap-podinfo-helm-chart-value-overrides.yaml)
!!! tip "Yes, I am sticking to my super-obtuse file naming convention!"
Doesn't it make it easier to understand, at a glance, exactly what this YAML file is intended to be?
### Commit the changes
Simply commit your changes, sit back, and wait for flux to do its 1-min update. If you like to watch the fun, you could run `watch -n1 flux get kustomizations` so that you'll see the reconciliation take place (*if you're quick*). You can also force flux to check the repo for changes manually, by running `flux reconcile source git flux-system`.
## Making changes
Let's say you decide that instead of 1 replica of the podinfo pod, you'd like 3 replicas. Edit your configmap, and change `replicaCount: 1` to `replicaCount: 3`.
Commit your changes, and once again do the waiting / impatient-reconciling jig. This time you'll have to wait up to 15 minutes though...
!!! question "Why 15 minutes?"
> I thought we check the repo every minute?
Yes, we check the entire GitHub repository for changes every 1 min, and changes to a kustomization are applied immediately. I.e., your podinfo ConfigMap gets updated within a minute (roughly). But the interval value for the HelmRelease is set to 15 minutes, so you could be waiting for as long as 15 minutes for flux to re-reconcile your HelmRelease with the ConfigMap, and to apply any changes. I've found that setting the HelmRelease interval too low causes (a) lots of unnecessary resource usage on behalf of flux, and (b) less stability when you have a large number of HelmReleases, some of whom depend on each other.
You can force a HelmRelease to reconcile, by running `flux reconcile helmrelease -n <namespace> <name of helmrelease>`
## Success!
We did it. The Holy Grail. We deployed an application into the cluster, without touching the cluster. Pinch yourself, and then prove it worked by running `flux get kustomizations`, or `kubectl get helmreleases -n podinfo`.
--8<-- "recipe-footer.md"
[^1]: Got suggestions for improvements here? Shout out in the comments below!