Skip to content

Sync Azure Key Vault secrets into runtime vault bundle

  • Purpose: Populate the runtime vault bundle with selected AKV secrets for bootstrap/CI/DR runs. Owner: Platform operations

  • Trigger: Before running modules that require secrets, or when rotating secrets in AKV.

  • Impact: Without this sync (or explicit overrides), modules may fail with missing env vars.

  • Severity: P3 Pre-reqs: az and ansible-vault installed; access to the Key Vault.

  • Rollback strategy: Overwrite keys via hyops secrets set or rotate in AKV and re-sync.

Context

HyOps treats AKV as the steady-state source of truth for secret values (ADR-0020). For bootstrap and controlled automation runs, HyOps can sync a selected allowlist into:

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

This command does not print secret values.

Preconditions and safety checks

  • Confirm the Azure CLI can access the vault:

    az account show

  • Confirm the vault password provider is ready (workstations):

    hyops vault status-verbose

Notes: - After hyops vault bootstrap, HyOps remembers the provider command at ~/.hybridops/config/vault-password-command. - In a fresh shell, if vault is locked, unlock once:

    hyops vault password >/dev/null

Steps

1) Dry-run the sync

  • Command:

    hyops secrets akv-sync --env dev --vault-name --dry-run

  • Expected result: a list of env keys that would be synced.

2) Run the sync

  • Command:

    hyops secrets akv-sync --env dev --vault-name

  • Expected result: synced <N> keys into <root>/vault/bootstrap.vault.env.

Verification

  • Run a module preflight that requires secrets and confirm it no longer fails with missing env vars.

Troubleshooting

vault decrypt failed / not ready from hyops vault status-verbose

  • Meaning: vault provider exists but cannot decrypt in the current shell.

  • Remediation:

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

vault password command timed out while waiting for unlock

  • Meaning: GPG unlock did not complete before timeout.

  • Remediation:

    hyops vault password >/dev/null export HYOPS_VAULT_PASSWORD_COMMAND_TIMEOUT_S=300 hyops secrets akv-sync --env --vault-name

References

License: MIT-0 for code, CC-BY-4.0 for documentation