{"id":38413611,"url":"https://github.com/langburd/terraform-proxmox","last_synced_at":"2026-01-17T04:05:38.867Z","repository":{"id":326587421,"uuid":"1048150241","full_name":"langburd/terraform-proxmox","owner":"langburd","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-30T21:30:51.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-01T00:47:55.201Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/langburd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T02:24:01.000Z","updated_at":"2025-11-30T21:30:55.000Z","dependencies_parsed_at":"2025-12-02T11:02:37.171Z","dependency_job_id":null,"html_url":"https://github.com/langburd/terraform-proxmox","commit_stats":null,"previous_names":["langburd/terraform-proxmox"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/langburd/terraform-proxmox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langburd%2Fterraform-proxmox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langburd%2Fterraform-proxmox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langburd%2Fterraform-proxmox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langburd%2Fterraform-proxmox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/langburd","download_url":"https://codeload.github.com/langburd/terraform-proxmox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langburd%2Fterraform-proxmox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28494256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T04:05:38.777Z","updated_at":"2026-01-17T04:05:38.848Z","avatar_url":"https://github.com/langburd.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proxmox LXC Containers with OpenTofu\n\nThis repository contains an opinionated OpenTofu root configuration and a reusable LXC module that works with both Terraform and OpenTofu. It lets you describe containers once in `containers.yaml`, then create, update, and destroy them in a repeatable way, including optional automation for Docker-in-LXC on Proxmox versions affected by the AppArmor issue (CVE-2025-52881).\n\nThe root configuration uses `.tofu` files and is intended to be executed with the `tofu` CLI only (not the `terraform` CLI). The `modules/lxc` submodule is written in standard HCL (`.tf`) and can be consumed from either Terraform or OpenTofu.\n\n## Overview\n\n- Root configuration (`*.tofu` files) that:\n  - Parses `containers.yaml` into locals.\n  - Invokes the `modules/lxc` Terraform module for each container.\n  - Optionally downloads LXC OS templates and creates resource pools.\n  - Manages Proxmox snippets and host-side scripts for Alpine Docker containers and the Docker AppArmor workaround.\n- Reusable `modules/lxc` module that wraps `proxmox_virtual_environment_container` with strong validation and a YAML-friendly input structure.\n\nFor detailed variable, provider, and output documentation, refer to `SPECS.md` (generated Terraform docs) and `modules/lxc/README.md`.\n\n## Main features\n\n- YAML-driven configuration via a single `containers.yaml` file.\n- Support for most `proxmox_virtual_environment_container` arguments, including:\n  - CPU, memory, disks, mount points.\n  - Initialization (hostname, networking, DNS, user account).\n  - Network interfaces and additional interfaces.\n  - Features, startup options, cloning, and timeouts.\n- Separation of concerns:\n  - Root module for orchestration, hooks, and infrastructure glue.\n  - `modules/lxc` for the low-level container resource.\n- Optional Proxmox automation:\n  - Downloading standard LXC templates (`lxc-templates.tofu`).\n  - Managing Proxmox pools (`pools.tofu`).\n- Docker-on-LXC support for Proxmox \u003c 9.1:\n  - Host-side AppArmor fix applied via `null_resource.docker_apparmor_fix` and `scripts/docker-apparmor-fix.sh`.\n  - Alpine Docker LXC hook script (`scripts/alpine-docker-setup.sh`) uploaded as a Proxmox snippet and referenced from containers.\n\n## Project structure\n\n```text\nterraform-proxmox/\n├── containers.yaml          # Declarative container definitions (single source of truth)\n├── containers.tofu          # Root logic: parses YAML, calls modules/lxc, applies hooks\n├── lxc-templates.tofu       # Optional download of LXC OS templates\n├── pools.tofu               # Optional Proxmox resource pools\n├── providers.tofu           # Terraform/OpenTofu and provider configuration\n├── variables.tofu           # Root variables (endpoint, credentials, app_password, etc.)\n├── outputs.tofu             # Root outputs\n├── modules/\n│   └── lxc/\n│       ├── main.tf          # LXC container resource implementation\n│       ├── variables.tf     # Module inputs and validation\n│       ├── outputs.tf       # Module outputs\n│       └── README.md        # Module-level documentation\n├── scripts/\n│   ├── alpine-docker-setup.sh   # LXC hookscript to provision Alpine Docker containers\n│   └── docker-apparmor-fix.sh   # Host-side AppArmor workaround for Docker in LXC\n├── hooks/\n│   └── tfsort.sh            # Helper script to run tfsort on .tofu/.tf files\n├── SPECS.md                 # Generated Terraform docs (providers, inputs, outputs, etc.)\n└── README.md                # This file\n```\n\n## Prerequisites\n\n- A Proxmox VE host or cluster reachable from where you run OpenTofu.\n- OpenTofu CLI (`tofu`) installed; the root configuration uses `.tofu` files and is not intended to be run with the `terraform` CLI.\n- Access credentials for the Proxmox API:\n  - API endpoint (for example `https://your-proxmox-host:8006/api2/json`).\n  - User with permission to manage LXC containers and snippets (for example `root@pam`).\n- SSH access from the machine running OpenTofu to the Proxmox host, if you enable the Docker AppArmor workaround (`docker_apparmor_fix`), because it is implemented with an SSH-based `null_resource`.\n\nExact provider versions, inputs, and outputs are documented in `SPECS.md`.\n\n## Setup\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/\u003cyour-org\u003e/terraform-proxmox.git\n   cd terraform-proxmox\n   ```\n\n2. **Configure Proxmox credentials**\n\n   Either export environment variables so OpenTofu can pick up the variables used in `providers.tofu`:\n\n   ```bash\n   export TF_VAR_endpoint=\"https://your-proxmox-host:8006/api2/json\"\n   export TF_VAR_username=\"root@pam\"\n   export TF_VAR_password=\"your-proxmox-host-root-password\"\n   export TF_VAR_app_password=\"container-root-password\"\n   ```\n\n   or set the same variables in `terraform.tfvars`.\n\n3. **Review providers and inputs**\n\n   - Check `providers.tofu` and `variables.tofu` for how providers and root variables are defined.\n   - See `SPECS.md` for the generated list of providers, inputs, and outputs when it has been refreshed with `terraform-docs` (or similar).\n\n## Basic usage\n\n1. **Describe containers in `containers.yaml`**\n\n   Minimal example:\n\n   ```yaml\n   containers:\n     web-server:\n       node_name: \"pve-node1\"\n       description: \"Web server container\"\n       tags: [\"web\", \"production\"]\n       operating_system:\n         template_file_id: \"local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst\"\n         type: \"debian\"\n       disk:\n         datastore_id: \"local-lvm\"\n         size: 8\n       initialization:\n         hostname: \"web-server\"\n         ip_config:\n           ipv4:\n             address: \"192.168.1.10/24\"\n             gateway: \"192.168.1.1\"\n   ```\n\n   See `modules/lxc/README.md` for the full set of supported fields and structures.\n\n2. **Initialize and plan**\n\n   ```bash\n   tofu init\n   tofu plan\n   ```\n\n3. **Apply**\n\n   ```bash\n   tofu apply\n   ```\n\n   This will:\n\n   - Parse `containers.yaml`.\n   - Create or update LXC containers via the `modules/lxc` module.\n   - Upload the Alpine Docker hook script as a snippet.\n   - Apply the Docker AppArmor workaround for any containers that have `docker_apparmor_fix` enabled in `containers.yaml`.\n\n## Docker and hookscript integration (optional)\n\nIf you run Docker inside LXC containers on Proxmox versions affected by the AppArmor issue:\n\n- Mark affected containers in `containers.yaml` with a `docker_apparmor_fix` flag.\n- Configure their networking and `features` to allow nesting, as described in `modules/lxc/README.md`.\n- Optionally configure a hook script (for example the Alpine Docker setup script) by setting `hook_script_file_id` in the container definition so it points at the snippet created by `proxmox_virtual_environment_file.alpine_docker_setup`.\n\nThe root configuration will:\n\n- Upload `scripts/alpine-docker-setup.sh` as a Proxmox snippet.\n- Run `scripts/docker-apparmor-fix.sh` on the Proxmox host via `null_resource.docker_apparmor_fix` before the first start of marked containers.\n\n## Further documentation\n\n- Module reference and configuration details (Terraform/OpenTofu module): `modules/lxc/README.md`.\n- Generated provider/module documentation (providers, modules, inputs, outputs): `SPECS.md`.\n- Script behaviour and advanced Docker/LXC handling: see comments inside `scripts/alpine-docker-setup.sh` and `scripts/docker-apparmor-fix.sh`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangburd%2Fterraform-proxmox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flangburd%2Fterraform-proxmox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangburd%2Fterraform-proxmox/lists"}