docs: document secret injection settings and add a guide - #2340
Conversation
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Greptile SummaryThis PR adds comprehensive reference and tutorial documentation for file-backed secret injection, rotation, failure handling, and monitoring. The supplied walkthrough currently selects an image that its own validation marker says cannot execute the feature.
Confidence Score: 4/5The PR should not merge until the walkthrough points to a build that contains secret injection or supplies reproducible build instructions for one. The runnable Compose example selects an image explicitly identified by the same change as lacking the feature, causing readers who follow the guide to receive an empty credential instead of the documented injection, rotation, and fail-closed behavior. Files Needing Attention: content/examples/guides/secrets/docker-compose.yaml.md, content/docs/guides/secrets.mdx
|
| Filename | Overview |
|---|---|
| content/examples/guides/secrets/docker-compose.yaml.md | Adds the runnable stack but selects an image that the accompanying validation marker says lacks secret injection. |
| content/docs/guides/secrets.mdx | Adds a detailed walkthrough whose commands depend on an unavailable image, despite documenting the resulting failure mode. |
| content/docs/reference/secrets.mdx | Adds comprehensive configuration, lifecycle, failure, monitoring, and limitation reference material with no independently actionable defect identified. |
| content/docs/reference/metrics.mdx | Documents secret cache and injection metrics consistently with the new reference. |
| content/docs/reference/reference.json | Adds structured Secrets entries whose routes and anchors resolve; service metadata could not be tied to a current observable failure. |
Reviews (1): Last reviewed commit: "docs: opt the secrets guide out of fixtu..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ```yaml title="docker-compose.yaml" | ||
| services: | ||
| pomerium: | ||
| image: pomerium/pomerium:main |
There was a problem hiding this comment.
When readers run the supplied Compose configuration, it selects pomerium/pomerium:main, which the new validation marker explicitly says lacks secret injection; Pomerium therefore ignores secrets and forwards an empty credential instead of demonstrating injection, rotation, metrics, or fail-closed responses. A red consistency test proving the current fixture is broken is: compose = Path("content/examples/guides/secrets/docker-compose.yaml.md").read_text(); skip = Path("content/examples/guides/secrets/validate/SKIP").read_text(); image = re.search(r"^\s*image:\s*(\S+)", compose, re.MULTILINE).group(1); assert f"nor in {image}" not in skip.
Context Used: For every finding, write a red test with proof and... (source)
1 participant
Summary
Documents the
secretsconfiguration block and${secret.ID}injection in per-routeset_request_headers, so a route can inject a credential Pomerium reads from a file instead of one written into the configuration.New reference page
/docs/reference/secrets: reference syntax, the binding table (url,refresh,stale_grace),file://URL rules and the JSON field selector,secrets.defaults, config keys and environment variables, background read and rotation behavior, the fail-closed503matrix, state-change log lines, and configuration errors. The page states what is not supported:file://only, request headers only, no Ingress annotation.New guide
/docs/guides/secrets: a Docker Compose walkthrough that injects a token, rotates it with no reload, and shows the fail-closed path when the credential disappears.Also updated: Headers Settings gains an "Inject Secrets" section and a note that response headers are static text; Metrics gains a
pomerium_secrets_*section;reference.jsongains the new settings so they appear in the reference table.Related
Docs for the secret injection stack in core: pomerium/pomerium#6585
AI disclosure
Claude Code (Opus 5) drafted all of this content and verified it against the implementation branch, then I reviewed it. Verification was run rather than assumed: the feature was built from source and exercised end to end (injection, JSON selector, live rotation, stale-then-503, recovery), metric names were taken from a live
/metricsscrape, the documented configuration errors were reproduced, and the guide's exact commands were run against a Docker Compose stack. A second Claude Code agent adversarially reviewed the docs against the source in two passes; its findings were applied.Checklist