refactor!: switch dev environment from Vagrant to k3d

Author: khuedoan

.gitignore

@@ -1,4 +1,3 @@
-.vagrant/
 .venv/
 book/
 

README.md

@@ -223,7 +223,7 @@ They can't capture all of the project's features, but they are sufficient to get
 
 ## Get Started
 
-- [Try it out on a VM](https://homelab.khuedoan.com/try-on-a-vm.html) without any hardware
+- [Try it out locally](https://homelab.khuedoan.com/try-locally.html) without any hardware
 - [Deploy on real hardware](https://homelab.khuedoan.com/deployment) for real workload
 
 ## Roadmap

docs/book.toml

@@ -8,3 +8,7 @@ title = "Khue's Homelab"
 [output.html]
 git-repository-url = "https://github.com/khuedoan/homelab"
 edit-url-template = "https://github.com/khuedoan/homelab/edit/master/docs/{path}"
+
+# TODO deprecate this after 6 months
+[output.html.redirect]
+"/try-on-a-vm.html" = "/try-locally.html"

docs/src/SUMMARY.md

@@ -1,7 +1,7 @@
 # Summary
 
 - [Introduction](introduction.md)
-- [Try on a VM](try-on-a-vm.md)
+- [Try locally](try-locally.md)
 - [Deployment](./deployment/README.md)
   - [Provisioning flow](./deployment/provisioning-flow.md)
   - [Prerequisites](./deployment/prerequisites.md)

docs/src/deployment/configuration.md

@@ -7,10 +7,10 @@ it's the source of truth for my homelab, so you'll need to fork it to make it yo
 
 ## Choose the environment
 
-| Environment | Branch   | Recommended setup             |
-| ----------- | -------- | ----------------------------- |
-| Production  | `master` | Real hardware                 |
-| Development | `dev`    | A single Vagrant VM           |
+| Environment | Branch   | Recommended setup                     |
+| ----------- | -------- | ------------------------------------- |
+| Production  | `master` | Real hardware                         |
+| Development | `dev`    | A local [k3d](https://k3d.io) cluster |
 
 For example, if you're trying out the dev VM, use the development environment:
 

docs/src/deployment/dns.md

@@ -5,7 +5,7 @@ Because everyone DNS setup are different, DNS automation is not in the scope of
 
 Some options for DNS config (choose one):
 
-- Use nip.io (suitable for a test environment)
+- Use [nip.io](https://nip.io) (suitable for a test environment)
 - Change the DNS config in your router
 - Change the DNS config at your domain registrar (doesn't work with the [`home.arpa`](https://datatracker.ietf.org/doc/html/rfc8375) domain)
 
@@ -17,7 +17,7 @@ Before continuing to the next section for some examples, run this command to get
 
 ## Use nip.io
 
-TODO
+Preconfigured in the `dev` branch.
 
 ## In your router
 

docs/src/introduction.md

@@ -2,4 +2,4 @@
 
 {{#include ../../README.md:introduction}}
 
-Continue to the next section to try on a VM, or skip to the deployment guide to deploy on real hardware.
+Continue to the next section to try locally, or skip to the deployment guide to deploy on real hardware.

docs/src/try-locally.md

@@ -0,0 +1,57 @@
+# Try locally
+
+## Caveats compare to production environment
+
+The development cluster doesn't have the following features:
+
+- There is no valid domain name, hence no SSL certificates (some services require valid SSL certificates)
+- Only accessible on the host machine
+- No backup
+<!-- TODO more caveats here -->
+
+Please keep in mind that the development cluster may be unstable and things may break (it's for development after all).
+
+## Prerequisites
+
+Host machine:
+
+- OS: Linux (Windows and macOS are untested)
+- Recommended hardware specifications:
+  - CPU: 4 cores
+  - RAM: 16 GiB
+
+Install the following packages:
+
+- `docker`
+- `make`
+
+Clone the repository (follow the [configuration guide](./deployment/configuration.md) if you want to customize it):
+
+```sh
+git clone https://github.com/khuedoan/homelab
+git checkout dev
+```
+
+## Build
+
+Open the tools container:
+
+```sh
+make tools
+```
+
+Build a development cluster and bootstrap it:
+
+```
+make
+```
+
+Look for the dashboard URL in the command output.
+
+## Clean up
+
+Delete the cluster:
+
+```sh
+k3d cluster delete homelab-dev
+```

docs/src/try-on-a-vm.md

@@ -20,6 +20,3 @@ cluster:
 console:
 	ansible-console \
 		--inventory inventories/${env}.yml
-
-vagrant:
-	vagrant up

metal/Makefile

@@ -0,0 +1,20 @@
+apiVersion: k3d.io/v1alpha4
+kind: Simple
+metadata:
+  name: homelab-dev
+image: docker.io/rancher/k3s:v1.23.4-k3s1
+servers: 3
+agents: 0
+options:
+  k3s:
+    extraArgs:
+      - arg: --disable=local-storage
+        nodeFilters:
+          - server:*
+      - arg: --disable=traefik
+        nodeFilters:
+          - server:*
+      - arg: --disable-cloud-controller
+        nodeFilters:
+          - server:*
+subnet: 172.28.0.0/16

metal/Vagrantfile

@@ -34,5 +34,9 @@ RUN pacman --sync --refresh --noconfirm \
         sudo \
         terraform
 
+# TODO better way to install k3d?
+RUN curl -L https://github.com/k3d-io/k3d/releases/download/v5.4.1/k3d-linux-amd64 > /usr/local/bin/k3d \
+    && chmod +x /usr/local/bin/k3d
+
 # TODO https://github.com/ansible-collections/community.docker/issues/216
 RUN pip install docker-compose