Vault Operations¶

Operational guide for HashiCorp Vault secrets management in the fzymgc-house cluster.

Quick Reference¶

Property	Value
URL	`https://vault.fzymgc.house`
Auth Methods	OIDC (Authentik), Token
Storage Backend	Integrated Storage (Raft)
Terraform Module	`tf/vault/`
Helper Script	`./scripts/vault-helper.sh`

Secret Structure¶

All infrastructure secrets stored under secret/fzymgc-house/:

Path	Purpose
`infrastructure/bmc/tpi-alpha`	TuringPi Alpha BMC credentials
`infrastructure/bmc/tpi-beta`	TuringPi Beta BMC credentials
`infrastructure/cloudflare/api-token`	Cloudflare API token
`cluster/authentik`	Authentik Terraform token
`cluster/windmill`	Windmill secrets (Discord, S3, tokens)
`cluster/hcp-terraform`	HCP Terraform agent token

Authentication¶

export VAULT_ADDR=https://vault.fzymgc.house

# OIDC login (browser-based)
vault login -method=oidc

# Token login
vault login

Common Operations¶

Read a Secret¶

vault kv get secret/fzymgc-house/cluster/authentik

# Get single field
vault kv get -field=terraform_token secret/fzymgc-house/cluster/authentik

List Secrets¶

vault kv list secret/fzymgc-house/cluster/

Write a Secret¶

vault kv put secret/fzymgc-house/cluster/example key=value

Helper Script Operations¶

# Check connectivity
./scripts/vault-helper.sh status

# List infrastructure secrets
./scripts/vault-helper.sh list

# Get specific secret
./scripts/vault-helper.sh get bmc/tpi-alpha

# Get single field
./scripts/vault-helper.sh get bmc/tpi-alpha password

Integration Examples¶

Ansible Integration¶

# Vault lookup in group_vars
tpi_bmc_password: "{{ lookup('community.hashi_vault.vault_kv2_get', 'infrastructure/bmc/tpi-alpha', engine_mount_point='secret/fzymgc-house').secret.password }}"

cloudflare_api_token: "{{ lookup('community.hashi_vault.vault_kv2_get', 'infrastructure/cloudflare/api-token', engine_mount_point='secret/fzymgc-house').secret.token }}"

Requires community.hashi_vault collection (installed via requirements).

Terraform Integration¶

data "vault_kv_secret_v2" "cloudflare" {
  mount = "secret/fzymgc-house"
  name  = "infrastructure/cloudflare/api-token"
}

provider "cloudflare" {
  api_token = data.vault_kv_secret_v2.cloudflare.data["token"]
}

Secret Rotation¶

Manual Rotation¶

Generate new credential
Update Vault secret
Restart affected pods to pick up changes

Automatic Rotation¶

Some secrets support automatic rotation via Vault policies.

Required Policy¶

Developers need infrastructure-developer policy. Defined in tf/vault/policy-infrastructure-developer.hcl:

path "secret/data/fzymgc-house/infrastructure/*" {
  capabilities = ["read", "list"]
}
path "secret/metadata/fzymgc-house/infrastructure/*" {
  capabilities = ["list"]
}
path "secret/data/fzymgc-house/*" {
  capabilities = ["read", "list"]
}
path "secret/metadata/fzymgc-house/*" {
  capabilities = ["list"]
}

Troubleshooting¶

Vault Sealed¶

If Vault is sealed, unseal keys are required. Contact cluster admin.

Permission Denied¶

Check your Vault policy assignments in Authentik groups.

Connectivity Issues¶

curl -s https://vault.fzymgc.house/v1/sys/health
vault token lookup

Ansible Secret Issues¶

ansible-galaxy collection list | grep hashi_vault
ansible localhost -m debug -a "msg={{ lookup('community.hashi_vault.vault_kv2_get', 'infrastructure/bmc/tpi-alpha', engine_mount_point='secret/fzymgc-house').secret.password }}"

Terraform Issues¶

vault token lookup
terraform console
> data.vault_kv_secret_v2.authentik.data