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.
  • If current env has a stale PROXMOX_TOKEN_SECRET, init first tries to heal from a valid sibling env token for the same host + token ID.
  • Cross-env healing prefers the sibling credentials file when it already carries a valid current token, then falls back to the sibling vault entry.
  • If no reusable sibling token exists, init clears the stale secret and refreshes it through remote bootstrap.
  • --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
  • Run record: ~/.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 @ 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.
    • If the current env token is stale, init heals it automatically before rotating.
    • Init validates both basic API auth and snippet-storage content access before writing status=ready.

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 --target proxmox

  • Readiness marker exists and reports status=ready:

  • ~/.hybridops/envs/<env>/meta/proxmox.ready.json
  • When a public key is discoverable or configured, readiness includes:
  • context.ssh_public_key
  • 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.

Example check:

jq -r ".context.ssh_public_key" ~/.hybridops/envs/<env>/meta/proxmox.ready.json

Troubleshooting

scp upload failed

  • Cause: SSH connectivity/authentication mismatch (user, key, host policy).

  • Remediation:

    ssh -o BatchMode=yes @ true scp -o BatchMode=yes @:/tmp/

  • Check run record:

  • ~/.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 --bootstrap --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.

proxmox token validation failed for snippet storage content access

  • Cause: token auth worked for /version but does not have usable content access to the resolved storage_snippets datastore.
  • Remediation:

  • Re-run:

    hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>

  • Confirm the resolved snippets storage is correct in:

    • ~/.hybridops/envs/<env>/meta/proxmox.ready.json
  • If multiple envs share the same token ID, let init heal from a valid sibling token rather than forcing rotation unless you intend to rotate the shared token.

Vault persistence fails

  • Cause: missing or invalid vault password source.

  • Remediation:

    hyops vault status-verbose hyops vault bootstrap hyops init proxmox --env --bootstrap --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