Skip to content

Init HashiCorp Vault with hyops init hashicorp-vault

Purpose: Initialise env-scoped HashiCorp Vault settings so HybridOps can validate Vault reachability and use Vault as an external secret authority.
Owner: Platform operations
Trigger: First-time setup of an environment that will use HashiCorp Vault for secret sync or runner-dispatched DR workflows.
Impact: Without this init target, hyops secrets vault-sync and --persist vault flows cannot resolve a stable env-scoped Vault contract.
Severity: P3
Pre-reqs: Reachability to the target Vault endpoint; a valid token or token env var; ansible-vault installed if the token will be cached in the runtime vault bundle.
Rollback strategy: Remove or edit <root>/config/hashicorp-vault.conf and re-run init; rotate/revoke the upstream Vault token if needed.

Context

This runbook distinguishes two different vault concepts:

  • HashiCorp Vault = external secret authority
  • runtime vault bundle = per-environment encrypted cache at:
  • <root>/vault/bootstrap.vault.env

hyops init hashicorp-vault does not create or manage the Vault service itself. It validates the configured authority and writes env-scoped readiness metadata so later commands can use it safely.

Default files:

  • config:
  • <root>/config/hashicorp-vault.conf
  • readiness:
  • <root>/meta/hashicorp-vault.ready.json

Preconditions and safety checks

  • Confirm the target environment is correct: 

    echo "HYOPS_ENV=$HYOPS_ENV"

  • Confirm Vault address and token source: 

    echo "$VAULT_ADDR"
echo "${VAULT_TOKEN:+set}"

  • If you plan to persist the token into the runtime vault bundle, confirm the local vault password provider is ready: 

    hyops vault status-verbose

Steps

1) Bootstrap in one command (recommended)

  • Command: 

    VAULT_TOKEN='...' \
hyops init hashicorp-vault --env dev \
  --bootstrap \
  --vault-addr https://vault.example.com

  • Expected result:

  • config file is written under <root>/config/hashicorp-vault.conf
  • token is validated against auth/token/lookup-self
  • readiness marker is written

You can also add browser-assisted login guidance:

hyops init hashicorp-vault --env dev \
  --bootstrap \
  --vault-addr https://vault.example.com \
  --with-cli-login

In that mode, HyOps opens the Vault UI and then prompts you to paste a token for validation.

2) Generate the config template (manual path)

  • Command: 

    hyops init hashicorp-vault --env dev

  • Expected result:

  • If the config does not exist, HyOps writes a template and exits with guidance.
  • Edit <root>/config/hashicorp-vault.conf.

3) Populate the non-secret config

  • Minimum required value: 

    VAULT_ADDR=https://vault.example.com

  • Optional values: 

    VAULT_NAMESPACE=
VAULT_TOKEN_ENV=VAULT_TOKEN
VAULT_ENGINE=kv-v2
VAULT_MAP_FILE=
VAULT_AUTH_METHOD=token

4) Validate readiness without persisting the token

  • Command: 

    VAULT_ADDR=https://vault.example.com \
VAULT_TOKEN='...' \
hyops init hashicorp-vault --env dev

  • Expected result:

  • readiness marker written
  • token validated via auth/token/lookup-self
  • no token written to evidence

5) Optional: persist the token into the runtime vault cache

  • Use this only when you deliberately want the env runtime cache to carry the token for automation: 

    VAULT_ADDR=https://vault.example.com \
VAULT_TOKEN='...' \
hyops init hashicorp-vault --env dev --persist-token

  • Expected result:

  • readiness marker written
  • token cached under the configured VAULT_TOKEN_ENV key inside:
    • <root>/vault/bootstrap.vault.env

You can combine this with one-shot bootstrap:

VAULT_TOKEN='...' \
hyops init hashicorp-vault --env dev \
  --bootstrap \
  --vault-addr https://vault.example.com \
  --persist-token

Verification

  • Confirm readiness: 

    cat ~/.hybridops/envs/dev/meta/hashicorp-vault.ready.json

  • Confirm the configured token env key name: 

    jq -r '.context.vault_token_env' ~/.hybridops/envs/dev/meta/hashicorp-vault.ready.json

  • Optional: if --persist-token was used, confirm the token key exists in the runtime vault bundle: 

    hyops secrets show --env dev VAULT_TOKEN

Troubleshooting

ERR: VAULT_ADDR is required

  • Meaning: the config file is missing VAULT_ADDR, and no override was provided.

  • Remediation:

  • set VAULT_ADDR in <root>/config/hashicorp-vault.conf
  • or pass --vault-addr

ERR: --bootstrap requires --vault-addr or VAULT_ADDR

  • Meaning: one-shot bootstrap was requested without a Vault address.

  • Remediation: 

    hyops init hashicorp-vault --env dev --bootstrap --vault-addr https://vault.example.com

ERR: Vault token not available

  • Meaning: no token was found in --token, the configured token env var, or the runtime vault cache.

  • Remediation: 

    export VAULT_TOKEN='...'
    or: 
    hyops init hashicorp-vault --env dev --bootstrap --vault-addr https://vault.example.com --with-cli-login

ERR: HashiCorp Vault validation failed

  • Meaning: Vault is unreachable, the token is invalid, the namespace is wrong, or the auth method is unsupported.

  • Remediation:

  • confirm VAULT_ADDR
  • confirm VAULT_NAMESPACE
  • confirm the token has permission for auth/token/lookup-self

References

Maintainer: HybridOps.Studio
License: MIT-0 for code, CC-BY-4.0 for documentation