From 1523b15952987cc23f87a7845d480be9bf89327c Mon Sep 17 00:00:00 2001 From: June Date: Sun, 25 Jan 2026 21:11:07 +0100 Subject: [PATCH 1/3] docs: improve formatting and wording a bit to make things clearer --- docs/create-new-web-service-vm.md | 55 +++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/docs/create-new-web-service-vm.md b/docs/create-new-web-service-vm.md index 1f5874d..da8293b 100644 --- a/docs/create-new-web-service-vm.md +++ b/docs/create-new-web-service-vm.md @@ -5,36 +5,47 @@ Let's assume that you want to add a new web service `example.hamburg.ccc.de` whi ## IP, DNS, VM 1. Allocate a fresh [IPv6 in Netbox in the 2a00:14b0:42:102::/64 net](https://netbox.hamburg.ccc.de/ipam/prefixes/47/ip-addresses/). This will be the management address for the VM. -2. Add an entry `example.hosts.hamburg.ccc.de` with that AAAA to the name server (`ns-intern`). -3. Add an entry `example.hamburg.ccc.de` as a CNAME for `public-reverse-proxy` to the same zone. -4. Commit and reload the zone. -5. Create a new VM on chaosknoten, for example by cloning the Debian template 9023. Give it the name `example`. -6. Edit the ethernet interface to be connected to `vmbr0`, VLAN tag `2`. -7. Configure the IPv6 address in the Cloud-Init section. Leave IPv4 set to DHCP. -8. Make sure the VM is started at boot (options). -9. Adjust any other VM parameters as needed. -10. Boot the VM. -11. Add the [VM to Netbox](https://netbox.hamburg.ccc.de/virtualization/virtual-machines/). Make sure to enter the VM ID. -12. Add an Ethernet interface to the VM; we typically use `eth0` as a name. -13. Add IP for that interface, then choose "Assign IP" and search for the IP you've created. Make it the primary IP of that interface. +2. On `ns-intern`: + 1. Add an entry `example.hosts.hamburg.ccc.de` as an AAAA pointing to the allocated IP. + 2. Add an entry `example.hamburg.ccc.de` as a CNAME for `public-reverse-proxy` to the same zone. + 3. Commit and reload the zone. +3. On Chaosknoten: + 1. Create a new VM, for example by cloning the Debian template 9023. + Give it the name `example`. + 2. Edit the ethernet interface to be connected to `vmbr0`, VLAN tag `2`. + 3. Configure the IPv6 address in the Cloud-Init section. Leave IPv4 set to DHCP. + 4. Make sure the VM is started at boot (options). + 5. Adjust any other VM parameters as needed. + 6. Boot the VM. +4. Add the [VM to Netbox](https://netbox.hamburg.ccc.de/virtualization/virtual-machines/). + - Make sure to enter the VM ID. + - Add an Ethernet interface to the VM; we typically use `eth0` as a name. + - Add IP for that interface, then choose "Assign IP" and search for the IP you've created. Make it the primary IP of that interface. ## Ansible Basics As the first step, we need to make the host known to Ansible. 1. In `.sops.yaml`, add an entry for the host. Follow the other entries there. - 1. `keys.hosts.chaosknoten.age` needs an age public key (the private key is needed in the host-specific YAML) + 1. `keys.hosts.chaosknoten.age` needs an age public key (must be generated; the private key gets added later in the host-specific YAML) 2. `creation_rules` needs an entry for the host, referencing the age key. 2. In `inventories/chaosknoten/hosts.yaml`: 1. Configure basic connection info: - ``` + ```yaml example: ansible_host: example.hosts.hamburg.ccc.de ansible_user: chaos ansible_ssh_common_args: -J ssh://chaos@router.hamburg.ccc.de ``` You typically will want to use router as a jump host so that you can run Ansible on an IPv4 only connection. - 2. Add the host to the desired roles. As a minimum, you'll want `base_config_hosts` and `infrastructure_authorized_keys_hosts`. For a typical web service based on Docker Compose, you'll want `docker_compose_hosts`, `nginx_hosts`, and `certbot_hosts`. + 2. Add the host to the desired roles. + 1. As a minimum, you'll want the following roles: + - `base_config_hosts` + - `infrastructure_authorized_keys_hosts` + 2. For a typical web service based on Docker Compose, you'll also want: + - `docker_compose_hosts` + - `nginx_hosts` + - `certbot_hosts`. 3. In the directorry `inventories/chaosknoten/host_var/`: 1. A file `inventories/chaosknoten/host_var/example.yaml` with the host/service specific configuration. 2. A file `inventories/chaosknoten/host_var/example.sops.yaml` with the encrypted secrets for the host/service. Run `sops inventories/chaosknoten/host_var/example.yaml` to edit/create that file. Entries here should generally be prefixed with `secret__` to make it easier to see where that variable is coming from in templates etc. @@ -69,12 +80,20 @@ Before you can run Ansible successfully, you will want to make sure you can conn * `ssh chaos@example.hosts.hamburg.ccc.de` * `ssh -J chaos@router.hamburg.ccc.de chaos@example.hosts.hamburg.ccc.de` -Then run Ansible for `public-reverse-proxy` to add the necessary entries: `ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit public-reverse-proxy`. +Then run Ansible for `public-reverse-proxy` to add the necessary entries: -Finally run Ansible for the new host: `ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit example` +```sh +ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit public-reverse-proxy +``` + +Finally run Ansible for the new host: + +```sh +ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts.yaml --limit example +``` # Commit your changes Do not forget to commit your changes, whether it's a new host or you are making changes to an existing host. -And always `git pull` before you run Ansible so avoid reverting anything! \ No newline at end of file +And always `git pull` before you run Ansible so avoid reverting anything! From c6c02724487ab278aa9904483d66efb8d4872d64 Mon Sep 17 00:00:00 2001 From: June Date: Sun, 25 Jan 2026 21:16:38 +0100 Subject: [PATCH 2/3] docs: add section on conf. monitoring with Gatus (status.hamburg.ccc.de) --- docs/create-new-web-service-vm.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/create-new-web-service-vm.md b/docs/create-new-web-service-vm.md index da8293b..57a1e81 100644 --- a/docs/create-new-web-service-vm.md +++ b/docs/create-new-web-service-vm.md @@ -97,3 +97,16 @@ ansible-playbook playbooks/deploy.yaml --inventory inventories/chaosknoten/hosts Do not forget to commit your changes, whether it's a new host or you are making changes to an existing host. And always `git pull` before you run Ansible so avoid reverting anything! + +# Monitoring + +## Gatus (`status.hamburg.ccc.de`) + +After you configured a new service or website, add it to our status and uptime monitoring. +Take a look at the configuration in `resources/external/status/docker_compose/config` and extend it to cover the newly added service or website. The configuration should probably happen in either `services-chaosknoten.yaml` or `websites.yaml`. Taking the existing configuration as a reference should give guidance on how to configure new checks. Additionally there's also the comprehensive [Gatus Documentation](https://github.com/TwiN/gatus?tab=readme-ov-file#table-of-contents). + +After you've added some checks, the configuration can be deployed using: + +```sh +ansible-playbook playbooks/deploy.yaml --inventory inventories/external --limit status +``` From 8f7990acc0240123d2d488c334ba2904060ece12 Mon Sep 17 00:00:00 2001 From: June Date: Sun, 25 Jan 2026 21:17:28 +0100 Subject: [PATCH 3/3] docs: add ansible_pull_hosts to the desired minimum roles/groups --- docs/create-new-web-service-vm.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/create-new-web-service-vm.md b/docs/create-new-web-service-vm.md index 57a1e81..46ff19f 100644 --- a/docs/create-new-web-service-vm.md +++ b/docs/create-new-web-service-vm.md @@ -42,6 +42,7 @@ As the first step, we need to make the host known to Ansible. 1. As a minimum, you'll want the following roles: - `base_config_hosts` - `infrastructure_authorized_keys_hosts` + - `ansible_pull_hosts` 2. For a typical web service based on Docker Compose, you'll also want: - `docker_compose_hosts` - `nginx_hosts`