Merge branch 'main' into markdownlint

Author: moller2866

.devcontainer/Dockerfile

@@ -0,0 +1,15 @@
+FROM jetpackio/devbox:latest
+
+# Installing your devbox project
+WORKDIR /code
+USER root:root
+RUN mkdir -p /code && chown ${DEVBOX_USER}:${DEVBOX_USER} /code
+USER ${DEVBOX_USER}:${DEVBOX_USER}
+COPY --chown=${DEVBOX_USER}:${DEVBOX_USER} devbox.json devbox.json
+COPY --chown=${DEVBOX_USER}:${DEVBOX_USER} devbox.lock devbox.lock
+
+
+
+RUN devbox run -- echo "Installed Packages."
+
+RUN devbox shellenv --init-hook >> ~/.profile

.devcontainer/devcontainer.json

@@ -0,0 +1,16 @@
+{
+  "name": "Devbox Remote Container",
+  "build": {
+    "dockerfile": "./Dockerfile",
+    "context": ".."
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "jetpack-io.devbox"
+      ]
+    }
+  },
+  "remoteUser": "devbox"
+}

README.md

@@ -4,8 +4,4 @@ An opinionated guide to on-prem Kubernetes
 
 ## How to run local
 
-- run `brew install hugo`
-- run `brew install go`
-- run `hugo serve --source .pages`
-
-When running the page is available at `http://localhost:1313/On-prem_Kubernetes_Guide/`
+For instructions on how to run this project, please refer to the [contributing.md](./contributing.md) file under `## Setting Up Your Development Environment` section.

contributing.md

@@ -27,3 +27,35 @@ Create a PR with your suggestions, it will automatically be assigned to the main
 ## Questions
 
 If in doubt you can always reach out to the maintainers of this guide, maintainers can be found in the codeowners file in the .github folder.
+
+## Setting Up Your Development Environment
+
+You can use either Devbox or Dev Containers to set up a consistent development environment for working on this guide.
+
+### Using Devbox
+
+1. Install [Devbox](https://www.jetpack.io/devbox/docs/installing_devbox/)
+2. Clone this repository
+3. Navigate to the repository root directory
+4. Run `devbox shell` to enter a shell with all the required dependencies
+5. You're now ready to make your changes!
+
+### Using Dev Containers
+
+1. Install [Visual Studio Code](https://code.visualstudio.com/) and the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
+2. Clone this repository
+3. Open the repository in VS Code
+4. When prompted to "Reopen in Container", click "Yes". Alternatively, press F1 and select "Remote-Containers: Reopen in Container"
+5. Wait for the container to build and start
+6. You now have a fully configured development environment!
+
+## Local Website Preview
+
+To preview the website locally while making changes:
+
+1. Run the Hugo development server:
+   ```
+   hugo server --source .pages
+   ```
+2. Open your browser and navigate to `http://localhost:1313/On-prem_Kubernetes_Guide/ `
+3. The website will automatically refresh when you make changes to the source files

devbox.json

@@ -0,0 +1,14 @@
+{
+  "$schema":  "https://raw.githubusercontent.com/jetify-com/devbox/0.13.4/.schema/devbox.schema.json",
+  "packages": ["hugo@latest"],
+  "shell": {
+    "init_hook": [
+      "echo 'Welcome to devbox!' > /dev/null"
+    ],
+    "scripts": {
+      "test": [
+        "echo \"Error: no test specified\" && exit 1"
+      ]
+    }
+  }
+}

devbox.lock

@@ -0,0 +1,53 @@
+{
+  "lockfile_version": "1",
+  "packages": {
+    "hugo@latest": {
+      "last_modified": "2025-02-07T11:26:36Z",
+      "resolved": "github:NixOS/nixpkgs/d98abf5cf5914e5e4e9d57205e3af55ca90ffc1d#hugo",
+      "source": "devbox-search",
+      "version": "0.143.0",
+      "systems": {
+        "aarch64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/6j6py1jcp5n2sh1p3ksskhjc33vjyga9-hugo-0.143.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/6j6py1jcp5n2sh1p3ksskhjc33vjyga9-hugo-0.143.0"
+        },
+        "aarch64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/h22mcig2r7y1az488nncnpskal07csl9-hugo-0.143.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/h22mcig2r7y1az488nncnpskal07csl9-hugo-0.143.0"
+        },
+        "x86_64-darwin": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/kly0866bbxhd16k6acjkqxw5ngh6i0ws-hugo-0.143.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/kly0866bbxhd16k6acjkqxw5ngh6i0ws-hugo-0.143.0"
+        },
+        "x86_64-linux": {
+          "outputs": [
+            {
+              "name": "out",
+              "path": "/nix/store/vn0sn422kq2d87g06x20dg4y6fm76r9l-hugo-0.143.0",
+              "default": true
+            }
+          ],
+          "store_path": "/nix/store/vn0sn422kq2d87g06x20dg4y6fm76r9l-hugo-0.143.0"
+        }
+      }
+    }
+  }
+}

docs/hardware_ready/ADRs/talos_as_os.md

@@ -0,0 +1,40 @@
+---
+title: "Use Talos OS as the Preferred Operating System for Kubernetes Operations"
+date: "2025-02-25"
+---
+
+
+| status: | date: | decision-makers: |
+| --- | --- | --- |
+| proposed | 2025-02-25 | Sofus Albertsen |
+
+
+## Context and Problem Statement
+
+Choosing the right operating system for your Kubernetes cluster is crucial for stability, security, and operational efficiency.  The OS should be optimized for container workloads, minimize overhead, and integrate well with Infrastructure as Code (IaC) practices.
+## Considered Options
+
+* Talos OS
+* Red Hat OpenShift
+* SUSE Rancher (RancherOS/RKE)
+
+## Decision Outcome
+
+Chosen option: **Talos OS**, because its minimal footprint, API-driven configuration, and singular focus on Kubernetes make it ideal for automated infrastructure management and reduce operational overhead.
+
+Talos OS's immutable architecture and security-focused design further enhance its suitability for Kubernetes deployments, giving you a minimal attack surface from the OS point of view. As an example, the OS does not have any shell, so no bash scripts can be executed.
+
+OpenShift and Rancher were considered, but their comprehensive feature sets, while beneficial in some scenarios, introduce increased complexity and overhead.
+
+While their dashboards can simplify initial setup, they can also encourage "click-ops" and deviate from IaC best practices.  These platforms might be suitable if existing Red Hat or SUSE expertise is a primary driver, but becuase they are fully fledged OS's underneath, they introduce more operational overhead than Talos.
+
+### Consequences
+
+* **Good:** Talos OS's minimal package selection makes it a smaller attack surface.
+* **Good:** The API-driven configuration of Talos OS allows for seamless integration with IaC tools like Terraform, enabling fully automated cluster provisioning and management.
+* **Good:** The immutable infrastructure of Talos OS simplifies updates and adds recilliency because of it's dual boot bank setup.
+* **Good:** The "two package" approach simplifies maintenance (day 2 operations) and reduces the likelihood of OS-related issues, as all known package combinations can be tested from the vendor.
+
+* **Bad:**  The learning curve for Talos OS might be steeper initially for teams unfamiliar with its API-driven approach.
+* **Bad:**  The lack of a graphical user interface might be a drawback for some users accustomed to traditional OS management.
+* **Bad:** Talos is a relatively newer project compared to OpenShift or Rancher, therefore community support and available resources might be smaller. 

docs/hardware_ready/_index.md

@@ -15,7 +15,7 @@ In case virtualisation is chosen, the below recommendations are what you would r
 
 | Problem domain | Description | Reason for importance | Tool recommendation |
 |:---:|:---:|:---:|:---:|
-| Kubernetes Node Operating System | The Operating System running on each of the hosts that will be part of your Kubernetes cluster | Choosing the right OS will be the foundation for building a production-grade Kubernetes cluster |  |
+| Kubernetes Node Operating System | The Operating System running on each of the hosts that will be part of your Kubernetes cluster | Choosing the right OS will be the foundation for building a production-grade Kubernetes cluster | [Talos OS](hardware_ready/ADRs/talos_as_os.md) |
 | Storage solution | The underlying storage capabilities which Kubernetes will leverage to provide persistence for stateful workloads | Choosing the right storage solution for your clusters needs is important as there is a lot of balance tradeoffs associated with it, e.g redundancy vs. complexity |  |
 | Container Runtime (CRI) | The software that is responsible for running containers | You need a working container runtime on each node in your cluster, so that the kubelet can launch pods and their containers |  |
 | Network plugin (CNI) | Plugin used for cluster networking | A CNI plugin is required to implement the Kubernetes network model | [Cilium](Cilium_as_network_plugin.md) |