CCCHH/ansible-infra
CCCHH/ansible-infra
2
2
Fork 2
Code Issues 7 Pull requests 4 Wiki Activity Actions

docs: improve formatting and wording a bit to make things clearer

Browse source
This commit is contained in:
June 2026-01-25 21:11:07 +01:00
commit 1523b15952
Signed by: june
SSH key fingerprint: SHA256:o9EAq4Y9N9K0pBQeBTqhSDrND5E7oB+60ZNx0U1yPe0
1 changed files with 37 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

53
docs/create-new-web-service-vm.md
View file

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