This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Specifications

1 - Infra pve

1.1 - Proxmox infrastructure Specification

Specify the Proxmox cluster configuration, resource pools, and bootstrap test VM owned by infra/pve. The baseline is checked-in source at revision 550d7e79b1f5fdbc2b6017b75178471d6914082f, observed on 2026-09-08. It describes declared infrastructure and packaged operator entry points; deployment and cluster health have not been observed for this baseline.

The Terraform configuration SHALL resolve the members of Vault’s approles identity group and declare one Proxmox pool per resolved entity, keyed and named by that entity’s name. It SHALL also declare a separate templates pool.

Sources: project documentation and resource pool definitions.

  • WHEN Terraform resolves the entities in the Vault approles group
  • THEN the desired configuration includes a pool with each entity’s name and the dedicated templates pool.

The PVE Ansible entry point SHALL package the inventory and deployment playbook and apply the shared host and PVE roles to the pve1 inventory group. It SHALL package the canonical shared cloud-init files under files/cloud_init.yaml and files/cloud_init_min.yaml, preserving the existing snippet update flow.

Sources: deployment target, playbook, and snippet variables.

  • WHEN the Ansible binary’s source package is built
  • THEN it includes the playbook, inventory, shared role collection, and both shared cloud-init files under their established aliases.

The Terraform configuration SHALL declare its cloud-init test VM through the shared pve_vm_qemu module, derive its hostname and address from the project’s DNS configuration, and place it in the src_infra_dc1_pve1 AppRole pool. The baseline declaration SHALL use VM ID 100, a 5G scsi0 disk, and the test tag.

Sources: VM definition and DNS configuration.

  • WHEN Terraform evaluates module.vm_cloudinit_test
  • THEN its name and /24 address derive from cloudinit_test DNS fields, and its pool resolves to the declared PVE AppRole pool.

PVE Terraform commands SHALL use the project’s AL configuration and the declared Terraform, PVE-login, and Vault-environment plugins. The package SHALL include the lockfile, Terraform source, shared backend and VM modules, and required Vault helper targets. PVE Ansible commands SHALL likewise use the project AL configuration and packaged injector.

Sources: Terraform wrapper and Ansible wrapper.

  • WHEN a repository Terraform command target is invoked with authorization for its operation
  • THEN the wrapper supplies the declared modules and helper inputs and selects the tf, pve_login, and vault_env=default_default plugins.

2 - Owned dns

2.1 - owned-dns Specification

Define Proxmox cluster DNS management through the owner’s tf root, including canonical declarations, scoped credentials, and offline source checks before adopting live records.

The tf root SHALL consume this owner’s canonical dnsconfig.json through the shared DNS Terraform module, preserving declared record identities and views. DNS resources SHALL default to disabled until the authorized adoption revision and SHALL retain enabled ownership after existing records are imported into the owner’s state. Reconciliation against unchanged declarations and adopted state SHALL propose no record additions, changes, replacements, or deletions.

  • WHEN the checked-in root is evaluated with default inputs before its authorized adoption revision
  • THEN it reads this owner’s declaration and disables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the authorized adoption audits competing writers, keeps identified writers stopped within the recorded coverage, and enables owner record management
  • THEN the owning root imports existing records by exact provider ID into its state while preserving their declared identities and views
  • WHEN the adopted root uses its checked-in source defaults
  • THEN DNS ownership remains enabled and the package retains the module and canonical declaration inputs
  • WHEN the owning root plans against its adopted state and unchanged declarations
  • THEN it proposes no record additions, changes, replacements, or deletions

The DNS wrappers SHALL select src_infra_dc1_pve1 through the repository AL flow and keep secret values in injected variables. dns.plan, dns.show, and dns.apply SHALL select dns=1 and operate on module.dns in the existing tf root and backend. Apply SHALL consume the reviewed saved plan. Required root inputs SHALL retain their existing Vault readers, while ordinary Proxmox authentication SHALL remain separate. Scoped DNS operations SHALL verify DNS and its dependencies without establishing overall PVE service health. Real DNS credentials and Vault policy grants SHALL be prerequisites for operational Terraform calls. RouterOS DNS credentials SHALL be isolated from unrelated RouterOS resources. The package SHALL expose a format test that does not authenticate to Vault or contact DNS providers.

  • WHEN the package format test executes
  • THEN it checks the packaged Terraform configuration without live credentials
  • AND existing non-DNS authentication and backend paths remain unchanged
  • WHEN the scoped DNS wrapper selects dns=1
  • THEN it selects DNS credential injection through the owner AppRole and uses the existing root and backend without starting Proxmox login
  • AND the targeted plan and saved-plan apply cover DNS and its dependencies, without proving PVE host or API health
  • AND disabled DNS resources do not imply offline provider configuration