ansible-infra/docs/create-new-web-service-vm.md

How to create all necessary entries for new (web service) VM

Let's assume that you want to add a new web service example.hamburg.ccc.de which is going to be hosted on the VM example on chaosknoten. These are the steps that you need to take to create the VM and add it to the Ansible repo.

IP, DNS, VM

1. Allocate a fresh IPv6 in Netbox in the 2a00:14b0:42:102::/64 net. 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. 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.

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)
   2. creation_rules needs an entry for the host, referencing the age key.
2. In inventories/chaosknoten/hosts.yaml:
   1. Configure basic connection info:

      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.
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 there should generally be prefixed with secret__ to make it easier to see where that variable is coming from in templates etc.

Service-specific config

From here, we go into the details of the web service that you want to configure. For a typical web service with Docker Compose, you will likely want to configure the following.

Make inventories/chaosknoten/host_var/example.yaml look like this:

certbot__version_spec: ""
certbot__acme_account_email_address: le-admin@hamburg.ccc.de
certbot__certificate_domains:
  - "example.hamburg.ccc.de"
certbot__new_cert_commands:
  - "systemctl reload nginx.service"

docker_compose__compose_file_content: "{{ lookup('ansible.builtin.template', 'resources/chaosknoten/example/docker_compose/compose.yaml.j2') }}"

nginx__version_spec: ""
nginx__configurations:
  - name: example.hamburg.ccc.de
    content: "{{ lookup('ansible.builtin.file', 'resources/chaosknoten/spaceapiccc/nginx/example.hamburg.ccc.de.conf') }}"

This will create compose.yaml from the template resources/chaosknoten/example/docker_compose/compose.yaml.j2', and the nginx config from resources/chaosknoten/spaceapiccc/nginx/example.hamburg.ccc.de.conf. Of course, depending on your service, you might need additional entries. See the other hosts and the roles for more info.

First Ansible run

Before you can run Ansible successfully, you will want to make sure you can connect to the VM, and that the host key has been added to your known hosts:

• 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.

Finally run Ansible for the new host: 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!