Skip to content

Init annex: HashiCorp Vault

Status: Stable (Public)
Version: 1.0

This annex defines HashiCorp Vault-specific requirements and outputs for hyops init hashicorp-vault.

Global rules are defined in hyops init contract.

1. Config

Default config path:

  • <root>/config/hashicorp-vault.conf

Config format is line-oriented KEY=value.

1.1 Required keys (non-secret)

  • VAULT_ADDR
    Base URL for the external HashiCorp Vault authority.

1.2 Optional keys (non-secret)

  • VAULT_NAMESPACE
    Optional namespace for Vault Enterprise / HCP-style layouts.

  • VAULT_TOKEN_ENV
    Environment variable name used to supply a Vault token at init or sync time. Default: VAULT_TOKEN.

  • VAULT_ENGINE
    Secret engine mode used for mapped secret refs. Supported values:

  • kv-v1

  • kv-v2 (default)

  • VAULT_MAP_FILE
    Optional explicit secret map file path for hyops secrets vault-sync and --persist vault.

  • VAULT_AUTH_METHOD
    Authentication method for init readiness validation. Current supported value:

  • token

2. Runtime vault interaction

Default runtime vault bundle:

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

This init target may optionally persist the validated token into the runtime vault bundle under the configured VAULT_TOKEN_ENV key when --persist-token is used.

Norms:

  • The external HashiCorp Vault authority is the source of truth.
  • The runtime vault bundle is only an encrypted execution cache.
  • Persisting a Vault token into the runtime vault bundle is optional and operator-controlled.

3. Behaviour

3.1 Interactive mode

hyops init hashicorp-vault does not require an interactive login flow today.

Operators provide a token through one of:

  • --token
  • shell env via the configured token env var
  • an already-populated runtime vault bundle entry

The init target SHOULD support a one-shot bootstrap path where config is rendered from flags and/or environment without a manual file edit step, for example:

  • --bootstrap --vault-addr https://vault.example.com

When --with-cli-login is used in an interactive shell, the init target MAY open the Vault UI in a browser and prompt the operator to paste a token for validation.

3.2 Non-interactive mode

When --non-interactive is set:

  • init MUST NOT prompt
  • a usable token MUST already be available
  • init MUST validate reachability and token usability via auth/token/lookup-self

3.3 Credential validation

Validation MUST confirm:

  • Vault API is reachable at VAULT_ADDR
  • the token is accepted by auth/token/lookup-self

Validation MUST NOT persist tokens into logs or evidence.

4. Outputs

4.1 Readiness marker

Default path:

  • <root>/meta/hashicorp-vault.ready.json

The marker MUST reflect status=ready only when:

  • config is valid
  • token validation succeeds

The marker SHOULD include:

  • context.vault_addr
  • context.vault_namespace
  • context.vault_token_env
  • context.vault_engine
  • context.vault_map_file
  • context.auth_method
  • context.persisted_token

4.2 Evidence

Evidence MUST be written under:

  • <root>/logs/init/hashicorp-vault/<run_id>/

Evidence MUST NOT include secret values or raw Vault tokens.

5. Failure semantics

  • If VAULT_ADDR is missing, init MUST fail with an operator-facing configuration error.
  • If the token is unavailable, init MUST fail with guidance naming the configured token env var.
  • If Vault validation fails, init MUST fail clearly and write evidence.