> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxmox provisioning

> OpenTofu/Terragrunt provisioning for Proxmox VMs and LXC containers. The first tier of the homelab stack.

export const RepoFit = ({children}) => <Tip>{children}</Tip>;

export const RepoMeta = ({language, status, lastActive, repoUrl}) => <Info>
    Language: <b>{language}</b>  ·  Status: <b>{status}</b>  ·  Last active: <b>{lastActive}</b>  ·  <a href={repoUrl}>Source on GitHub</a>
  </Info>;

> Provision VMs and LXCs from a single `terragrunt apply`. The first thing that runs.

<RepoMeta language="HCL" status="active" lastActive="this week" repoUrl="https://github.com/JacobPEvans/terraform-proxmox" />

`tofu-proxmox` defines every VM and LXC in the homelab as OpenTofu resources. Terragrunt provides DRY config across environments. The Proxmox provider talks to the cluster API; nothing here touches a host directly.

## What it does

* Reads its desired-state from the [`deployment.json` contract](/infrastructure/deployment-state-contract) — one versioned S3 object, fetched fail-loud, single-writer via the state lock
* Defines compute, network, and storage for every homelab guest
* Wraps the [`bpg/proxmox`](https://registry.terraform.io/providers/bpg/proxmox/latest) provider
* Places guests across cluster nodes via a per-resource `node_name` (defaults to the primary node)
* Declares per-node ZFS storage (`node_storage`) that Ansible provisions — OpenTofu references the datastore by id and never creates the pool itself (`zpool create` is an OS-level operation)
* Uses Terragrunt to share variables across `prod`, `staging`, and one-off environments
* Outputs a list of provisioned hosts that Ansible inventories consume directly

## How it fits

|          | Upstream                             | Downstream                                                                                                                       |
| -------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Trigger  | `terragrunt apply` from the operator | Outputs an Ansible-ready inventory                                                                                               |
| Talks to | Proxmox cluster API (read/write)     | [`ansible-proxmox`](/infrastructure/repos/ansible-proxmox), [`ansible-proxmox-apps`](/infrastructure/repos/ansible-proxmox-apps) |

<RepoFit>
  Provisioning only. Anything that runs *inside* a host belongs in `ansible-proxmox` or `ansible-proxmox-apps`.
</RepoFit>

## Getting started

<Steps>
  <Step title="Clone and enter the dev shell">
    `git clone https://github.com/JacobPEvans/terraform-proxmox && cd terraform-proxmox && nix develop`
  </Step>

  <Step title="Provide Proxmox API credentials">
    Doppler resolves `PROXMOX_VE_USERNAME`, `PROXMOX_VE_PASSWORD`, and `PROXMOX_VE_ENDPOINT` at run time. The `README.md` covers the exact var names.
  </Step>

  <Step title="Apply">
    `terragrunt run-all apply` from the env folder. Review the plan; nothing destructive runs without confirmation.
  </Step>

  <Step title="Hand off to Ansible">
    Outputs are written to the file Ansible reads as its inventory. Run `ansible-proxmox` next.
  </Step>
</Steps>

## Related repos

<CardGroup cols={2}>
  <Card title="ansible-proxmox" icon="screwdriver-wrench" href="/infrastructure/repos/ansible-proxmox">
    Configures the host once OpenTofu has provisioned it.
  </Card>

  <Card title="ansible-proxmox-apps" icon="boxes-stacked" href="/infrastructure/repos/ansible-proxmox-apps">
    Deploys HAProxy, Cribl Edge, Cribl Stream on top.
  </Card>

  <Card title="tf-splunk-aws" icon="chart-line" href="/observability/repos/tf-splunk-aws">
    The AWS-side equivalent for Splunk's DR footprint.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/JacobPEvans/terraform-proxmox">
    Modules, examples, full README.
  </Card>
</CardGroup>