Add home page readme

00-provisioning/README.md

@@ -1,40 +1,27 @@
 # 00-Provisioning
 
-Adding new nodes
+Provisioning is the process of creating and installing the machine and operating system to prepare it for workloads.  There are many terrafic tools for this, but my needs are simple and I don't like needless abstractions, so I rolled my own found in the **helpers.sh* file.  
 
-1. Call lighter and pass the new node's name to generate ignition files for the node, see below snippet.
-2. Commit and check the resulting ignition/*.json files into version control at deadbeef.codes, they need to be present before booting the node.
+OS of choice is [Fedora CoreOS](https://fedoraproject.org/coreos/) because of all the distributions I've reviewed it seems to be the most lightweight, purpose-built choice that meets requirements.  
+
+### Lighter
+
+Lighter is a small utility function in *helpers.sh* I made for templating Butane YAML files, allowing for value substitution.  It's a "lighter" method to template compared to something more featurerific like Jinja.
+
+### Butane
+
+Butane is a utility for transforming human-readable butane YAML configuration files and transpile them to machine-readable ignition JSON files.  The JSON is still readable in many cases, but good luck reading a systemd unit file or anything with more than a few lines
+
+### Ignition
+
+Core-OS comes with Ignition which is similar to utilities like cloud-init.  Allows completely configuring the system.  When adding a new node, or making a change to butane YAML files, be sure to run lighter and pass the node's hostname.  It will generate JSON files in the ignition directory which need to be checked into version control.  The machine needs to be able to access the files when it boots.
 
 ```bash
 # Be sure to run from 00-provisioning directory
 cd 00-provisioning
+source helpers.sh
 
-# Templating for Butane files to replace hostname with name passed 
-# to lighter, then it calls butane to generate ignition files
-lighter() {
-    if [ -z "$1" ]; then
-        echo "error: lighter() called without specifying a VM name"
-        echo "Usage: lighter() <name>"
-        return
-    fi
-
-    # Create temporary working copies
-    cp butane/boot.yaml butane/boot~.yaml
-    cp butane/full.yaml butane/full~.yaml
-
-    # Replace hostname token with name provided
-    hostnameToken="{{HOSTNAME}}"
-    sed -i -e "s/$hostnameToken/$1/g" butane/boot~.yaml
-    sed -i -e "s/$hostnameToken/$1/g" butane/full~.yaml
-
-    # Butane transpile to ignition files
-    butane butane/boot~.yaml > ignition/$1-boot.json
-    butane butane/full~.yaml > ignition/$1-full.json
-
-    # Cleanup mess
-    rm -f butane/*~.yaml
-}
-
+# Run lighter to substitute the machine's hostnames in the butane/full.yaml file, and call butane with each hostname to generate the ignition/*.yaml files
 lighter kube-control01
 lighter kube-control02
 lighter kube-control03
@@ -42,51 +29,21 @@ lighter kube-worker01
 lighter kube-worker02
 lighter kube-worker03
 
-
 ```
 
 After you've checked the ignition files into version control, provision the server, either on baremetal or VM - example with virtualbox.  Use a method to point it to the boot ignition file, in virtual box guest properties can be used.
 
 ```bash
 
-# Terraform?  We roll our own.
-
-# Stop git bash being stupid
-export MSYS_NO_PATHCONV=1
-
-# Be sure to run from 00-provisioning directory
-cd 00-provisioning
-
-# Set your own
-VBOXMANAGE="C:/Program Files/Oracle/VirtualBox/vboxmanage"
-COREOSAPPLIANCEIMAGE="D:/VirtualBox/OVA/fedora-coreos-39.20231119.3.0-virtualbox.x86_64.ova"
-
-# Function to create VirtualBox VM, accepts name of VM as argument
-create_vm() {
-    if [ -z "$1" ] || [ -z "$2" ]; then
-        echo "error: create_vm() called without specifying a VM name"
-        echo "Usage: create_vm <name> <MAC Address>"
-        echo "Example: create_vm kube_control01 \"08:00:27:00:00:01\""
-        return
-    fi
-
-    "$VBOXMANAGE" import --vsys 0 --vmname "$1" $COREOSAPPLIANCEIMAGE
-    "$VBOXMANAGE" modifyvm $1 --nic1 bridged
-    "$VBOXMANAGE" modifyvm $1 --bridge-adapter1 "Intel(R) Ethernet Controller I225-V"
-    "$VBOXMANAGE" modifyvm $1 --macaddress1 $2
-    "$VBOXMANAGE" guestproperty set $1 "/Ignition/Config" "$(cat ignition/$1-boot.json)"
-    "$VBOXMANAGE" startvm $1 --type headless
-}
-
 # Controllers - if doing HA, need at least 3 for Raft concensus
-create_vm kube-control01 "080027000001"
-create_vm kube-control02 "080027000002"
-create_vm kube-control03 "080027000003"
+create_vbox_vm kube-control01 "080027000001"
+create_vbox_vm kube-control02 "080027000002"
+create_vbox_vm kube-control03 "080027000003"
 
 # Workers
-create_vm kube-worker01 "080027000010"
-create_vm kube-worker02 "080027000011"
-create_vm kube-worker03 "080027000012"
+create_vbox_vm kube-worker01 "080027000010"
+create_vbox_vm kube-worker02 "080027000011"
+create_vbox_vm kube-worker03 "080027000012"
 
 ```
 

00-provisioning/butane/full.yaml

@@ -1,8 +1,10 @@
+# DO NOT CALL BUTANE DIRECTLY AGAINST THIS FILE
+# IT IS MEANT TO BE CALLED BY lighter
 variant: fcos
 version: 1.5.0
 storage:
   files:
-    # Hostname
+    # Hostname gets replaced with lighter
     - path: /etc/hostname
       mode: 420
       overwrite: true

00-provisioning/helpers.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# Terraform?  We roll our own.
+
+# Stop git bash being stupid
+export MSYS_NO_PATHCONV=1
+
+# Set your own
+VBOXMANAGE="C:/Program Files/Oracle/VirtualBox/vboxmanage"
+COREOSAPPLIANCEIMAGE="D:/VirtualBox/OVA/fedora-coreos-39.20231119.3.0-virtualbox.x86_64.ova"
+
+# Function to create VirtualBox VM, accepts name of VM as argument
+create_vbox_vm() {
+    if [ -z "$1" ] || [ -z "$2" ]; then
+        echo "error: create_vm() called without specifying a VM name"
+        echo "Usage: create_vm <name> <MAC Address>"
+        echo "Example: create_vm kube_control01 \"08:00:27:00:00:01\""
+        return
+    fi
+
+    "$VBOXMANAGE" import --vsys 0 --vmname "$1" $COREOSAPPLIANCEIMAGE
+    "$VBOXMANAGE" modifyvm $1 --nic1 bridged
+    "$VBOXMANAGE" modifyvm $1 --bridge-adapter1 "Intel(R) Ethernet Controller I225-V"
+    "$VBOXMANAGE" modifyvm $1 --macaddress1 $2
+    "$VBOXMANAGE" guestproperty set $1 "/Ignition/Config" "$(cat ignition/$1-boot.json)"
+    "$VBOXMANAGE" startvm $1 --type headless
+}
+
+# Templating for Butane files to replace hostname with name passed 
+# to lighter, then it calls butane to generate ignition files
+# It's "lighter" than using jinja or some other bloat ;)
+# This allows us to re-use the same butane YAML files for multiple hosts,
+# we can substitute values with whatever we want.
+lighter() {
+    if [ -z "$1" ]; then
+        echo "error: lighter() called without specifying a VM name"
+        echo "Usage: lighter() <name>"
+        return
+    fi
+
+    # Create temporary working copies 
+    cp butane/boot.yaml butane/boot~.yaml
+    cp butane/full.yaml butane/full~.yaml
+
+    # Replace hostname token with name provided
+    hostnameToken="{{HOSTNAME}}"
+    sed -i -e "s/$hostnameToken/$1/g" butane/boot~.yaml
+    sed -i -e "s/$hostnameToken/$1/g" butane/full~.yaml
+
+    # Butane transpile to ignition files
+    butane butane/boot~.yaml > ignition/$1-boot.json
+    butane butane/full~.yaml > ignition/$1-full.json
+
+    # Cleanup mess
+    rm -f butane/*~.yaml
+}

README.md

@@ -0,0 +1,6 @@
+# deadbeef.codes-k8s
+
+This is documentation and a process I've created for bootstrapping a Kubernetes cluster on bare metal or VMs without using a cloud provider managed service.   My use case for this is running my own personal services, and learning more about Kubernetes as I study for the CKA exam.
+
+Each section can be followed in numerical order.  
+