From bfdafa631e81202b76802873f11d4296426a605f Mon Sep 17 00:00:00 2001
From: Sheogorath <sheogorath@shivering-isles.com>
Date: Sun, 30 Jan 2022 22:34:48 +0100
Subject: [PATCH] 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 | 4 +
cli/Dockerfile | 14 +++
docs/.gitignore | 1 +
docs/Makefile | 7 ++
docs/book.toml | 5 ++
docs/src/SUMMARY.md | 29 +++++++
docs/src/about.md | 3 +
docs/src/components/README.md | 3 +
docs/src/components/calico.md | 1 +
docs/src/components/cert-manager.md | 1 +
docs/src/components/k8up.md | 1 +
docs/src/components/longhorn.md | 1 +
docs/src/components/metallb.md | 1 +
docs/src/components/nginx-system.md | 1 +
docs/src/components/node-features.md | 1 +
docs/src/components/starboard.md | 1 +
docs/src/components/system-upgrades.md | 1 +
docs/src/operating_system.md | 116 +++++++++++++++++++++++++
18 files changed, 191 insertions(+)
create mode 100644 docs/.gitignore
create mode 100644 docs/Makefile
create mode 100644 docs/book.toml
create mode 100644 docs/src/SUMMARY.md
create mode 100644 docs/src/about.md
create mode 100644 docs/src/components/README.md
create mode 120000 docs/src/components/calico.md
create mode 120000 docs/src/components/cert-manager.md
create mode 120000 docs/src/components/k8up.md
create mode 120000 docs/src/components/longhorn.md
create mode 120000 docs/src/components/metallb.md
create mode 120000 docs/src/components/nginx-system.md
create mode 120000 docs/src/components/node-features.md
create mode 120000 docs/src/components/starboard.md
create mode 120000 docs/src/components/system-upgrades.md
create mode 100644 docs/src/operating_system.md
diff --git a/Makefile b/Makefile
index 05af93f94..cfe0555dc 100644
--- a/Makefile
+++ b/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
diff --git a/cli/Dockerfile b/cli/Dockerfile
index fbc3f471c..ce3cd8fde 100644
--- a/cli/Dockerfile
+++ b/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 \
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..7585238ef
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 000000000..d099dd4e6
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,7 @@
+
+include ../utils/help.mk
+
+.PHONY: serve
+serve: ## Render docs locally and provide them on localhost
+ cd ../ && koolbox mdbook serve docs
+
diff --git a/docs/book.toml b/docs/book.toml
new file mode 100644
index 000000000..d34134a46
--- /dev/null
+++ b/docs/book.toml
@@ -0,0 +1,5 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "src"
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
new file mode 100644
index 000000000..a2f4780a9
--- /dev/null
+++ b/docs/src/SUMMARY.md
@@ -0,0 +1,29 @@
+# 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]()
diff --git a/docs/src/about.md b/docs/src/about.md
new file mode 100644
index 000000000..786d8e132
--- /dev/null
+++ b/docs/src/about.md
@@ -0,0 +1,3 @@
+# 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.
diff --git a/docs/src/components/README.md b/docs/src/components/README.md
new file mode 100644
index 000000000..ef2c13541
--- /dev/null
+++ b/docs/src/components/README.md
@@ -0,0 +1,3 @@
+# Components
+
+Overview over cluster components, their function, useful links and things that would have been nice to know beforehand.
diff --git a/docs/src/components/calico.md b/docs/src/components/calico.md
new file mode 120000
index 000000000..8e569ec36
--- /dev/null
+++ b/docs/src/components/calico.md
@@ -0,0 +1 @@
+../../../infrastructure/calico/README.md
\ No newline at end of file
diff --git a/docs/src/components/cert-manager.md b/docs/src/components/cert-manager.md
new file mode 120000
index 000000000..8f8b23fbc
--- /dev/null
+++ b/docs/src/components/cert-manager.md
@@ -0,0 +1 @@
+../../../infrastructure/cert-manager/README.md
\ No newline at end of file
diff --git a/docs/src/components/k8up.md b/docs/src/components/k8up.md
new file mode 120000
index 000000000..da5bac019
--- /dev/null
+++ b/docs/src/components/k8up.md
@@ -0,0 +1 @@
+../../../infrastructure/k8up/README.md
\ No newline at end of file
diff --git a/docs/src/components/longhorn.md b/docs/src/components/longhorn.md
new file mode 120000
index 000000000..650cc4b18
--- /dev/null
+++ b/docs/src/components/longhorn.md
@@ -0,0 +1 @@
+../../../infrastructure/longhorn/README.md
\ No newline at end of file
diff --git a/docs/src/components/metallb.md b/docs/src/components/metallb.md
new file mode 120000
index 000000000..071c398a7
--- /dev/null
+++ b/docs/src/components/metallb.md
@@ -0,0 +1 @@
+../../../infrastructure/metallb/README.md
\ No newline at end of file
diff --git a/docs/src/components/nginx-system.md b/docs/src/components/nginx-system.md
new file mode 120000
index 000000000..61c6a3980
--- /dev/null
+++ b/docs/src/components/nginx-system.md
@@ -0,0 +1 @@
+../../../infrastructure/nginx-system/README.md
\ No newline at end of file
diff --git a/docs/src/components/node-features.md b/docs/src/components/node-features.md
new file mode 120000
index 000000000..93eff175a
--- /dev/null
+++ b/docs/src/components/node-features.md
@@ -0,0 +1 @@
+../../../infrastructure/node-features/README.md
\ No newline at end of file
diff --git a/docs/src/components/starboard.md b/docs/src/components/starboard.md
new file mode 120000
index 000000000..2230c00d2
--- /dev/null
+++ b/docs/src/components/starboard.md
@@ -0,0 +1 @@
+../../../infrastructure/starboard/README.md
\ No newline at end of file
diff --git a/docs/src/components/system-upgrades.md b/docs/src/components/system-upgrades.md
new file mode 120000
index 000000000..74f67f4e3
--- /dev/null
+++ b/docs/src/components/system-upgrades.md
@@ -0,0 +1 @@
+../../../infrastructure/system-upgrades/README.md
\ No newline at end of file
diff --git a/docs/src/operating_system.md b/docs/src/operating_system.md
new file mode 100644
index 000000000..237e9e46b
--- /dev/null
+++ b/docs/src/operating_system.md
@@ -0,0 +1,116 @@
+# 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
+```
--
GitLab