docs: Initial documentation set up

This patch adds the initial structure for the documentation of the
Shivering-Isles GitOps Infrastructure repository. It uses mdbook to
create an easy to read documentation.

It uses mdbook, because it's an easy single-binary tool to generate
documentation. This fits the tooling schema of koolbox quite well and
can be easily integrated into the automatic updates toolchain already
used. Further it uses markdown, which allows easy writing of further
documentation and re-use of existing documentation.

The documentation structure re-uses various existing READMEs from
components. These might be replaced in the long run.

It also lays out future plans for documentation, which is currently
still on the TODO list. This should help to keep the overall structure
in mind and provide the general direction.

References:
https://rust-lang.github.io/mdBook/index.html

Makefile

@@ -18,6 +18,10 @@ cli: ## Install koolbox CLI (Contains all tools used in this project)
 cli-config: ## Configure koolbox CLI (To setup terraform values as well was tokens)
 	cd ./cli && make config
 
+.PHONY: docs
+docs: cli ## Build and render docs locally
+	cd ./docs && make serve
+
 .PHONY: validate
 validate:
 	./scripts/validate.sh

cli/Dockerfile

@@ -98,6 +98,18 @@ RUN set -x; mkdir -p /opt/krew; cd "/opt/krew" && \
   tar zxvf "${KREW}.tar.gz" && \
   mv "${KREW}" /opt/krew/krew
 
+# kubectl-krew CLI cache
+FROM registry.fedoraproject.org/fedora:35 as mdbook
+
+# renovate: datasource=github-releases depName=kubernetes-sigs/krew
+ARG MDBOOK_VERSION=v0.4.18
+ENV MDBOOK_VERSION=${MDBOOK_VERSION}
+
+RUN curl -L "https://github.com/rust-lang/mdBook/releases/download/${MDBOOK_VERSION}/mdbook-${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar xvzf - mdbook \
+    && install -o root -g root -m 0755 mdbook /usr/local/bin/mdbook
+
+
+
 # Actual start of container build
 FROM registry.fedoraproject.org/fedora:35
 
@@ -143,6 +155,7 @@ COPY --from=kubeval /usr/local/bin/kubeval /usr/local/bin/kubeval
 COPY --from=sops /usr/local/bin/sops /usr/local/bin/sops
 COPY --from=yq /usr/local/bin/yq /usr/local/bin/yq
 COPY --from=kubectl-krew /opt/krew/krew /usr/local/bin/kubectl-krew
+COPY --from=mdbook /usr/local/bin/mdbook /usr/local/bin/mdbook
 
 RUN true \
     && echo "command -v kubectl-krew >/dev/null && export PATH=\"${KREW_ROOT:-$HOME/.krew}/bin:$PATH\"" >> /root/.bashrc \
@@ -150,6 +163,7 @@ RUN true \
     && echo "command -v kustomize >/dev/null && . <(kustomize completion bash)" >> /root/.bashrc \
     && echo "command -v kubectl >/dev/null && . <(kubectl completion bash)" >> /root/.bashrc \
     && echo "command -v helm >/dev/null && . <(helm completion bash)" >> /root/.bashrc \
+    && echo "command -v mdbook >/dev/null && . <(mdbook completions bash)" >> /root/.bashrc \
     && true
 
 RUN true \

docs/.gitignore

+book

docs/Makefile

+
+include ../utils/help.mk
+
+.PHONY: serve
+serve: ## Render docs locally and provide them on localhost
+	cd ../ && koolbox mdbook serve docs
+

docs/book.toml

+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "src"

docs/src/SUMMARY.md

+# Summary
+
+# Infrastructure
+
+- [About](about.md)
+- [Hardware]()
+- [Operating System](operating_system.md)
+- [Network]()
+- [Continous Integreation]()
+- [GitOps]()
+- [Infrastructure Components](components/README.md)
+  - [calico](components/calico.md)
+  - [cert-manager](components/cert-manager.md)
+  - [flux]()
+  - [k8up](components/k8up.md)
+  - [longhorn](components/longhorn.md)
+  - [metallb](components/metallb.md)
+  - [monitoring]()
+  - [nginx-system](components/nginx-system.md)
+  - [node-features](components/node-features.md)
+  - [starboard](components/starboard.md)
+  - [system-upgrades](components/system-upgrades.md)
+- [Apps]()
+  - [DNS]()
+  - [hcloud-dynfw]()
+  - [mail]()
+  - [Matrix]()
+  - [Nextcloud]()
+  - [Registry]()

docs/src/about.md

+# Shivering Isles GitOps Infrastructure
+
+This documentation provides some insight into the Sivering-Isles GitOps Infrastructure. Into concepts, useful information and a general overview over all the different parts of the overall project.

docs/src/components/README.md

+# Components
+
+Overview over cluster components, their function, useful links and things that would have been nice to know beforehand.

docs/src/components/calico.md

+../../../infrastructure/calico/README.md
\ No newline at end of file

docs/src/components/cert-manager.md

+../../../infrastructure/cert-manager/README.md
\ No newline at end of file

docs/src/components/k8up.md

+../../../infrastructure/k8up/README.md
\ No newline at end of file

docs/src/components/longhorn.md

+../../../infrastructure/longhorn/README.md
\ No newline at end of file

docs/src/components/metallb.md

+../../../infrastructure/metallb/README.md
\ No newline at end of file

docs/src/components/nginx-system.md

+../../../infrastructure/nginx-system/README.md
\ No newline at end of file

docs/src/components/node-features.md

+../../../infrastructure/node-features/README.md
\ No newline at end of file

docs/src/components/starboard.md

+../../../infrastructure/starboard/README.md
\ No newline at end of file

docs/src/components/system-upgrades.md

+../../../infrastructure/system-upgrades/README.md
\ No newline at end of file

docs/src/operating_system.md

+# Operating System
+
+For this setup Fedora is the Operating System of choice for multiple reasons. It provides both image-based installation methods (e.g. Fedora CoreOS) as well as package-based installation methods (e.g. Fedora Server) for many architectures and provides a modern and stable set of packages. Further it matches the developer machine OS, which helps with debugging and testing things locally before pushing them onto the deployments.
+
+## OS requirements
+
+The OS requirements to run the current setup are:
+
+- modern software versions
+- Kubeadm support
+- cri-o support
+- TPM-based LUKS encryption
+- SELinux support
+- (optional) cockpit integration
+- (optional) SSH access
+- automated updates
+
+## Setup script
+
+Currently the following script is used for set up:
+
+```
+#!/bin/bash
+
+# System upgrade
+dnf upgrade -y
+
+# Prepare Kubernetes
+dnf copr enable -y "sheogorath/kubernetes-1.22"
+dnf install -y kubernetes kubernetes-kubeadm
+
+# Install Crio as container engine
+dnf module enable -y cri-o:1.22
+dnf install -y cri-o cri-tools
+systemctl enable --now crio
+
+# Load kernel modules for Kubernetes and Calico
+modprobe br_netfilter
+modprobe wireguard
+cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
+br_netfilter
+wireguard
+EOF
+
+# Prepare sysctls for Kubernetes
+cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
+net.bridge.bridge-nf-call-ip6tables = 1
+net.bridge.bridge-nf-call-iptables = 1
+net.ipv4.ip_forward = 1
+EOF
+sysctl --system
+
+dnf install -y iptables
+
+# Disable systemd-resolved for CoreDNS
+rm -f /etc/resolv.conf
+cp /run/systemd/resolve/resolv.conf /etc/resolv.conf
+systemctl disable --now systemd-resolved
+
+# Prepare NetworkManager for Calico
+cat <<EOF | sudo tee /etc/NetworkManager/conf.d/calico.conf
+[keyfile]
+unmanaged-devices=interface-name:cali*;interface-name:tunl*;interface-name:vxlan.calico;interface-name:wireguard.cali
+EOF
+systemctl restart NetworkManager
+
+systemctl mask firewalld
+
+# Disable zram swap
+dnf remove -y zram-generator-defaults
+
+# Setup TPM encryption
+dnf install -y clevis-dracut
+clevis luks bind -d /dev/nvme0n1p3 tpm2 '{}'
+dracut -f
+
+# Install management interface
+dnf install -y cockpit cockpit-pcp
+
+reboot
+```
+
+*Be aware that this interactive due to TPM set up*
+
+## Filesystem Layout
+
+|Path|Filesystem|Size |Description|
+|----|----------|-----|-----------|
+|`/` |`xfs`     |15GiB|Root filesystem set up by Fedora Server layout.|
+|`/boot/efi`|`vfat`|600MiB|Filesystem for EFI, set up by Fedora Server layout.|
+|`/var/lib/containers` |`xfs` |50GiB|Filesystem for container images.|
+|`/var/lib/kubelet` |`xfs` |20GiB|Filesystem for kubelet related storage, such as `emptyDir`|
+|`/var/lib/longhorn`|`xfs`|varies|Filesystem for longhorn storage, this is used by longhorn to provide high-available storage across the clusters.|
+|`/var/lib/storage`|`xfs`|varies|Additional filesystem for longhorn storage, this is used by longhorn to provide high-available storage across the clusters.|
+
+## Setup addition SSD
+
+```bash
+# Setup LUKS recovery key
+cryptsetup luksFormat /dev/sda
+cryptsetup isLuks /dev/sda
+cryptsetup luksDump /dev/sda
+cryptsetup luksUUID /dev/sda
+cryptsetup luksOpen /dev/sda storage
+# Encrypt with local TPM
+clevis luks bind -d /dev/sda tpm2 '{}'
+mkfs.xfs /dev/mapper/storage
+echo "storage UUID=$(cryptsetup luksUUID /dev/sda) none discard,timeout=15" >> /etc/crypttab
+echo "/dev/mapper/storage   /var/lib/storage           xfs     defaults,x-systemd.device-timeout=0 0 0" >> /etc/fstab
+mkdir -p /var/lib/storage
+chcon -t container_file_t /var/lib/storage/
+mount -a
+df -h /var/lib/storage/
+# Make sure decryption on reboot works
+systemctl enable clevis-luks-askpass.path
+```