Skip to content

Vault Secret Path Conventions

The naming convention for all CWIQ secret paths and a complete reference table of currently provisioned secrets.

All CWIQ secrets are stored in the KV v2 secrets engine mounted at secret/. Every secret has a structured path that encodes its scope, environment, application, and concern.

API Path vs. UI Path

KV v2 inserts a data/ segment into paths when accessed via the HTTP API. The Vault UI and CLI omit this segment.

Access Method Path Format Example
HTTP API (curl, Vault Agent templates) secret/data/{scope}/{env}/{app}/{concern} secret/data/cwiq/dev/orchestrator/database
Vault UI / CLI secret/{scope}/{env}/{app}/{concern} secret/cwiq/dev/orchestrator/database

KV v2 API paths always include data/.

When writing curl commands or Vault Agent templates, always include data/ in the path. When browsing the Vault UI or running vault kv get, omit data/. This is a frequent source of 404 errors when writing templates for the first time.

Path Convention

secret/{scope}/{env}/{app}/{concern}
Segment Options Notes
{scope} cwiq, nexus, sonarqube, defectdojo, orchestrator, reportportal Top-level grouping by system
{env} shared, dev, demo, prod Only used under the cwiq scope
{app} Application name (e.g., orchestrator, authentik, gitlab) Service or tool name
{concern} database, config, oidc, admin, svc-orchestrator What type of secret

Service account paths (used by CI/CD) follow a flatter convention: secret/{tool}/svc-orchestrator.

Complete Secret Path Reference

Platform Application Secrets (cwiq scope)

These secrets are used by application containers at runtime, delivered via the Vault Agent sidecar.

Vault Path (CLI) Keys Used By
secret/cwiq/dev/orchestrator/database pg_host, pg_user, pg_password, pg_name, pg_port Orchestrator server, all DEV microservices
secret/cwiq/dev/orchestrator/config secret_key Orchestrator server application config
secret/cwiq/shared/authentik/database pg_host, pg_user, pg_password, pg_name, pg_port Authentik SSO containers
secret/cwiq/shared/gitlab/oidc client_id, client_secret GitLab OIDC provider config
secret/cwiq/shared/nexus/config admin_password Nexus provisioning playbook

Nexus Service Accounts

Used by CI/CD pipeline jobs to authenticate with the Nexus Docker registry and artifact repositories.

Vault Path (CLI) Keys Used By
secret/nexus/svc-orchestrator username, password Docker push/pull, Kaniko builds, Trivy image scan, PyPI publish
secret/nexus/svc-executor username, password Executor RPM builds and binary uploads
secret/nexus/svc-deployer username, password Pull-only — Ansible and EC2 deployments that pull Docker images
secret/nexus/admin username, password Nexus admin UI access

SonarQube

Vault Path (CLI) Keys Used By
secret/sonarqube/admin username, password SonarQube admin UI — human access only
secret/sonarqube/svc-orchestrator token, url sonarqube-scan CI job

DefectDojo

Vault Path (CLI) Keys Used By
secret/defectdojo/admin username, password DefectDojo admin UI — human access only
secret/defectdojo/svc-orchestrator token defectdojo-import CI job

Platform Services

Vault Path (CLI) Keys Used By
secret/orchestrator/e2e-test-user username, password E2E test global setup — authenticates the test admin user
secret/reportportal/svc-orchestrator api_key e2e-test CI job — ReportPortal reporter

Adding New Secrets

When deploying a new application or adding a new service account, follow this process:

Step 1 — Choose the correct path. Follow the convention. For a new application in DEV, the path is secret/cwiq/dev/{app}/{concern}. For a new tool's service account, the path is secret/{tool}/svc-orchestrator.

Step 2 — Write the secret to Vault. From the Vault CLI or the Vault UI:

vault kv put secret/cwiq/dev/my-service/database \
  pg_host=10.1.35.46 \
  pg_user=my-service \
  pg_password=<generated-password> \
  pg_name=my_service \
  pg_port=5432

Step 3 — Update the Vault policy for the AppRole or CI role that needs to access the new path.

Step 4 — Update the documentation. Add the new path to the table above and update ansible-playbooks/vault-server/docs/02-cli-operations.md with the new entry in the CLI operations reference. Both files must be updated in the same commit.

After storing new admin credentials in Vault, report them to the user.

When Ansible deploys a new application and stores its admin credentials in Vault, always present the username, password, and access URL to the operator so they can verify access. Do not assume the operator knows where to find the credentials.

Vault CLI Quick Reference

# Read a secret (CLI)
vault kv get secret/cwiq/dev/orchestrator/database

# Read a specific field
vault kv get -field=pg_password secret/cwiq/dev/orchestrator/database

# Write / update a secret
vault kv put secret/cwiq/dev/orchestrator/config secret_key=new-value

# List secrets under a path
vault kv list secret/cwiq/dev/orchestrator/

# Check the metadata (version history)
vault kv metadata get secret/cwiq/dev/orchestrator/database

All CLI commands require a valid Vault token. Log in first with vault login (OIDC) or set VAULT_TOKEN in your shell.