Skip to content

Initialise Proxmox target credentials

Purpose: Initialise validated Proxmox runtime credentials and readiness state for module execution.
Owner: Platform operations
Trigger: First-time Proxmox onboarding, token rotation, or runtime rebuild.
Impact: Proxmox-backed modules cannot run without a ready target and valid credentials.
Severity: P2
Pre-reqs: hyops installed, SSH reachability to Proxmox host, vault password provider ready.
Rollback strategy: Remove generated credentials/readiness and revoke the Proxmox token if required.

Context

hyops init proxmox performs three outcomes:

  • Creates or updates Proxmox API token material and persists secret state in an env-scoped vault file.
  • Writes runtime credentials to an env-scoped credentials file.
  • Writes readiness metadata to an env-scoped marker file.

Token safety behavior:

  • Default behavior avoids accidental token rotation across envs.
  • If current env has no PROXMOX_TOKEN_SECRET, init checks other envs for a valid token matching the same Proxmox host + token ID and offers reuse.
  • --force explicitly rotates/regenerates token material.

Runtime root selection:

  • Recommended: --env <name> to scope runtime under ~/.hybridops/envs/<name>/.
  • Optional: --root <path> to override the runtime root explicitly.

Default output locations when using --env <name>:

  • Config: ~/.hybridops/envs/<name>/config/proxmox.conf
  • Vault: ~/.hybridops/envs/<name>/vault/bootstrap.vault.env
  • Credentials: ~/.hybridops/envs/<name>/credentials/proxmox.credentials.tfvars
  • Readiness: ~/.hybridops/envs/<name>/meta/proxmox.ready.json
  • Evidence: ~/.hybridops/envs/<name>/logs/init/proxmox/<run-id>/

When --bootstrap is used, HybridOps uploads and executes a remote bootstrap script on the Proxmox host to validate runtime values (node, storage, bridge) before writing local outputs.

Preconditions and safety checks

  • Confirm vault provider readiness (pass/GPG-backed provider): 
    hyops vault status-verbose
  • Confirm SSH access to Proxmox host with intended user/key: 
    ssh -o BatchMode=yes <ssh-user>@<proxmox-ip> true

Steps

1) Create the Proxmox init config template (first run)
- Command: 

hyops init proxmox --env <env>
- Expected result: - ~/.hybridops/envs/<env>/config/proxmox.conf is created. - Command exits with code 10 (template written).

2) Populate Proxmox config
- File: - ~/.hybridops/envs/<env>/config/proxmox.conf - Required values: - [proxmox].host - [proxmox].user_fq - Optional overrides: - fallback_storage_vm, fallback_storage_iso, fallback_storage_snippets, fallback_bridge - ssh_username, ssh_private_key

3) Run bootstrap init
- Command: 

hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>
- Notes: - If you already ran hyops vault bootstrap, HyOps uses the persisted provider command automatically. - If vault is locked in a fresh shell, unlock once: 
hyops vault password >/dev/null
- Optional explicit SSH controls: 
hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip> \
  --ssh-username <ssh-user> \
  --ssh-private-key <path-to-private-key>
- Expected result: - target=proxmox status=ready is printed. - Readiness and credentials paths are printed. - Runtime discovery summary is printed with value provenance. - If a valid token exists in another env, init may prompt to reuse it instead of rotating.

4) Run non-interactive mode (CI/operator automation)
- Command: 

hyops init proxmox --non-interactive --env <env> --bootstrap --proxmox-ip <proxmox-ip>
- Notes: - Provide vault password source via environment (recommended: HYOPS_VAULT_PASSWORD_COMMAND) or pre-bootstrap the persisted provider command. - Ensure SSH auth and vault provider are pre-seeded.

Verification

  • Target preflight succeeds: 
    hyops preflight --env <env> --target proxmox
  • Readiness marker exists and reports status=ready:
  • ~/.hybridops/envs/<env>/meta/proxmox.ready.json
  • Credentials file exists with restricted mode:
  • ~/.hybridops/envs/<env>/credentials/proxmox.credentials.tfvars
  • Runtime provenance is present in readiness:
  • storage_vm_source
  • storage_iso_source
  • storage_snippets_source
  • bridge_source

Interpretation of provenance: - detected: discovered from remote Proxmox runtime. - configured: taken from configured values and validated on the host. - fallback: only used when discovery is unavailable.

Troubleshooting

scp upload failed

  • Cause: SSH connectivity/authentication mismatch (user, key, host policy).
  • Remediation: 
    ssh -o BatchMode=yes <ssh-user>@<proxmox-ip> true
scp -o BatchMode=yes <local-file> <ssh-user>@<proxmox-ip>:/tmp/
  • Check evidence:
  • ~/.hybridops/envs/<env>/logs/init/proxmox/<run-id>/scp_upload.stderr.txt

vault password command timed out while waiting for unlock

  • Cause: GPG key prompt was not completed before timeout.
  • Remediation: 
    hyops vault password >/dev/null
export HYOPS_VAULT_PASSWORD_COMMAND_TIMEOUT_S=300
hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>

Runtime validation fails for storage or bridge

  • Cause: configured values exist but are not valid on the Proxmox host.
  • Remediation:
  • Verify Proxmox storage IDs and content flags (images, iso, snippets).
  • Verify bridge exists and is UP.
  • Correct ~/.hybridops/envs/<env>/config/proxmox.conf values and rerun bootstrap.

Vault persistence fails

  • Cause: missing or invalid vault password source.
  • Remediation: 
    hyops vault status-verbose
hyops vault bootstrap
hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>

Post-actions and clean-up

  • Archive run_id, readiness file path, and credentials path in the related change record.
  • Revoke superseded Proxmox token material during token rotation workflows.
  • Restrict permissions on env-scoped credential files and confirm they are not committed to source control.
  • For CI/bootstrap automation, document the vault password source and timeout settings used.

References