From 491406a080307e450dde30b80d4444509ee22eb6 Mon Sep 17 00:00:00 2001
From: Khue Doan <mail@khuedoan.com>
Date: Thu, 10 Feb 2022 19:11:16 +0700
Subject: [PATCH] docs: add detailed steps in provisioning flow

---
 docs/src/deployment/provisioning_flow.md | 82 ++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/src/deployment/provisioning_flow.md b/docs/src/deployment/provisioning_flow.md
index 6200c3e6..e518c1b3 100644
--- a/docs/src/deployment/provisioning_flow.md
+++ b/docs/src/deployment/provisioning_flow.md
@@ -1,5 +1,7 @@
 # Provisioning flow
 
+## Overview
+
 ![Provisioning flow](../images/provisioning_flow.png)
 
 Everything is automated, after you edit the configuration files, you just need to run a single `make` command and it will:
@@ -17,3 +19,83 @@ From now on, ArgoCD will do the rest:
 - Build the `./system` layer (storage, networking, monitoring, etc)
 - Build the `./platform` layer (Gitea, Vault, SSO, etc)
 - Build the `./apps` layer: (Syncthing, Jellyfin, etc)
+
+## Detailed steps
+
+Below is the pseudo code for the entire process, you don't have to read it right now, but it will be handy for debugging.
+
+```
+Human run make:
+    build ./metal:
+        install the OS:
+            download the installer image and extract it
+            create a PXE server on the controller using Docker Compose:
+                DHCP server
+                TFTP server
+                HTTP server
+            create init config for each machine
+            turn the machines on via WoL
+            the machines boot:
+                select network boot automatically
+                broadcast DHCP request
+                DHCP server reply:
+                    machine IP
+                    TFTP server (next-server) IP
+                get boot files from TFTP server
+                    GRUB
+                    GRUB config with URL to init config based on MAC address
+                    kernel
+                    initrd
+                boot to the kernel
+                download from HTTP server:
+                    init config from the URL in GRUB config
+                    remaining files required to boot
+                install the OS based on the init config:
+                    configure the system
+                    remaining files required to install
+                reboot to the new OS
+            controller see the machines are ready
+        build a Kubernetes cluster:
+            download k3s binary
+            generate cluster token
+            copy k3s config files
+            enable k3s service and form a cluster
+            create KUBECONFIG file
+            create MetalLB config:
+                use the last /27 subnet of the network
+                apply the config
+    build ./bootstrap:
+        install ArgoCD:
+            apply helm chart
+            wait for status
+        install root app:
+            select values file:
+                if Gitea unreachable (first install):
+                    get data from GitHub
+                else:
+                    get data from Gitea
+            apply helm chart
+            wait for status
+ArgoCD apply the rest:
+    clone git repo
+    install components based on directories:
+        ./bootstrap (it manages itself):
+            argocd
+            root
+        ./system:
+            storage
+            loadbalancer
+            ingress
+            etc
+        ./platform (depends on ./system):
+            git:
+                migrate the homelab repository from GitHub
+                ArgoCD switch the source from GitHub to Gitea
+            ci
+            vault
+            etc
+        ./apps (depends on ./system and ./platform):
+            homepage
+            jellyfin
+            etc
+```