https://github.com/homestak-dev/tofu
OpenTofu modules for Proxmox VM provisioning with cloud-init
https://github.com/homestak-dev/tofu
cloud-init homelab infrastructure-as-code opentofu proxmox terraform
Last synced: 4 months ago
JSON representation
OpenTofu modules for Proxmox VM provisioning with cloud-init
- Host: GitHub
- URL: https://github.com/homestak-dev/tofu
- Owner: homestak-dev
- License: apache-2.0
- Created: 2026-01-02T01:10:42.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-03-03T01:10:37.000Z (4 months ago)
- Last Synced: 2026-03-03T05:35:29.617Z (4 months ago)
- Topics: cloud-init, homelab, infrastructure-as-code, opentofu, proxmox, terraform
- Language: HCL
- Size: 8.83 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# tofu
OpenTofu modules for Proxmox VM provisioning with cloud-init.
## Overview
This repo provides two things:
1. **Reusable modules** - `proxmox-vm`, `proxmox-file`, `proxmox-sdn` can be used standalone by anyone doing Proxmox + OpenTofu work
2. **homestak integration** - `envs/generic` is the execution layer for [iac-driver](https://github.com/homestak-dev/iac-driver) workflows
Part of the [homestak-dev](https://github.com/homestak-dev) organization.
## Quick Start
### Option A: Full homestak (recommended)
Use iac-driver for manifest-driven VM provisioning:
```bash
# Install homestak
curl -fsSL https://raw.githubusercontent.com/homestak-dev/bootstrap/master/install.sh | bash
# Deploy and test a VM
cd /usr/local/lib/homestak/iac-driver
./run.sh manifest test -M n1-push -H
```
### Option B: Module reuse (advanced)
Use modules directly in your own OpenTofu configuration:
```hcl
module "vm" {
source = "github.com/homestak-dev/tofu//proxmox-vm"
proxmox_node_name = "pve"
vm_name = "my-vm"
cloud_image_id = "local:iso/debian-12.img"
cloud_init_user_data = file("cloud-init.yaml")
vm_cpu_cores = 2
vm_memory = 4096
vm_disk_size = 20
}
```
### Option C: Direct generic env (debugging only)
Requires manually crafted tfvars.json matching iac-driver schema:
```bash
cd envs/generic
tofu init
tofu plan -var-file=/path/to/tfvars.json
tofu apply -var-file=/path/to/tfvars.json
```
## Project Structure
```
tofu/
├── proxmox-vm/ # Reusable: VM provisioning with cloud-init
├── proxmox-file/ # Reusable: cloud image management
├── proxmox-sdn/ # Reusable: VXLAN SDN networking
└── envs/
└── generic/ # homestak: receives config from iac-driver
```
## Modules
| Module | Purpose |
|--------|---------|
| `proxmox-vm` | Single VM with CPU, memory, disk, network, cloud-init |
| `proxmox-file` | Cloud image management (local or URL source) |
| `proxmox-sdn` | VXLAN zone, vnet, and subnet configuration |
## Prerequisites
- OpenTofu CLI
- Proxmox VE with API access
- SSH key at `~/.ssh/id_rsa`
For full homestak integration:
- [bootstrap](https://github.com/homestak-dev/bootstrap) installed
- [site-config](https://github.com/homestak-dev/site-config) set up and decrypted
## Documentation
See [CLAUDE.md](CLAUDE.md) for detailed architecture, configuration flow, and known issues.
## Third-Party Acknowledgments
| Dependency | Purpose | License |
|------------|---------|---------|
| [bpg/proxmox](https://github.com/bpg/terraform-provider-proxmox) | OpenTofu provider for Proxmox API | MPL-2.0 |
## Related Repos
| Repo | Purpose |
|------|---------|
| [bootstrap](https://github.com/homestak-dev/bootstrap) | Entry point - curl\|bash setup |
| [site-config](https://github.com/homestak-dev/site-config) | Site-specific secrets and configuration |
| [ansible](https://github.com/homestak-dev/ansible) | Proxmox host configuration |
| [iac-driver](https://github.com/homestak-dev/iac-driver) | Orchestration engine |
| [packer](https://github.com/homestak-dev/packer) | Custom Debian cloud images |
## License
Apache 2.0 - see [LICENSE](LICENSE)