nwarila-platform/terraform-proxmox-iso-manager-framework
GitHub: nwarila-platform/terraform-proxmox-iso-manager-framework
Stars: 0 | Forks: 0
# terraform-proxmox-iso-manager-framework
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/ci.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/security.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/codeql.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/releases)
[](https://docs.renovatebot.com/)
[](https://conventionalcommits.org)
[](LICENSE)
Terraform child module for one job: manage one Proxmox VE installer ISO from a
Git-tracked pin containing `url`, `sha256`, and `filename`.
The module turns that pin into a SHA-verified Proxmox ISO path such as
`cephFS:iso/Rocky-9.6-x86_64-dvd.iso`, which Packer template repositories render into
`boot_iso` and `additional_iso_files` pkrvars matching the
[`nwarila-platform/proxmox-packer-framework`](https://github.com/nwarila-platform/proxmox-packer-framework)
variable types.
## What this demonstrates
This repository treats a small Terraform child module like a production platform
component:
- exact Terraform and provider pinning
- typed inputs with validation coverage
- mock-based Terraform tests with no live Proxmox dependency
- SHA-verified ISO lifecycle management
- fail-closed unmanaged-file behavior
- explicit threat model and module invariants
- Diataxis documentation structure
- ADR-backed design decisions
- OPA policy tests as part of `make ci`
- CI security scanning
- release evidence artifacts
## Usage
provider "proxmox" {
endpoint = "https://proxmox.example.test:8006/"
# Configure credentials in the root consumer, not in this child module.
}
module "iso" {
source = "git::https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework.git//terraform?ref="
family = "rocky9"
iso_pin = {
url = "https://dl.rockylinux.org/pub/rocky/9.6/isos/x86_64/Rocky-9.6-x86_64-dvd.iso"
sha256 = "8ff2a47e2f3bfe442617fceb7ef289b7b1d2d0502089dbbd505d5368b2b3a90f"
filename = "Rocky-9.6-x86_64-dvd.iso"
}
node = "tcnhq-prxmx01"
storage = "cephFS"
}
output "boot_iso" {
value = {
iso_checksum = "sha256:${module.iso.iso_sha256}"
iso_file = module.iso.iso_path
iso_urls = null
cd_label = null
index = 0
iso_download_pve = false
iso_storage_pool = null
iso_target_extension = null
iso_target_path = null
keep_cdrom_device = false
type = "scsi"
unmount = true
}
}
output "additional_iso_files" {
value = []
}
The outputs above match the `boot_iso` and `additional_iso_files` variable types declared by
[`nwarila-platform/proxmox-packer-framework`](https://github.com/nwarila-platform/proxmox-packer-framework)
and is intended to be rendered into an auto-loaded `*.auto.pkrvars.hcl` file via
`templatefile()` and `local_file`. See
[Use from a Packer template](docs/how-to/use-from-a-packer-template.md) for the rendering
pattern.
Consumers must pin the module to a release tag and import the `//terraform` subdirectory.
The exact Terraform and provider pins live in [`terraform/versions.tf`](terraform/versions.tf).
The module rejects tokenized, malformed, or credential-bearing ISO URLs because Terraform
state and outputs are not safe places for bearer tokens.
## Examples
| Example | Purpose |
| --- | --- |
| [`examples/minimal/`](examples/minimal/) | Smallest valid module call |
| [`examples/packer-consumer/`](examples/packer-consumer/) | Consumer-shaped output for Packer variables |
| [`examples/adoption-recovery/`](examples/adoption-recovery/) | Explicit unmanaged-file adoption path |
## Local Validation
Run the same core gates used by CI:
make ci
The CI target checks Terraform formatting, initialization, validation, tests, TFLint,
generated Terraform docs drift, documentation layout, and OPA policy tests.
## Quality Controls
| Control | Evidence |
| --- | --- |
| Terraform format, init, validate, test, TFLint, docs drift, docs layout, and OPA policy tests | `CI` workflow running `make ci` |
| GitHub Actions static analysis | `CodeQL Analysis` workflow |
| Filesystem, IaC, and secret scanning | `Security Scan` workflow |
| OpenSSF repository posture checks | `Scorecard` workflow |
| Template and org baseline drift | `Template Sync` and `Org ADR Sync` workflows |
| SHA pinning, exact pins, and privileged-workflow safety | `Repo Hygiene` workflow |
| Release PRs, changelog, tags, and evidence | `Release` workflow |
| Dependency update PRs | Renovate |
## Documentation
- [Use from a Packer template repo](docs/how-to/use-from-a-packer-template.md)
- [Develop this module](docs/how-to/develop-this-module.md)
- [Review release evidence](docs/how-to/review-release-evidence.md)
- [Adopt this template](docs/how-to/adopt-this-template.md)
- [Architecture](docs/explanation/architecture.md)
- [Testing strategy](docs/explanation/testing-strategy.md)
- [Threat model](docs/explanation/threat-model.md)
- [Terraform reference](docs/reference/terraform.md)
- [Release gates](docs/reference/release-gates.md)
- [Module invariants](docs/reference/invariants.md)
- [Template mirroring contract](docs/reference/mirroring.md)
- [Decision records](docs/decision-records/README.md)
## Security
The integrity of the upstream ISO source is outside this module's threat model. Consumers
are responsible for sourcing trustworthy SHA-256 values from upstream distribution
channels. See the inherited [organization security policy](https://github.com/nwarila-platform/.github/blob/main/SECURITY.md) and
[`docs/explanation/threat-model.md`](docs/explanation/threat-model.md) for the boundary
and reporting flow.
Repository-specific contribution and security policy files live in this repository.
Organization-wide defaults may still be inherited from `nwarila-platform/.github` where
GitHub supports inherited community-health files.
## License
[MIT](LICENSE).