Skip to content

Bootstrap vault password provider

  • Purpose: Enable non-interactive vault operations by bootstrapping the local vault password provider. Owner: Platform operations

  • Trigger: First-time install or when vault provider is not ready.

  • Impact: Without a provider, vault bundles cannot be decrypted or updated.

  • Severity: P3 Pre-reqs: pass, gpg, and a terminal pinentry are installed.

  • Rollback strategy: Remove stored entry via hyops vault reset.

Context

HybridOps.Core uses an Ansible Vault encrypted env bundle for bootstrap and CI/DR execution. The local password provider is backed by pass and gpg and is invoked as an executable vault password file.

Preconditions and safety checks

  • Confirm prerequisites:

    command -v pass gpg ansible-vault

Steps

1) Bootstrap the provider - Command:

     hyops vault bootstrap
  • Expected result: Provider stores the vault password and reports success.
  • Note: HyOps persists the default provider command at ~/.hybridops/config/vault-password-command so other HyOps commands can decrypt vault files without extra flags.

2) Confirm provider readiness - Command:

     hyops vault status-verbose
  • Expected result: Output is ready.

  • Note: in a fresh shell, if you see not ready with a GPG/pinentry error, unlock once:

     hyops vault password >/dev/null

    Then re-run hyops vault status-verbose.

3) Verify vault operations (optional) - Action: generate a test key into the runtime vault bundle (values are not printed). - Command:

     hyops secrets ensure --env dev VAULT_PROVIDER_TEST
  • Expected result: command succeeds and the encrypted bundle exists at: ~/.hybridops/envs/dev/vault/bootstrap.vault.env

Verification

  • hyops vault status-verbose returns exit code 0 and prints ready.
  • hyops secrets ensure --env dev VAULT_PROVIDER_TEST succeeds.

Troubleshooting

hyops vault bootstrap fails with permission denied

  • Cause: provider script is not executable.
  • Remediation:

  • If using a HybridOps.Core repo checkout, ensure the script is executable:

    chmod 0755 tools/secrets/vault/vault-pass.sh

  • If HyOps is installed outside the core repo, pass an explicit script path:

    hyops vault --script /path/to/vault-pass.sh bootstrap

hyops vault bootstrap fails due to missing pass or gpg

  • Cause: prerequisites not installed.

  • Remediation:

    hyops setup base --sudo

Bootstrap hangs on pinentry

  • Cause: pinentry backend requires TTY.
  • Remediation:
  • Execute from an interactive terminal session.
  • Confirm pinentry-curses is installed:
    dpkg -l | grep -E '^ii\s+pinentry-curses\b' || true

hyops vault status-verbose prints not ready with No pinentry

  • Meaning: the vault password exists in pass but your GPG key is locked and cannot prompt (common in a fresh shell).

  • Remediation (interactive shells):

    hyops vault password >/dev/null hyops vault status-verbose

Post-actions and clean-up

  • For CI usage, provide a distinct password source and use --vault-password-command 'printenv <VAR>' for init targets that support it.

Platform-specific vault keys

Once the vault provider is ready, certain blueprint runs require additional keys to be populated manually before execution. These keys cannot be auto-generated because they represent external credentials.

Key Blueprint Purpose
HYOPS_GSM_SA_KEY_JSON onprem/rke2-workloads@v1 GCP Service Account key JSON used by External Secrets Operator to read from GCP Secret Manager.
RKE2_TOKEN onprem/rke2-workloads@v1, onprem/rke2@v1 RKE2 cluster join token (auto-generated by hyops secrets ensure if absent).

Set a platform key:

hyops secrets set --env <env> HYOPS_GSM_SA_KEY_JSON "$(cat /path/to/gcp-sa-key.json)"

The full list of required keys for each blueprint is documented in the corresponding blueprint runbook.

References