Generate bootstrap secrets into runtime vault bundle¶

Purpose: Generate and store missing secret env keys into the runtime vault bundle so modules can run non-interactively.
Owner: Platform operations
Trigger: Before first apply of a module that requires secrets (NetBox, EVE-NG, etc.).
Impact: Without these keys, modules fail fast with missing env-var errors.
Severity: P3
Pre-reqs: Vault password provider is ready (hyops vault status-verbose = ready).
Rollback strategy: Rotate keys with --force or overwrite explicitly via hyops secrets set.

Context¶

HyOps modules must not embed or print secret values. They reference secret env keys (for example NETBOX_DB_PASSWORD) via inputs.required_env and *_env fields.

For bootstrap/labs/CI/DR, HyOps supports a per-environment encrypted vault bundle:

~/.hybridops/envs/<env>/vault/bootstrap.vault.env

hyops secrets ensure generates strong random values for missing keys and stores them encrypted. Values are never printed to stdout.

In steady state, the external secret authority should remain the source of truth. Today the clean neutral path is HashiCorp Vault, with the runtime vault bundle acting only as an execution cache.

Note on NetBox authority:

If you are using HyOps "central NetBox authority" (default), generate NETBOX_* secrets in --env shared.

Preconditions and safety checks¶

Confirm the vault password provider is ready:
```
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
```
Confirm required tools exist:
```
command -v ansible-vault
```

Steps¶

1) Generate secrets by explicit key names
- Command:

hyops secrets ensure --env <env> NETBOX_DB_PASSWORD NETBOX_SECRET_KEY

- Expected result: keys are created in the encrypted vault bundle. - Evidence: ~/.hybridops/envs/<env>/vault/bootstrap.vault.env

2) Generate secrets from a module contract (recommended)
- Action: infer required keys from inputs.required_env. - Command:

hyops secrets ensure --env <env> --module platform/onprem/netbox --inputs <inputs.yml>

- Expected result: any missing keys listed in the module's inputs.required_env are created.

3) Rotate secrets (regenerate)
- Command:

hyops secrets ensure --env <env> --force NETBOX_DB_PASSWORD

- Expected result: key is overwritten in the vault bundle.

4) Override with explicit values
- Action: set values you choose (for example when using externally provided credentials). - Command:

hyops secrets set --env <env> NETBOX_DB_PASSWORD='...'

- Expected result: key is overwritten with the provided value.

5) Optional: persist generated or provided values upstream to HashiCorp Vault - Action: after hyops init hashicorp-vault --env <env> is ready, push the changed keys into the external authority too. - Commands:

hyops secrets ensure --env <env> --persist vault NETBOX_DB_PASSWORD NETBOX_SECRET_KEY

hyops secrets set --env <env> --persist vault NETBOX_DB_PASSWORD='...'

- Expected result: - runtime vault bundle updated - mapped keys also written to HashiCorp Vault

Verification¶

Module preflight passes without missing-env errors:

hyops preflight --env <env> --strict --module platform/onprem/netbox --inputs <inputs.yml>

Troubleshooting¶

`[vault-pass] ERROR: entry not ready (run --bootstrap)`¶

Remediation:
```
hyops vault bootstrap
```

`vault decrypt failed` / pinentry prompts¶

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

Remediation:

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

Then re-run the same hyops secrets ensure ... command.

`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 ensure --env <env> KEY1 [KEY2 ...]

References¶

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