Compare commits

..
Author SHA1 Message Date
51f5b2cbbc fix multiple typos
Some checks failed
/ Ansible Lint (push) Successful in 2m22s
/ Ansible Lint (pull_request) Successful in 2m22s
/ build (pull_request) Failing after 2m39s
/ cleanup-staging (pull_request) Failing after 2m17s
2026-05-27 20:43:47 +02:00
c6e3f59fc2 apply patch "0001-fixup-some-formulations.patch" 2026-05-27 20:43:47 +02:00
6206483d2c clarify the usage of the document scope and the differences between concept, configuration and guide 2026-05-27 20:43:47 +02:00
050632947c add documentation-structure 2026-05-27 20:43:47 +02:00
ed6245fa8e fix setup instructions to use uv run 2026-05-27 20:43:47 +02:00
7832978ff7
update ccchh.net dns zone after club proxmox migration
Some checks failed
/ Ansible Lint (push) Successful in 2m19s
/ build (push) Failing after 2m39s
2026-05-24 11:55:37 +02:00
dd48a9d519
bring guide about new chaosknoten VMs into doc structure
Some checks failed
/ Ansible Lint (push) Successful in 2m36s
/ build (push) Failing after 2m37s
2026-05-24 00:27:23 +02:00
0842a51ae0 Merge branch 'main' of git.hamburg.ccc.de:CCCHH/ansible-infra
Some checks failed
/ Ansible Lint (push) Successful in 2m21s
/ build (push) Failing after 2m38s
2026-05-24 00:12:52 +02:00
603d3fb6f4 Update machine SMTP mail sending config 2026-05-24 00:12:50 +02:00
4574dbf4ba
secrets(role): introduce secrets role for storing secrets
Some checks failed
/ Ansible Lint (push) Successful in 2m18s
/ build (push) Failing after 2m40s
Allows storage of secrets to then be referenced in other places.
The motivation was storing WireGuard secrets for systemd-networkd.
2026-05-23 22:40:17 +02:00
12 changed files with 188 additions and 88 deletions

View file

@ -0,0 +1,111 @@
---
title: Create a new VM on Chaosknoten
---
!!! success "Goal"
Create a new VM on our Chaosknoten Server with DNS Name, Firewalling and network config.
## 1. Reserve an IP Address
Decide on what kind of network configuration the VM needs.
In this guide we assume a public v6 and a non-public v4 in the v4-NAT network.
If you have special requirements, refer to TODO for more information on the different kinds of networks available on Chaosknoten.
1. Allocate a fresh [v6 in NetBox in the v4-NAT v6-network](https://netbox.hamburg.ccc.de/ipam/prefixes/47/ip-addresses/).
- The _hostname_ should be the full FQDN, like: `myservice.hosts.hamburg.ccc.de`
## 2. Configure DNS
2. Add a new `AAAA` record pointing to the chosen v6 to the [`hamburg.ccc.de` zone](https://git.hamburg.ccc.de/CCCHH/ansible-infra/src/branch/main/resources/chaosknoten/auth-dns/zones/hamburg.ccc.de.zone).
It should look something like this:
```
myservice.hosts IN AAAA 2a00:14b0:42:102::ff
```
3. Run the Ansible playbook for the `auth-dns` host to publish the new DNS entry:
```
ansible-playbook -i inventories/chaosknoten playbooks/deploy.yaml -l auth-dns -t knot
```
## 3. Create A VM in Proxmox
Now that we have a v6, let's create a new VM on Chaosknoten.
1. Clone the `chaos-debian-XX-tmpl-YYYY-MM-DD` template with ID `9023`.
- The _Name_ should be the hostname used earlier, e.g. `myservice`.
- The _Mode_ should be set to _Full Clone_ and the _Target Storage_ to _nvme0_.
- All other settings should be left as is.
2. Once cloned, edit the VM settings as follows:
- The network interface for the VM should already be configured to use bridge _vmbr0_ with VLAN tag _2_, which is the correct configuration for the v4-NAT network used in this example.
For other networks, other bridges or VLANs should be used.
- If there isn't a good reason to not do so, enable the Proxmox firewall for the VM. Firewall security groups exist for various common use cases to make the firewall configuration fast and easy.
- In the _Cloud-init_ section, set the chosen static v6 with its gateway. As we're using the v4-NAT network in this example, the gateway would be `2a00:14b0:42:102::1`.
For other networks, different network configuration must be set.
- In the _Options_ section, set _Start at Boot_ to _Yes_.
- Optionally configure other VM parameters.
Especially the _Memory_, _Processors_ and _Hard Disk_ options might be of interest.
3. Next start up the VM.
- Once it has an IP, you should be able to SSH into it using the hostname used in the DNS entry earlier (e.g. `myservice.hosts.hamburg.ccc.de`):
```
ssh chaos@myservice.hosts.hamburg.ccc.de
```
Or if no v6 connectivity is available:
```
ssh -J chaos@router.hamburg.ccc.de chaos@myservice.hosts.hamburg.ccc.de
```
## 4. Enter VM into NetBox
4. Finally add the VM to NetBox
1. First [add the VM itself](https://netbox.hamburg.ccc.de/virtualization/virtual-machines/).
- The _Name_ should be the hostname of the VM, so e.g. `myservice`.
- _Site_ and _Cluster_ should be set. For Chaosknoten that would be _IRZ42_ and _chaosknoten_.
- The _Proxmox VM ID_ should be set to the ID of the VM in Proxmox.
- All other options should be left as is.
2. Then add the interface of the VM to the newly created VM in NetBox by adding a component.
- The _Name_ should be the name of the interface of the VM. Most likely _net0_.
- The _Primary MAC Address_ should be set to the MAC address generated by Proxmox, which can be found in the _Network Device_ configuration in Proxmox.
- _802.1Q Switching_ should be set appropriately. As we're using the v4-NAT network in this example, the _802.1Q Mode_ would be _Access_ with the _VLAN group_ being _IRZ42 Intern_ and the _Untagged VLAN_ being _v4-NAT_.
- All other options should be left as is.
4. Finally assign the IP address created earlier in NetBox to the just created interface by going into the _Assignment_ section of the IP address configuration.
- Also check _Make this the primary IP for the device/VM_ while doing so.
## 5. Enroll the VM in ansible
Next up the VM should be added to the Ansible configuration management. While Ansible can and should be used to configure various services and configuration options, this section focuses on the basic setup to be done.
1. [Setup SOPS for the new host](./sops-new-host.md).
2. Add the VM to the inventory (e.g. `inventories/chaosknoten/hosts.yaml`):
1. First add basic connection info. For our host in the v4-NAT network, this would look like this:
```yaml
myservice:
ansible_host: myservice.hosts.hamburg.ccc.de
ansible_user: chaos
ansible_ssh_common_args: -J ssh://chaos@router.hamburg.ccc.de
```
Adding the router as a jump host enables us to run Ansible on a v4-only connection.
2. Add the host to a base set of inventory groups for a base configuration:
- `base_config_hosts`
- `infrastructure_authorized_keys_hosts`
- `ansible_pull_hosts`
3. Run a first Ansible playbook against the new host to apply the basic configuration:
```
ansible-playbook -i inventories/chaosknoten playbooks/deploy.yaml -l myservice
```
Feel free to commit at this point before continuing with further configuration.
## 6. Configure the VM further for your needs
With the basic configuration now done, the VM can be set up further. Here are some helpful pointers:
- Inventory variables for the host can be set in its host vars file, e.g. `inventories/chaosknoten/host_vars/myservice.yaml`.
- Secrets should be stored using SOPS, see: [SOPS: Storing Secrets](./sops-storing-secrets.md)
- Guidance on setting up a web service can be found in the [Web Service](./web-service.md) guide.
Afterward you should also take care of setting up monitoring for the newly configured service, see: [Monitor a new service with Gatus](./monitor-a-new-service-with-gatus.md).
## Closing Up
This section is optional but if there's any way for the reader to verify their goal has been achieved, you should mention it here.

View file

@ -291,3 +291,5 @@ msmtp_hosts:
renovate_hosts:
hosts:
renovate:
secrets_hosts:
hosts:

View file

@ -22,3 +22,5 @@ infrastructure_authorized_keys_hosts:
ansible_pull_hosts:
hosts:
status:
secrets_hosts:
hosts:

View file

@ -1,5 +1,5 @@
metrics__chaos_password: ENC[AES256_GCM,data:seOU504dZ9K21+NK1MBf9isee2L2rueP6Bl0F66R,iv:ZtQ516gzJQSSgvOOAzPF9MuarXqHSLXy37/9z85KoQ8=,tag:dIal6OxPLli+7DbzhjNFsA==,type:str]
msmtp__smtp_password: ENC[AES256_GCM,data:NlA0aN2SeP4Tl3G1Qg0v/SAicY8p6ZMdQPihGfFTohAmajNvteFJ19ELPezwTz7hia0oU7lwo3DfKuu92WMIKA==,iv:s44piFZZrF6ZYmkGqsBFjTUNiHc4IhBXJATRPETsAI8=,tag:Sj0Q/Y4hT4Hs1JxVOO/8xQ==,type:str]
msmtp__smtp_password: ENC[AES256_GCM,data:FAih8FghRYDx3QGFCjKoJ8Zq0TkeCIx4n1jTx4/sASgECqvucg==,iv:8NDn3wj/bXsbHbuce3ycJTBVWde6XAVxv4NuMUkMbIM=,tag:jeE2b0i/8JPtguLYQvdV1w==,type:str]
sops:
age:
- recipient: age1j0876shgsn7f2thxh9kx9x5uwnh45z6sy2jlk2qz5jhgedm26g5srn9kax
@ -38,8 +38,8 @@ sops:
cnlBL29XQVlsL1ZCenBIYTQ3S3JxQjQKq09vbn1XOC1jIXDpv+ThFMk9k7SyYknr
MBJRBp/0PrKBo/Xk+RCSWSLjgali5Cc8KTjDTJyBG8rFzzvLIazBRg==
-----END AGE ENCRYPTED FILE-----
lastmodified: "2026-03-30T19:28:25Z"
mac: ENC[AES256_GCM,data:IGai2CmOI46XHekSSpLgQxEGw9zIf7Z10K8eQyi0rJGha5ZOjz9jP1VIhC9m6LjRxOKJuEPV2NvBACC5tBUCGwW1Ym31spcROjjtCzyqRF8E7R02oNMIQ32Byb9ij56/Trl5UOBOML+WOdeaq8r74kEfIyZBCx/tfGENuTlBqd4=,iv:Gjzb/IW6WcRL3c4ShOH46cVed4duTs1BFygYnGd4d4Y=,tag:DZAH6tA92mFP5Yo9b4kmkg==,type:str]
lastmodified: "2026-05-23T22:10:20Z"
mac: ENC[AES256_GCM,data:JbnKG1qyAkvFDXr2iHu+gk7nRjedmm+dEK8vBFW5YzndWE4QKoYWeaqRHBk7wdWO9kpZgU2rFiu4Be+ikotoMS8jKAcd5wWSrWtSreaZxxiD2TWMWX8HwPtETnYe0rjrEZ3kPcUj4QPyNTphfbH3ARLjthedRXNF70NDc+DIpAY=,iv:4LN3oslWUWqoY3rQNVDSmlJn1o0c8JQELzsWd5btn7Y=,tag:c8X1q9XMMUkXed93j9C6ww==,type:str]
pgp:
- created_at: "2026-05-20T02:08:49Z"
enc: |-
@ -212,4 +212,4 @@ sops:
-----END PGP MESSAGE-----
fp: 41FFAF3D519CF5C039FBD8414BCC213729AF0E49
unencrypted_suffix: _unencrypted
version: 3.12.1
version: 3.12.2

View file

@ -12,8 +12,8 @@ ansible_pull__timer_randomized_delay_sec: 30min
msmtp__smtp_host: cow.hamburg.ccc.de
msmtp__smtp_port: 465
msmtp__smtp_tls_method: smtps
msmtp__smtp_user: any@hosts.z9.ccchh.net
msmtp__smtp_from: "{{ inventory_hostname }}@hosts.z9.ccchh.net"
msmtp__smtp_user: machine@ccchh.net
msmtp__smtp_from: "{{ inventory_hostname }}@cchh.net"
alloy_config_default: |
prometheus.remote_write "default" {

View file

@ -57,3 +57,5 @@ ansible_pull_hosts:
light:
waybackproxy:
yate:
secrets_hosts:
hosts:

View file

@ -6,6 +6,13 @@
tags:
- base_config
- name: Ensure secrets deployment on secrets_hosts
hosts: secrets_hosts
roles:
- secrets
tags:
- secrets
- name: Ensure systemd-networkd config deployment on systemd_networkd_hosts
hosts: systemd_networkd_hosts
roles:

View file

@ -1,73 +1,64 @@
$ORIGIN .
$TTL 900 ; 15 minutes
ccchh.net IN SOA auth-dns.hamburg.ccc.de. noc.hamburg.ccc.de. (
2026042801 ; serial
86400 ; refresh (1 day)
7200 ; retry (2 hours)
3600000 ; expire (5 weeks 6 days 16 hours)
7200 ; minimum (2 hours)
)
NS auth-dns.hamburg.ccc.de.
NS ns.vie.ccc.de.
$TTL 60 ; 1 minutes
@ SOA auth-dns.hamburg.ccc.de. noc.hamburg.ccc.de. (
1 ; serial (overwritten by knot automatically)
86400 ; refresh (1 day)
7200 ; retry (2 hours)
3600000 ; expire (5 weeks 6 days 16 hours)
60 ; minimum/negative ttl (1 minute)
)
$ORIGIN ccchh.net.
aes A 212.12.48.125
club-assistant AAAA 2a07:c481:1:d0::a
;_acme-challenge.club-assistant CNAME d50ad73a-f82d-4244-87f0-6f5195b37d21.auth.acmedns.hamburg.ccc.de
club-assistant.z9 AAAA 2a07:c481:1:d0::a
;_acme-challenge.club-assistant.z9 CNAME 0efa74d1-7dcd-478b-bdc5-5b76d0f07642.auth.acmedns.hamburg.ccc.de
esphome AAAA 2a07:c481:1:d0::66
esphome.z9 AAAA 2a07:c481:1:d0::66
zigbee2mqtt A 185.161.129.132
light AAAA 2a07:c481:1:d0::16
_acme-challenge.light CNAME e59f55ee-9013-469d-a146-a159721b6fea.auth.acmedns.hamburg.ccc.de.
light.z9 AAAA 2a07:c481:1:d0::16
_acme-challenge.light.z9 CNAME 3bc9e7ce-03dd-4533-a059-b5d38407eaa5.auth.acmedns.hamburg.ccc.de.
light-werkstatt AAAA 2a07:c481:1:d0::16
_acme-challenge.light-werkstatt CNAME f408acc0-d9f5-4525-bb01-28938e3bb7d0.auth.acmedns.hamburg.ccc.de.
mailserver-endpoint A 82.165.121.46
ns1 A 185.161.129.133
send-only-mail MX 10 send-only-mailserver
TXT "v=spf1 mx -all"
send-only-mailserver A 82.165.121.46
send-only-mailserver-access A 185.161.129.132
thinkcccore0 AAAA 2a07:c481:1:f2::3
thinkcccore0.z9 AAAA 2a07:c481:1:f2::3
thinkcccore1 AAAA 2a07:c481:1:f2::4
thinkcccore1.z9 AAAA 2a07:c481:1:f2::4
opnsense AAAA 2a07:c481:1:f2::1
opnsense.z9 AAAA 2a07:c481:1:f2::1
pbs AAAA 2a07:c481:1:f2::4
thinkcccore2 AAAA 2a07:c481:1:f2::5
thinkcccore2.z9 AAAA 2a07:c481:1:f2::5
thinkcccore3 AAAA 2a07:c481:1:f2::6
thinkcccore3.z9 AAAA 2a07:c481:1:f2::6
miniscccore0 AAAA 2a07:c481:1:f2::9
miniscccore0.z9 AAAA 2a07:c481:1:f2::9
uptime-kuma A 185.161.129.132
status AAAA 2a07:c481:1:ce::a
status.z9 AAAA 2a07:c481:1:ce::a
wiki A 212.12.48.125
hmdooris-ccu A 10.31.208.202
buba A 10.31.211.137
buba.z9 A 10.31.211.137
dooris AAAA 2a07:c481:1:d0::1c
_acme-challenge.dooris CNAME 37caae1f-b77f-4eb1-aa71-dc3f7ed24360.auth.acmedns.hamburg.ccc.de.
waybackproxy A 10.31.208.99
yate A 10.31.208.12
staubiv2 A 10.31.210.233
staubiv2.z9 A 10.31.210.233
; Mail: hosts.z9.ccchh.net
hosts.z9 MX 10 cow.hamburg.ccc.de
TXT "v=spf1 mx -all"
dkim._domainkey.hosts.z9 TXT ("v=DKIM1;k=rsa;t=s;s=email;"
"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvsdypQ/tlrzto5KVP"
"5o7tEblXK/hOVRFB683uODzo26XTFMSRGjumMuo/tej59GMePdUu0uIsdq8hfj8"
"ot0R2OQNazdyp4NW4TUWfFGJ4S2f6LR3lE3I5Lw7fHiYHz0GnCGTqZIItkHK+xQ"
"i5Fdhwd1YbFJtO0XiZ0jY5w6pvny6pEH8WaKX85rEmz2zqCtpiYPRPmoK/Tn+rV"
"2e8fVioMRm9W8E4PU42WLds66qOkFR0KjKIavE6y7JahESEoVGcVnSPdtMOX0Ln"
"KbSMQNrTvNbBoPdLYvNaXOw7TmVPKjDV+FRCIIdK+m0fL82/vm5jPBvDr5+WlM1"
"xV/P/KlSnQIDAQAB")
$ORIGIN send-only-mail.ccchh.net.
_dmarc TXT "v=DMARC1;p=quarantine;"
key._domainkey TXT "v=DKIM1;k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDqduM4+SQ+IQ2uAxbjFkd+0hAjohTgT3nM76jyrWGHJ8TizNU2PGkta0NjCq+m9VLBZUjIJphW2vrnlJsnN0JkGAdoLBL3Qs0kShT6V+xsxslZG2KHApihnJUp34tPSMES+aTnD+jEPGyxFLeoiK+3gywNhCGalHSQ+G88Z2n59wIDAQAB"
@ NS auth-dns.hamburg.ccc.de.
@ NS ns.vie.ccc.de.
;
; Network-Infrastructure
;
rt-wan A 185.161.129.134
AAAA 2a07:c481::1:2
sw-rack-1 A 10.89.213.2
AAAA 2a07:c481:1:36::2
sw-rack-2-poe A 10.89.213.3
AAAA 2a07:c481:1:36::3
sw-main-1 A 10.89.213.4
AAAA 2a07:c481:1:36::4
sw-main-2 A 10.89.213.5
AAAA 2a07:c481:1:36::5
sw-shop-1 A 10.89.213.6
AAAA 2a07:c481:1:36::6
sw-shop-2-poe A 10.89.213.7
AAAA 2a07:c481:1:36::7
sw-shop-3-poe A 10.89.213.8
AAAA 2a07:c481:1:36::8
pve01 A 10.89.213.11
AAAA 2a07:c481:1:36::11
pve02 A 10.89.213.12
AAAA 2a07:c481:1:36::12
pve03 A 10.89.213.13
AAAA 2a07:c481:1:36::13
pve04 A 10.89.213.14
AAAA 2a07:c481:1:36::14
pbs A 10.89.213.15
AAAA 2a07:c481:1:36::15
unifi A 10.89.213.21
;
; Club-Services
;
xr18 A 172.31.200.21
;club-assistant AAAA 2a07:c481:1:d0::a
;;_acme-challenge.club-assistant CNAME d50ad73a-f82d-4244-87f0-6f5195b37d21.auth.acmedns.hamburg.ccc.de
;esphome AAAA 2a07:c481:1:d0::66
;zigbee2mqtt A 185.161.129.132
;light AAAA 2a07:c481:1:d0::16
;_acme-challenge.light CNAME e59f55ee-9013-469d-a146-a159721b6fea.auth.acmedns.hamburg.ccc.de.
;light-werkstatt AAAA 2a07:c481:1:d0::16
;_acme-challenge.light-werkstatt CNAME f408acc0-d9f5-4525-bb01-28938e3bb7d0.auth.acmedns.hamburg.ccc.de.
;hmdooris-ccu A 10.31.208.202
;buba A 10.31.211.137
;dooris AAAA 2a07:c481:1:d0::1c
;_acme-challenge.dooris CNAME 37caae1f-b77f-4eb1-aa71-dc3f7ed24360.auth.acmedns.hamburg.ccc.de.
;yate A 10.31.208.12
;staubiv2 A 10.31.210.233

24
roles/secrets/README.md Normal file
View file

@ -0,0 +1,24 @@
# Role `secrets`
Allows storing the given secret contents in the configured files.
## Supported Distributions
Should work on Debian-based distributions.
## Required Arguments
None.
## Optional Arguments
- `secrets__secrets`: List of secrets.
Defaults to the empty list (`[ ]`).
- `secrets__secrets.*.name`: (File)name for the secret (in the `/etc/ansible_secrets` directory).
- `secrets__secrets.*.content`: The secret content to store.
- `secrets__secrets.*.owner`: The owner of the secret file.
Defaults to `root`.
- `secrets__secrets.*.group`: The group of the secret file.
Defaults to `root`.
- `secrets__secrets.*.mode`: The mode of the secret file.
Defaults to `0640`.

View file

@ -0,0 +1 @@
secrets__secrets: [ ]

View file

@ -0,0 +1,6 @@
argument_specs:
main:
options:
secrets__secrets:
type: list
required: false

View file

@ -0,0 +1,53 @@
- name: validate secret configs
ansible.builtin.validate_argument_spec:
argument_spec: "{{ required_data }}"
provided_arguments:
config: "{{ item }}"
loop: "{{ secrets__secrets }}"
loop_control:
label: "{{ item.name }}"
vars:
required_data:
config:
type: dict
required: true
options:
name:
type: str
required: true
content:
type: str
required: true
owner:
type: str
required: false
default: root
group:
type: str
required: false
default: root
mode:
type: str
required: false
default: "0640"
- name: ensure secrets directory exists
ansible.builtin.file:
path: "/etc/ansible_secrets"
state: directory
owner: root
group: root
mode: "0750"
become: true
- name: ensure secrets are present
ansible.builtin.copy:
content: "{{ item.content }}"
dest: "/etc/ansible_secrets/{{ item.name }}"
mode: "{{ item.mode | default('0640') }}"
owner: "{{ item.owner | default('root') }}"
group: "{{ item.group | default('root') }}"
become: true
loop: "{{ secrets__secrets }}"
loop_control:
label: "{{ item.name }}"