Skip to content

Bootstrap vault password provider

Execution context: Run this procedure from a terminal where hyops --help succeeds. If HybridOps.Core is not installed, complete the Quickstart. For deployment support, use GitHub Discussions.

  • 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

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

GPG passphrase is no longer available

Use guarded recovery for an environment that has not yet applied the affected credentials:

hyops vault recover \
  --env <env> \
  --ref <blueprint-ref>

Recovery verifies that the password store and GPG key are dedicated to HybridOps, creates a local backup and requires typed confirmation. It does not change deployed infrastructure. Recovery stops if the selected blueprint has already applied credentials that cannot be regenerated safely, or if another environment vault uses the same workstation password provider.

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