terraform/README.md

1337NET Terraform State

This repository contains the Terraform configs for 1337NET. Terraform configurations are declarative, meaning that you define the whats of your result, not the hows. Terraform for Proxmox works by making API calls to Proxmox which authenticates with a Proxmox token. However, some functionality is not API exposed; for these situations, we can allow SSH authentication to the Proxmox node we want to make changes to, and Terraform will run the necessary shell commands to achieve its desired state. I'm probably cutting a lot of details, but that's the gist of it.

Ideally, all infrastructure moving forward should be defined in this repository and deployed using terraform on Reeves. Some infrastructure was provisioned before the transition to Terraform, and it's currently a work in progress to migrate this infrastructure into Terraform configs.

This repository uses the bgp/proxmox provider. Find the documentation here. The 3 resources we currently use are proxmox_virtual_environment_vm, proxmox_download_file, and proxmox_virtual_environment_file.

To run terraform commands, you must define proxmox_api_token and proxmox_endpoint in the node sub-directory. You can do this in a file called secrets.tfvars. For example:

# ./proxmox_node_name/secrets.tfvars
proxmox_api_token="terraform@pve!terraform=..."
proxmox_endpoint="192.168.30.10:8006" # fishburne's IP + Proxmox port

Importing an existing Proxmox resource to Terraform

If a VM already exists in Proxmox that was created through the Web UI and you want to preserve the VM's state while also importing it into Terraform so that it's managed by Terraform moving forward, take the following steps:

1. Define a resource import

Create imports.tf and replace vm_name, node_name and vm_id.

# imports.tf

import {
    to = proxmox_virtual_environment_vm.vm_name
    id = "node_name/vm_id"
}

2. Generate a plan that writes the config for the newly defined Terraform resource

terraform plan -var-file secrets.tfvars -generate-config-out=generated.tf

3. Copy over the relevant settings in generated.tf to main.tf

This one is a bit handwavy, but basically, you want to copy over the settings that need explicit definement. This is probably stuff like vm_id, vm_name, proxmox_node_name, datastore_type, RAM and CPU settings, etc. The other settings likely have defaults that match the VM.

# main.tf

module "vm_name" {
    source "../../modules/proxmox-vm"
    
    vm_id = vm_id
    proxmox_node_name = node_name
    vm_name = "vm_name"
    cores = 1
    memory = 2048
}

4. Change imports.tf to transfer the new resource to our Proxmox template module

# imports.tf

import {
    to = module.vm_name.proxmox_virtual_environment_vm.this
    id = "node_name/vm_id"
}

5. DELETE generated.tf to remove a duplicate reference to resources.

6. Generate an import plan

terraform plan -var-file secrets.tfvars -out import.tfplan

6. Review the generated plan and make sure nothing will be destroyed