A collection of infrastructure-as-code (IaC) and configuration-as-code (CaC) files for homelab setup.

OpenTofu (an open-source fork of Terraform) is used to provision infrastructure in Proxmox Virtual Environment (VE) through IaC while Vagrant is used for testing Ansible playbooks, which is configuration-as-code used to automate infrastructure configuration.

The homelab can be configured using either OpenTofu/Terraform or Vagrant. OpenTofu/Terraform is used to provision infrastructure under the infra/prod directory while Vagrant is used for provisioning infrastructure under the infra/test directory. After provisioning, Ansbile is then used to run playbooks under the provisioning/playbooks directory.

1. Install IaC tools: OpenTofu (guide) or Terraform (guide), and Vagrant (guide)

2. Install CaC tools: Ansible (guide). There are requirements.txt and .python-version files under the provisioning directory which can be used if installing Ansible using pip

1. Setup a Proxmox VE server (guide) and follow this guide to create user for the Terraform Proxmox VE provider

2. Create a Proxmox VE VM template using this guide. The homelab uses AlmaLinux OS 9 (an open-source Linux distribution binary compatible with RHEL) and ID 90x for the VM templates by default. Create one VM template for each Proxmox VE node. Obtain the cloud-init images for AlmaLinux here. Note that the snippet provided in the guide will be replaced via Ansible later on in this "Getting Started" guide.

3. View the Terraform files and make changes as necessary, e.g., the Proxmox VE API URL for the provider, network and disk settings for the VM, etc. Optionally, create an .auto.tfvars file to store variables

1. Install Vagrant Libvirt using this guide

1. Add a generic password to the macOS keychain:

security add-generic-password -s homelab-playbooks -a ansible-vault -w

2. Replace all vault.yaml files and encrypt them using Ansible Vault

3. View the inventory file hosts-prod.yaml and make changes as necessary

4. View variables under the provisioning/group_vars/ directory and make changes as necessary

Provision infrastructure using OpenTofu (replace tofu with terraform if using Terraform). Example:

cd infra/prod/k8s
tofu init
tofu plan -out=plan0
tofu apply plan0

Bootstrap using the Ansible playbooks. Example:

for ip in 192.168.1.{21..26}; do ssh-keyscan -H $ip >> ~/.ssh/known_hosts; done

cd ../../../provisioning
ansible-playbook playbooks/k8s.yaml --inventory=hosts-prod.yaml

Provision infrastructure using Vagrant (automatically runs the Ansible playbooks). Example:

cd infra/test/k8s
vagrant up

Destroy infrastructure using OpenTofu (replace tofu with terraform if using Terraform). Example:

cd infra/prod/k8s
tofu destroy

Or using Vagrant:

cd infra/test/k8s
vagrant destroy