diff --git a/.gitignore b/.gitignore index 4e2deb94..636d3568 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ -.vagrant/ .venv/ book/ diff --git a/README.md b/README.md index 73c99c7f..aae7efcb 100644 --- a/README.md +++ b/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 diff --git a/docs/book.toml b/docs/book.toml index fda6bfa6..6802f1e7 100644 --- a/docs/book.toml +++ b/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" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 6bdd0fa7..8825e1d1 100644 --- a/docs/src/SUMMARY.md +++ b/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) diff --git a/docs/src/deployment/configuration.md b/docs/src/deployment/configuration.md index d3ea36b8..04e28254 100644 --- a/docs/src/deployment/configuration.md +++ b/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: diff --git a/docs/src/deployment/dns.md b/docs/src/deployment/dns.md index 3bc1004d..198fb4ca 100644 --- a/docs/src/deployment/dns.md +++ b/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 diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 6ade257c..a415a5d7 100644 --- a/docs/src/introduction.md +++ b/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. diff --git a/docs/src/try-locally.md b/docs/src/try-locally.md new file mode 100644 index 00000000..7833ae2d --- /dev/null +++ b/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 + + +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 +``` diff --git a/docs/src/try-on-a-vm.md b/docs/src/try-on-a-vm.md deleted file mode 100644 index 081533d3..00000000 --- a/docs/src/try-on-a-vm.md +++ /dev/null @@ -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 - -## Clean up - -Shut down the VM: - -```sh -cd metal -vagrant destroy -``` - -Then clean up your DNS config from the previous step. diff --git a/metal/Makefile b/metal/Makefile index 9ab38ea4..35acd211 100644 --- a/metal/Makefile +++ b/metal/Makefile @@ -20,6 +20,3 @@ cluster: console: ansible-console \ --inventory inventories/${env}.yml - -vagrant: - vagrant up diff --git a/metal/Vagrantfile b/metal/Vagrantfile deleted file mode 100644 index fb5cfc58..00000000 --- a/metal/Vagrantfile +++ /dev/null @@ -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 diff --git a/metal/inventories/dev.yml b/metal/inventories/dev.yml deleted file mode 100644 index ab1bbbe2..00000000 --- a/metal/inventories/dev.yml +++ /dev/null @@ -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} diff --git a/metal/k3d-dev.yaml b/metal/k3d-dev.yaml new file mode 100644 index 00000000..02fa686d --- /dev/null +++ b/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 diff --git a/tools/Dockerfile b/tools/Dockerfile index 01092d97..660d474f 100644 --- a/tools/Dockerfile +++ b/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