Skip to content

Init annex: Proxmox

Status: Stable (Public)
Version: 1.0

This annex defines Proxmox-specific requirements and outputs for hyops init proxmox.

Global rules are defined in hyops init contract.

1. Config

Default config path:

  • <root>/config/proxmox.conf

Config format is INI with [proxmox] section.

1.1 Required keys

  • PROXMOX_IP
    Proxmox host IP or resolvable hostname for SSH access.

  • USER_FQ
    Proxmox user identifier in user@realm form (example: automation@pam).

1.2 Optional keys

  • TOKEN_NAME (default: infra-token)
  • TLS_SKIP (default: true)
  • HTTP_PORT (default: 8802)

Fallbacks used when remote bootstrap does not return values:

  • FALLBACK_STORAGE_VM (default: local-lvm)
  • FALLBACK_STORAGE_ISO (default: local)
  • FALLBACK_BRIDGE (default: vmbr0)

SSH wiring for provider operations:

  • PROXMOX_SSH_USERNAME (default: root)
  • PROXMOX_SSH_KEY (default: ~/.ssh/id_ed25519)

HTTP bind override for Packer HTTP server:

  • HTTP_BIND_ADDRESS (optional; if unset, autodetect)

2. Vault keys

Default vault path:

  • <root>/vault/bootstrap.vault.env

Secrets used:

  • PROXMOX_TOKEN_SECRET

Rules:

  • PROXMOX_TOKEN_SECRET MUST be present for --non-interactive.
  • In interactive mode, if PROXMOX_TOKEN_SECRET exists in the current env vault it MUST be reused.
  • If current env vault has no token secret, init SHOULD attempt cross-env token reuse:
  • scan sibling env runtimes under ~/.hybridops/envs/*
  • match by proxmox_url host + proxmox_token_id
  • validate candidate token via Proxmox API before reuse
  • prompt operator to reuse (default yes) in interactive mode
  • auto-reuse in --non-interactive
  • --force MUST bypass reuse logic and rotate/regenerate token material.

3. Remote bootstrap

Remote bootstrap is used to create/rotate a Proxmox token and discover runtime values.

Norms:

  • Remote bootstrap MUST execute on the Proxmox host via SSH as root@PROXMOX_IP.
  • Remote bootstrap MUST ensure the configured API user exists.
  • Remote bootstrap MUST create or rotate TOKEN_NAME when token generation is required.
  • Remote bootstrap MUST return non-secret runtime values where possible:
  • node name
  • API IP used for proxmox_url
  • storage IDs for images, iso, snippets
  • bridge name

If a value is not returned, the corresponding fallback key MUST be used when defined.

4. Outputs

4.1 Credentials tfvars

Default path:

  • <root>/credentials/proxmox.credentials.tfvars

The file MUST be mode 0600.

The tfvars file MUST include:

  • proxmox_url
  • proxmox_token_id
  • proxmox_token_secret
  • proxmox_node
  • proxmox_skip_tls
  • proxmox_ssh_username
  • proxmox_ssh_key
  • storage_pool
  • storage_iso
  • storage_snippets
  • network_bridge
  • http_bind_address
  • http_port

Optional:

  • ssh_public_key when a local public key is discoverable.

4.2 Readiness marker

Default path:

  • <root>/meta/proxmox.ready.json

The marker MUST reflect status=ready only when the credentials file is written successfully and required vault persistence (if any) has completed.

5. Failure semantics

  • If --non-interactive is set and PROXMOX_TOKEN_SECRET is missing, init MUST fail with exit code 21.
  • If remote bootstrap is required and fails, init MUST fail with exit code 20.
  • If credentials file writing fails, init MUST fail with exit code 30.