feat: improve docs and cluster dir

.sops.yaml

@@ -2,3 +2,5 @@
 creation_rules:
 - encrypted_regex: '((?i)(pass|secret($|[^N])|key|token|^data$|^stringData))'
   pgp: >-
+    $FLUX_KEY_FP,
+    $PERSONAL_KEY_FP

README.md

@@ -17,20 +17,166 @@ Bare metal or VMs with a modern operating system like Ubuntu, Debian or CentOS.
 
 ### :wrench:  Tools
 
-| Tool                                                   | Purpose                                                             | Required |
+| Tool                                                               | Purpose                                                             | Required |
-|--------------------------------------------------------|---------------------------------------------------------------------|:--------:|
+|--------------------------------------------------------------------|---------------------------------------------------------------------|:--------:|
-| [k3sup](https://github.com/alexellis/k3sup)            | Tool to install k3s on your nodes                                   |    ✅     |
+| [k3sup](https://github.com/alexellis/k3sup)                        | Tool to install k3s on your nodes                                   |    ✅     |
-| [flux](https://toolkit.fluxcd.io/)                     | Operator that manages your k8s cluster based on your Git repository |    ✅     |
+| [flux](https://toolkit.fluxcd.io/)                                 | Operator that manages your k8s cluster based on your Git repository |    ✅     |
-| [SOPS](https://github.com/mozilla/sops)                | Encrypts k8s secrets with GnuPG                                     |    ✅     |
+| [kustomize](https://kustomize.io/)                                 | Template-free way to customize application configuration            |    ✅     |
-| [GnuPG](https://gnupg.org/)                            | Encrypts and signs your data                                        |    ✅     |
+| [SOPS](https://github.com/mozilla/sops)                            | Encrypts k8s secrets with GnuPG                                     |    ✅     |
-| [direnv](https://github.com/direnv/direnv)             | Exports env vars based on present working directory                 |    ❌     |
+| [GnuPG](https://gnupg.org/)                                        | Encrypts and signs your data                                        |    ✅     |
-| [pre-commit](https://github.com/pre-commit/pre-commit) | Keeps formatting consistency across your files                      |    ❌     |
+| [pinentry](https://gnupg.org/related_software/pinentry/index.html) | Allows GnuPG to read passphrases and PIN numbers                    |    ✅     |
+| [direnv](https://github.com/direnv/direnv)                         | Exports env vars based on present working directory                 |    ❌     |
+| [pre-commit](https://github.com/pre-commit/pre-commit)             | Keeps formatting consistency across your files                      |    ❌     |
 
 ## :rocket:  Installation
 
-### :sailboat:  k3sup
+Very first step will be to create a new repository by clicking the **Use this template** button on this page.
 
-Bootstrap your nodes with k3s using k3sup
+### :key:  Setting up GnuPG keys
+
+1. Create a Personal GPG Key, password protected, and export the fingerprint
+
+```sh
+export GPG_TTY=$(tty)
+export PERONAL_KEY_NAME="First name Last name (location) <email>"
+
+gpg --batch --full-generate-key <<EOF
+Key-Type: 1
+Key-Length: 4096
+Subkey-Type: 1
+Subkey-Length: 4096
+Expire-Date: 0
+Name-Real: ${PERONAL_KEY_NAME}
+EOF
+
+gpg --list-secret-keys "${PERONAL_KEY_NAME}"
+# pub   rsa4096 2021-03-11 [SC]
+#       772154FFF783DE317KLCA0EC77149AC618D75581
+# uid           [ultimate] k8s@home (Macbook) <k8s-at-home@gmail.com>
+# sub   rsa4096 2021-03-11 [E]
+
+export PERSONAL_KEY_FP=772154FFF783DE317KLCA0EC77149AC618D75581
+```
+
+2. Create a Flux GPG Key and export the fingerprint
+
+```sh
+export GPG_TTY=$(tty)
+export FLUX_KEY_NAME="Cluster name (Flux) <email>"
+
+gpg --batch --full-generate-key <<EOF
+%no-protection
+Key-Type: 1
+Key-Length: 4096
+Subkey-Type: 1
+Subkey-Length: 4096
+Expire-Date: 0
+Name-Real: ${KEY_NAME}
+EOF
+
+gpg --list-secret-keys "${FLUX_KEY_NAME}"
+# pub   rsa4096 2021-03-11 [SC]
+#       AB675CE4CC64251G3S9AE1DAA88ARRTY2C009E2D
+# uid           [ultimate] Home cluster (Flux) <k8s-at-home@gmail.com>
+# sub   rsa4096 2021-03-11 [E]
+
+export FLUX_KEY_FP=AB675CE4CC64251G3S9AE1DAA88ARRTY2C009E2D
+```
+
+### :sailboat:&nbsp; Installing k3s with k3sup
+
+1. Ensure you are able to SSH into you nodes with using your private ssh key. This is how k3sup is able to connect to your remote node.
+
+2. Install the master node
+
+```sh
+k3sup install \
+    --host=169.254.1.1 \
+    --user=k8s-at-home \
+    --k3s-version=v1.20.5+k3s1 \
+    --k3s-extra-args="--disable servicelb --disable traefik"
+```
+
+3. Join a worker node(s) (optional)
+
+```sh
+k3sup join \
+    --host=169.254.1.2 \
+    --server-host=169.254.1.1 \
+    --k3s-version=v1.20.5+k3s1 \
+    --user=k8s-at-home
+```
+
+4. Verify nodes are online
+   
+```sh
+kubectl --kubeconfig=./kubeconfig get nodes
+# NAME           STATUS   ROLES                       AGE     VERSION
+# k8s-master-a   Ready    control-plane,master      4d14h   v1.20.5+k3s1
+# k8s-worker-a   Ready    worker                    4d14h   v1.20.5+k3s1
+```
+
+### GitOps with Flux
+
+1. Pre-create the namespace
+   
+```sh
+kubectl --kubeconfig=./kubeconfig create namespace flux-system --dry-run=client -o yaml | kubectl apply -f -
+```
+
+1. Add the Flux GPG key in-order for Flux to decrypt SOPS secrets
+
+```sh
+gpg --export-secret-keys --armor "${FLUX_KEY_FP}" |
+kubectl --kubeconfig=./kubeconfig create secret generic sops-gpg \
+    --namespace=flux-system \
+    --from-file=sops.asc=/dev/stdin
+```
+
+3. Update files using `envsubst` or by updating them manually
+
+```sh
+export BOOTSTRAP_GITHUB_REPOSITORY="k8s-at-home/home-cluster"
+export BOOTSTRAP_DOMAIN="k8s-at-home.com"
+export BOOTSTRAP_METALLB_LB_RANGE="169.254.1.10-169.254.1.20"
+
+envsubst < ./.sops.yaml
+envsubst < ./cluster/cluster-secrets.yaml
+envsubst < ./cluster/cluster-settings.yaml
+envsubst < ./cluster/base/flux-system/gotk-sync.yaml
+```
+
+4. **Verify** all the above files have the correct information present
+
+5. Encrypt `cluster-settings.yaml` with SOPS
+
+```sh
+sops --encrypt --in-place ./cluster/base/cluster-secrets.yaml
+```
+
+6. **Verify** this file **is encrypted** with SOPS
+
+7. Push you changes to git
+
+```sh
+git add -A
+git commit -m "initial commit"
+git push
+```
+
+8. Install Flux
+
+```sh
+kubectl --kubeconfig=./kubeconfig --kustomize=./cluster/base/flux-system
+```
+
+## Post installation
+
+### pre-commit
+
+```sh
+pre-commit install-hooks
+```
 
 ## :handshake:&nbsp; Thanks
 

cluster/base/apps.yaml

@@ -0,0 +1,26 @@
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
+kind: Kustomization
+metadata:
+  name: apps
+  namespace: flux-system
+spec:
+  interval: 10m0s
+  dependsOn:
+  - name: core
+  path: ./cluster/apps
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  decryption:
+    provider: sops
+    secretRef:
+      name: sops-gpg
+  postBuild:
+    substitute: {}
+    substituteFrom:
+    - kind: ConfigMap
+      name: cluster-settings
+    - kind: Secret
+      name: cluster-secrets

cluster/base/cluster-secrets.yaml

@@ -0,0 +1,8 @@
+# yamllint disable
+apiVersion: v1
+kind: Secret
+metadata:
+    name: cluster-secrets
+    namespace: flux-system
+stringData:
+    SECRET_DOMAIN: $BOOTSTRAP_DOMAIN

cluster/base/cluster-settings.yaml

@@ -0,0 +1,8 @@
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-settings
+  namespace: flux-system
+data:
+  METALLB_LB_RANGE: $BOOTSTRAP_METALLB_LB_RANGE

cluster/base/core.yaml

@@ -0,0 +1,24 @@
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
+kind: Kustomization
+metadata:
+  name: core
+  namespace: flux-system
+spec:
+  interval: 10m0s
+  path: ./cluster/core
+  prune: false
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  decryption:
+    provider: sops
+    secretRef:
+      name: sops-gpg
+  postBuild:
+    substitute: {}
+    substituteFrom:
+    - kind: ConfigMap
+      name: cluster-settings
+    - kind: Secret
+      name: cluster-secrets

cluster/base/flux-system/charts/helm/bitnami-charts.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+  name: bitnami-charts
+  namespace: flux-system
+spec:
+  interval: 30m
+  url: https://charts.bitnami.com/bitnami
+  timeout: 2m

cluster/base/flux-system/charts/helm/ingress-nginx-charts.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+  name: ingress-nginx-charts
+  namespace: flux-system
+spec:
+  interval: 30m
+  url: https://kubernetes.github.io/ingress-nginx
+  timeout: 2m

cluster/base/flux-system/charts/helm/jetstack-charts.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+  name: jetstack-charts
+  namespace: flux-system
+spec:
+  interval: 30m
+  url: https://charts.jetstack.io/
+  timeout: 2m

cluster/base/flux-system/charts/helm/k8s-at-home-charts.yaml

@@ -0,0 +1,10 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+  name: k8s-at-home-charts
+  namespace: flux-system
+spec:
+  interval: 30m
+  url: https://k8s-at-home.com/charts/
+  timeout: 2m

cluster/base/flux-system/charts/helm/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- bitnami-charts.yaml
+- ingress-nginx-charts.yaml
+- jetstack-charts.yaml
+- k8s-at-home-charts.yaml

cluster/base/flux-system/charts/kustomization.yaml

@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- helm

cluster/base/flux-system/gotk-sync.yaml

@@ -0,0 +1,31 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  interval: 1m0s
+  ref:
+    branch: main
+  secretRef:
+    name: flux-system
+  url: ssh://git@github.com/$BOOTSTRAP_GITHUB_REPOSITORY
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
+kind: Kustomization
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  interval: 10m0s
+  path: ./cluster/base
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  validation: client
+  decryption:
+    provider: sops
+    secretRef:
+      name: sops-gpg

cluster/base/flux-system/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- gotk-components.yaml
+- gotk-sync.yaml
+- charts