refactor!: switch dev environment from Vagrant to k3d

.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

@@ -8,9 +8,9 @@ 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           |
+| 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

@@ -1,54 +0,0 @@
-# Try on a VM
-
-## Prerequisites
-
-Install the following packages:
-
-- `docker`
-- `make`
-- `vagrant`
-- `virtualbox`
-
-VM specifications:
-
-```ruby
-# metal/Vagrantfile
-{{#include ../../metal/Vagrantfile:vm_specs}}
-```
-
-## Configuration
-
-Follow the the steps in the [configuration guide](./deployment/configuration.md).
-
-## Build
-
-```sh
-VAGRANT_CWD=./metal vagrant up
-```
-
-Open the tools container:
-
-```sh
-make tools
-```
-
-Build a cluster on the test VM and bootstrap it:
-
-```
-make dev
-```
-
-Finally follow the [DNS guide](./deployment/dns.md) to update your DNS setup.
-
-Now you can visit the dashboard at <https://home.example.com>
-
-## Clean up
-
-Shut down the VM:
-
-```sh
-cd metal
-vagrant destroy
-```
-
-Then clean up your DNS config from the previous step.

metal/Makefile

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

metal/Vagrantfile

@@ -1,47 +0,0 @@
-require 'yaml'
-
-inventory = YAML.load_file(File.join(__dir__, './inventories/dev.yml'))
-group_vars = YAML.load_file(File.join(__dir__, './group_vars/all.yml'))
-
-# ANCHOR: vm_specs
-cpus = 2
-memory = "8192"
-disk_size = "128GB"
-# ANCHOR_END: vm_specs
-
-Vagrant.configure("2") do |config|
-  config.vm.box = "rockylinux/8"
-
-  inventory['metal']['children'].each do |group, properties|
-    properties['hosts'].each do |host, host_vars|
-      config.vm.define host do |node|
-        ip = host_vars['ansible_host']
-        node.vm.network "public_network", ip: ip
-        node.vm.hostname = host
-        node.vm.disk :disk, size: disk_size, primary: true
-      end
-    end
-  end
-
-  config.vm.provider "virtualbox" do |vb|
-    vb.cpus   = cpus
-    vb.memory = memory
-  end
-
-  config.vm.provision "file",
-    source: "#{group_vars['ansible_ssh_private_key_file']}.pub",
-    destination: "/tmp/id_ed25519.pub"
-
-  # TODO move most of this to Ansible?
-  config.vm.provision "shell",
-    reboot: true,
-    inline: <<-SHELL
-      mkdir /#{group_vars['ansible_user']}/.ssh
-      cat /tmp/id_ed25519.pub >> ~#{group_vars['ansible_user']}/.ssh/authorized_keys
-      sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
-      dnf install -y iscsi-initiator-utils
-      systemctl enable --now iscsid
-      sysctl fs.inotify.max_user_instances=8192
-      sysctl -p
-    SHELL
-end

metal/inventories/dev.yml

@@ -1,11 +0,0 @@
-# TODO support multiple nodes (doesn't work yet)
-metal:
-  children:
-    masters:
-      hosts:
-        dev0: {ansible_host: 192.168.1.10}
-        # dev1: {ansible_host: 192.168.1.11}
-        # dev2: {ansible_host: 192.168.1.12}
-    workers:
-      hosts: {}
-        # dev3: {ansible_host: 192.168.1.13}

metal/k3d-dev.yaml

@@ -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

tools/Dockerfile

@@ -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