Bootstrapping a new VM
This procedure describes the step you must follow to rollout a new managed vm. Note that this procedure can only be executed by someone in the BOFH team. We are planning to make this functionality available to all members.
We support two flavours of machines currently:
- Debian 12 (bookworm) with backports enabled
- AlmaLinux 9 with SELinux enabled
All code that is used to deploy these works with both these distros, and it is fairly easy to add additional distributions if the need arises.
Deploying a new VM
Add DNS records
First up, you will need to create DNS records for the new machine. This is done by logging into FreeIPA. Find a free ip, and create a record for the host you want to create. Dont forget to create a PTR record.
TODO: Ensure that zone transfers happen sooner. This sometimes needs to be prodded
Update ansible inventory
Checkout the repository and add a new host under inventories/nurdspace/inventory.yml. Add the host to the following groups:
- all
- vergersweg
- debian or almalinux (depending on the distro)
Optionally you can create your own group. This is used to deploy a system where the service itself is also managed via ansible. This is done for all BOFH systems. Next, commit your changes, and check the CI/CD pipeline to see if the ansible archive is correctly deployed.
Create new virtual machine
Start by creating a clone of either the AlmaLinux or Debian template repository. Be sure to remove the existing .git directory. Next, edit machines.tf and customize it to your needs. See the example below:
module "NAME" {
source = "git::https://git.nurd.space/bofh/opentofu/modules/proxmox"
hostname = "NAME"
distribution = "debian12" # or `almalinux9`
ipv4_address = "10.208.X.Y"
cluster_node = "erratic"
datastore = "hddvg"
vault_password = var.vault_password
}
Each machine will get 2 cores, 2GB ram and 20GB diskspace by default. You can customize this by setting the cores, memory or storage parameters. If you want to use ansible to also manage the service, set the role parameter to the name of the ansible group you want to deploy onto the system.
Deploy the system
Once you are satisfied with the machine configuration, create a new repository for this system under the machines group. Initialize the copy of the repository you cloned from one of the templates, and add the newly created gitlab repository as a remote. Push your code, and a CI/CD pipeline will pick this up and deploy your system.
Actual deployment
Once the pipeline is kicked off, the following steps will be performed:
- OpenTOFU will create a new virtual machine on Proxmox. The machine is configured with a cloud-config tailored to the system
- During the first boot, cloud-init downloads and intalls ansible-puller, and will perform the first run of ansible-puller
- Ansible puller will download and install ansible in a venv on the system, and will pull a tarball with the latest copy of the ansible repository
- After unpacking, ansible-puller will perform the actual configuration of the system
This whole cycle takes approximately 10 to 15 minutes. Once it is completed, you can login to the system using your LDAP credentials. If anything fails, you can login to the system using the debug user to see what went wrong. Ask one of the BOFH members for the password for this account.