{"id":43368858,"url":"https://github.com/jacobpevans/terraform-proxmox","last_synced_at":"2026-05-06T21:01:50.891Z","repository":{"id":295302773,"uuid":"989729188","full_name":"JacobPEvans/terraform-proxmox","owner":"JacobPEvans","description":"Infrastructure-as-Code automating Proxmox VE provisioning with Terraform/Terragrunt. Declarative management of VMs, LXC containers, networking, firewall rules. Includes cloud-init, Packer image building for Splunk, and AWS S3/DynamoDB state management for safe concurrent operations.","archived":false,"fork":false,"pushed_at":"2026-04-17T23:02:13.000Z","size":1021,"stargazers_count":0,"open_issues_count":27,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T01:10:00.779Z","etag":null,"topics":["automation","aws-s3","cloud-init","devops","docker","homelab","hypervisor","iac","infrastructure-as-code","k3s","lxc-containers","packer","proxmox","splunk","state-management","terraform","terragrunt","virtualization"],"latest_commit_sha":null,"homepage":null,"language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JacobPEvans.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-24T17:48:38.000Z","updated_at":"2026-04-17T00:10:27.000Z","dependencies_parsed_at":"2026-02-02T06:00:24.959Z","dependency_job_id":null,"html_url":"https://github.com/JacobPEvans/terraform-proxmox","commit_stats":null,"previous_names":["jacobpevans/terraform-proxmox"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/JacobPEvans/terraform-proxmox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobPEvans%2Fterraform-proxmox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobPEvans%2Fterraform-proxmox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobPEvans%2Fterraform-proxmox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobPEvans%2Fterraform-proxmox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JacobPEvans","download_url":"https://codeload.github.com/JacobPEvans/terraform-proxmox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobPEvans%2Fterraform-proxmox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31987884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"ssl_error","status_checked_at":"2026-04-18T20:23:29.375Z","response_time":103,"last_error":"SSL_read: 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":["automation","aws-s3","cloud-init","devops","docker","homelab","hypervisor","iac","infrastructure-as-code","k3s","lxc-containers","packer","proxmox","splunk","state-management","terraform","terragrunt","virtualization"],"created_at":"2026-02-02T05:09:59.089Z","updated_at":"2026-04-18T23:00:21.624Z","avatar_url":"https://github.com/JacobPEvans.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terraform Proxmox Infrastructure\n\nThis project contains Terraform/Terragrunt configurations for managing Proxmox VE infrastructure with virtual machines\nfor automation, development, logging, and service management.\n\n## 🏗️ Overview\n\nThis repository provides Terraform configurations to provision and manage:\n\n- Virtual machines and containers on Proxmox VE\n- Automation infrastructure to manage all VMs and containers\n- Logging infrastructure and centralized syslog\n- Container orchestration with Kubernetes k3s and Docker\n- Resource pools and networking\n- SSH keys and authentication\n\n## Architecture\n\nThe project uses a modular structure for better maintainability and reusability:\n\n```text\nterraform-proxmox/\n├── main.tf                    # Root module orchestrating all components\n├── variables.tf               # Root-level variable definitions\n├── outputs.tf                 # Root-level outputs\n├── locals.tf                  # Local value definitions\n├── container.tf               # Container resource definitions\n├── deployment.json            # Non-secret deployment config (committed plaintext)\n├── terraform.sops.json       # Encrypted network topology (3 values)\n├── terraform.sops.json.example # SOPS template\n├── terragrunt.hcl            # Terragrunt configuration (generates provider.tf)\n├── packer/                    # Packer templates for VM images\n│   ├── splunk.pkr.hcl        # Splunk Enterprise template build\n│   └── variables.pkr.hcl     # Packer variables (Doppler integration)\n└── modules/\n    ├── proxmox-pool/          # Resource pool management\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    ├── proxmox-vm/            # Virtual machine creation\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    ├── proxmox-container/     # Container management\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    ├── splunk-vm/             # Splunk Enterprise all-in-one VM\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    ├── security/              # Security resources (SSH keys, passwords)\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    ├── firewall/              # Proxmox firewall rules for clusters\n    │   ├── main.tf\n    │   ├── variables.tf\n    │   └── outputs.tf\n    └── storage/               # Storage and cloud-init configs\n        ├── main.tf\n        ├── variables.tf\n        └── outputs.tf\n```\n\n## Features\n\n### Implemented\n\n- **Modular Design**: Separate modules for different resource types\n- **Security**: Static SSH key management via cloud-init\n- **Resource Pools**: Organized resource management\n- **Virtual Machines**: Configurable VM deployments with virtio disk interface\n- **Containers**: LXC container support (configurable)\n- **Storage**: Cloud-init configuration management\n- **Splunk Infrastructure**: Packer-built Splunk Enterprise template with dedicated splunk-vm module\n- **Firewall Management**: Integrated Proxmox firewall module for network isolation and security\n- **Terragrunt Integration**: Backend configuration and state management\n- **Latest Versions**: See `terragrunt.hcl` for current provider version constraints\n\n### Benefits of the Modular Structure\n\n1. **Eliminated Duplication**: All VMs use the same module\n2. **Improved Reusability**: Modules can be used across different environments\n3. **Enhanced Maintainability**: Clear separation of concerns\n4. **Better Security**: Static SSH key management with cloud-init\n5. **Consistent Configuration**: Standardized VM settings with virtio interfaces\n6. **Performance Optimized**: Virtio disk interfaces eliminate Proxmox warnings\n\n## Requirements\n\n### Option A: Using Nix Shell (Recommended)\n\nAll tools are provided via the shared [nix-devenv terraform shell](https://github.com/JacobPEvans/nix-devenv/tree/main/shells/terraform).\nThe repository ships a committed `.envrc` file that auto-activates\nthe shell via direnv when you enter the directory.\n\n**Requirements:**\n\n- [Nix](https://nixos.org/download/) with flakes enabled\n- [direnv](https://direnv.net/docs/installation.html) with [nix-direnv](https://github.com/nix-community/nix-direnv)\n\n```bash\n# Automatic activation (requires direnv + nix-direnv)\ndirenv allow    # one-time per worktree, then automatic on cd\n\n# Manual activation\nnix develop \"github:JacobPEvans/nix-devenv?dir=shells/terraform\"\n```\n\n**Tools provided:**\n\n- `terragrunt`, `opentofu`, `terraform-docs`, `tflint` -- IaC tooling\n- `tfsec`, `trivy` -- security scanning\n- `sops`, `age` -- secrets management\n- `awscli2`, `git`, `python3` -- cloud and development\n- `jq`, `yq` -- utilities\n- `pre-commit` -- git hook management\n\nSee **[nix-devenv shells/terraform](https://github.com/JacobPEvans/nix-devenv/tree/main/shells/terraform)** for the complete dev environment definition.\n\n### Option B: Manual Installation\n\nInstall the following tools manually:\n\n- Terraform \u003e= 1.12.2\n- Terragrunt \u003e= 0.81.10\n- AWS CLI configured\n- Proxmox API token\n- SSH key pair\n- Security scanners (tfsec, trivy)\n- Ansible and molecule (for configuration management)\n\n## Usage\n\n### Essential Commands\n\n```bash\n# Plan changes\nterragrunt plan\n\n# Deploy infrastructure\nterragrunt apply -auto-approve\n\n# Destroy infrastructure\nterragrunt destroy --terragrunt-parallelism=1\n\n# Check state\nterragrunt state list\n\n# View infrastructure\nterragrunt show\n```\n\n### Configuration\n\nConfiguration is split into three layers:\n\n```text\ndeployment.json          (committed, plaintext) — containers, VMs, pools, proxmox_node\nterraform.sops.json      (committed, encrypted) — network_prefix, SSH key paths\nDoppler env vars         (runtime only)         — PROXMOX_VE_*, SPLUNK_*, credentials\n```\n\n1. **Edit non-secret config** directly in `deployment.json`:\n\n   ```bash\n   # deployment.json is committed plaintext — edit and commit normally\n   $EDITOR deployment.json\n   git add deployment.json \u0026\u0026 git commit -m \"chore: update containers\"\n   ```\n\n2. **Set up SOPS** for the 3 encrypted values (network prefix + SSH key paths):\n\n   ```bash\n   cp terraform.sops.json.example terraform.sops.json\n   $EDITOR terraform.sops.json        # fill in real values\n   sops --encrypt --in-place terraform.sops.json\n   git add terraform.sops.json\n   ```\n\n3. **See the complete guide**: [docs/SOPS_SETUP.md](./docs/SOPS_SETUP.md)\n\n   This document explains the full 3-layer architecture, SOPS key setup,\n   Doppler credential management, and derived network values.\n\n## 📁 Repository Structure\n\n| File | Purpose |\n| ---- | ------- |\n| `main.tf` | Core resource definitions and VM orchestration |\n| `variables.tf` | Input variable definitions with validation |\n| `locals.tf` | Local value computations and transformations |\n| `container.tf` | Container resources and configurations |\n| `outputs.tf` | Output value definitions |\n| `terragrunt.hcl` | Remote state management (generates provider.tf) |\n| `deployment.json` | Non-secret deployment config (containers, VMs, pools) |\n| `terraform.sops.json` | Encrypted network topology (3 values) |\n| `terraform.sops.json.example` | SOPS template |\n\n## 🔧 Configuration\n\n### Required Variables\n\n- `proxmox_api_endpoint` - Proxmox API URL\n- `proxmox_api_token` - API authentication token\n- `proxmox_ssh_private_key` - SSH key for Proxmox host access\n\n### State Management\n\n- **Backend**: AWS S3 + DynamoDB\n- **Encryption**: Enabled\n- **Locking**: DynamoDB table for state locking\n\n## Storage Configuration\n\n**Note**: Proxmox datastore creation is typically done manually or via Proxmox API.\nThe bpg/proxmox provider doesn't support datastore creation through Terraform.\nThis follows Proxmox best practices to manage storage at the hypervisor level.\n\nDefault datastores used:\n\n- `local`: For ISO images, snippets, backups\n- `local-zfs`: For VM disks (recommended for better performance)\n- `local-lvm`: Alternative storage option\n\nAdditional datastores should be configured directly in Proxmox VE before running Terraform.\n\n## VM Configuration\n\nAll VMs are configured with:\n\n- Hardware-constrained resource allocation\n- Virtio disk interfaces for optimal performance\n- Debian 13.2.0 (Trixie)\n- Cloud-init integration with static SSH keys\n- SSH key authentication from configured SSH key\n\n**Infrastructure Summary**:\n\n- 1 VM (Splunk Enterprise all-in-one): ID 100\n- 5 LXC Containers: IDs 200, 205, 210-211, 220\n- See [INFRASTRUCTURE_NUMBERING.md](./docs/INFRASTRUCTURE_NUMBERING.md) for complete details\n\n## Testing\n\n### Splunk Protection Tests\n\nVerify Splunk VM protection guarantees (plan safety, output structure, live health):\n\n```bash\n# Plan-level tests (safe, no infrastructure changes):\naws-vault exec tf-proxmox -- doppler run -- ./scripts/test-splunk-protection.sh\n\n# With live VM health checks:\naws-vault exec tf-proxmox -- doppler run -- ./scripts/test-splunk-protection.sh --live\n```\n\n### Terraform Test Suite\n\nRun the `.tftest.hcl` mock test suite directly:\n\n```bash\nterraform test\n# or: tofu test\n```\n\n## 📖 Documentation\n\n### Setup \u0026 Configuration\n\n- **[DEPLOYMENT_GUIDE.md](./docs/DEPLOYMENT_GUIDE.md)** - **START HERE**: Complete deployment walkthrough\n- **[Managing Real Infrastructure Values](./docs/MANAGING_REAL_VALUES.md)** -\n  **CRITICAL**: How to safely maintain real IPs/hostnames separate from committed code\n- **[Nix Shell Setup Guide](./docs/nix-shell-setup.md)** - Comprehensive guide to using Nix shells for development\n- **[OpenHands Integration](./docs/openhands-integration.md)** -\n  Guide for integrating OpenHands AI software engineer with Nix, OrbStack, Terraform, and Kubernetes\n\n### Infrastructure Reference\n\n- **[INFRASTRUCTURE_NUMBERING.md](./docs/INFRASTRUCTURE_NUMBERING.md)** - Complete infrastructure map and numbering scheme\n- **[Splunk Cluster Specification](./docs/splunk-cluster-spec.md)** - Detailed Splunk configuration\n\n### Troubleshooting\n\n- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - Operational guidance and common issues\n- **[TERRAGRUNT_STATE_TROUBLESHOOTING.md](./TERRAGRUNT_STATE_TROUBLESHOOTING.md)** - Historical state management issues (resolved)\n\n## ✅ Current Status\n\n**Infrastructure Ready**: Terraform state synchronization issues completely resolved. All state operations (plan, refresh, apply) work reliably\nwith proper S3 + DynamoDB backend connectivity. Ready for controlled infrastructure deployment and k3s/Docker container setup.\n\n## 🛡️ Security\n\n- Passwords configured per VM via cloud-init user accounts\n- All sensitive outputs are marked as sensitive\n- State files are encrypted in S3\n- Least-privilege access principles applied\n- Virtio interfaces provide secure disk access\n\n## Best Practices Implemented\n\n1. **Resource Tagging**: All resources tagged with environment and purpose\n2. **Module Versioning**: Provider versions pinned for stability\n3. **State Management**: Remote state with S3 backend and DynamoDB locking\n4. **Variable Validation**: Input validation where appropriate\n5. **Lifecycle Management**: Proper resource lifecycle configuration\n6. **Error Handling**: Robust error handling and validation\n\n## 🤝 Contributing\n\n1. Plan changes with `terragrunt plan`\n2. Review infrastructure changes carefully\n3. Test in isolated environments\n4. Follow conventional commit messages\n\n## Future Enhancements\n\n- Add support for additional VM types\n- Implement backup automation\n- Add monitoring and alerting configurations\n- Integrate with configuration management tools\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobpevans%2Fterraform-proxmox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacobpevans%2Fterraform-proxmox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobpevans%2Fterraform-proxmox/lists"}