mosaicstack/stack
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 14 Wiki Activity

chore(format): prettier-normalize VAULT-SECRETS.md (table alignment + inline comments)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details

Browse Source
This commit is contained in:
Mos worker
2026-06-11 13:20:58 -05:00
parent 0a224efb82
commit f6b901dbca
2 changed files with 34 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
guides/VAULT-SECRETS.md
View File

@@ -210,15 +210,15 @@ Error: token expired
Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
| --- | --- | --- |
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
@@ -254,16 +254,16 @@ metadata:
spec:
refreshInterval: 1h
secretStoreRef:
name: vault-backend # ClusterSecretStore name — verify with cluster admin
name: vault-backend # ClusterSecretStore name — verify with cluster admin
kind: ClusterSecretStore
target:
name: <app>-secrets # k8s Secret name that will be created
name: <app>-secrets # k8s Secret name that will be created
creationPolicy: Owner
data:
- secretKey: DB_PASSWORD # key in the k8s Secret
- secretKey: DB_PASSWORD # key in the k8s Secret
remoteRef:
key: secret/k3s/<app> # Vault path
property: db_password # field within the Vault secret
key: secret/k3s/<app> # Vault path
property: db_password # field within the Vault secret
- secretKey: API_KEY
remoteRef:
key: secret/k3s/<app>
@@ -282,7 +282,7 @@ env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: <app>-secrets # matches ExternalSecret target.name
name: <app>-secrets # matches ExternalSecret target.name
key: DB_PASSWORD
- name: API_KEY
valueFrom:
@@ -295,7 +295,7 @@ env:
name: <app>-secrets
key: JWT_SECRET
- name: PORT
value: "3000" # safe-default: non-secret, no Vault needed
value: '3000' # safe-default: non-secret, no Vault needed
```
### 4. App-side schema validation — TypeScript (zod)
@@ -471,7 +471,7 @@ spec:
# deploy/deployment.yaml (env section for Direct-Vault app)
env:
- name: VAULT_ADDR
value: "https://vault.example.com" # safe-default: non-secret cluster address
value: 'https://vault.example.com' # safe-default: non-secret cluster address
- name: VAULT_ROLE_ID
valueFrom:
secretKeyRef:

34
packages/mosaic/framework/guides/VAULT-SECRETS.md
View File

@@ -210,15 +210,15 @@ Error: token expired
Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
| --- | --- | --- |
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
@@ -254,16 +254,16 @@ metadata:
spec:
refreshInterval: 1h
secretStoreRef:
name: vault-backend # ClusterSecretStore name — verify with cluster admin
name: vault-backend # ClusterSecretStore name — verify with cluster admin
kind: ClusterSecretStore
target:
name: <app>-secrets # k8s Secret name that will be created
name: <app>-secrets # k8s Secret name that will be created
creationPolicy: Owner
data:
- secretKey: DB_PASSWORD # key in the k8s Secret
- secretKey: DB_PASSWORD # key in the k8s Secret
remoteRef:
key: secret/k3s/<app> # Vault path
property: db_password # field within the Vault secret
key: secret/k3s/<app> # Vault path
property: db_password # field within the Vault secret
- secretKey: API_KEY
remoteRef:
key: secret/k3s/<app>
@@ -282,7 +282,7 @@ env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: <app>-secrets # matches ExternalSecret target.name
name: <app>-secrets # matches ExternalSecret target.name
key: DB_PASSWORD
- name: API_KEY
valueFrom:
@@ -295,7 +295,7 @@ env:
name: <app>-secrets
key: JWT_SECRET
- name: PORT
value: "3000" # safe-default: non-secret, no Vault needed
value: '3000' # safe-default: non-secret, no Vault needed
```
### 4. App-side schema validation — TypeScript (zod)
@@ -471,7 +471,7 @@ spec:
# deploy/deployment.yaml (env section for Direct-Vault app)
env:
- name: VAULT_ADDR
value: "https://vault.example.com" # safe-default: non-secret cluster address
value: 'https://vault.example.com' # safe-default: non-secret cluster address
- name: VAULT_ROLE_ID
valueFrom:
secretKeyRef: