Postgres spiffe authentication use case with Teleport workload identity

[stevenGravy]

Summary

This shows the configuration and operator experience for the Postgres + Teleport Workload Identity for scheduled non-human workloads authenticating to a database via short-lived SPIFFE X.509 certificates. K8s cron jobs are used to show a automated usage from Python and Go clients with short-lived certificates direct to the database. Human users are shown how they can authenticate with spiffe certs as well and connect via Teleport tcp app access or regular db access.

What changed

• New use case
• New POC
• New template
• New integration
• Docs only

How to test

• A available k8s cluster to deploy helm charts to with kubeconfig access and Teleport cluster with editor access
• binaries required: tctl, tsh, kubectl, helm, python3, curl, jq
• make sure your user can issue workload identities as shown in the role example at the top of the README
• Copy the .env.example to .env
• Update the TELEPORT_PROXY_ADDR to the Teleport cluster in .env
• Make sure kubectl has access to a k8s cluster.
• Run ./setup.sh
• This will deploy a postgres db that allows access with a workload identity and database access along with
  k8s cronjobs running every two minutes.
• A set of steps will given with ==> Setup complete. Confirm the deployment is healthy: to test with.

An example success of a database access with the python client using workload identity.

8s-prod     Active   77d
➜  postgres kubectl logs -n postgres-wi-demo-0ekb -l app.kubernetes.io/instance=pg-client-python-0ekb --tail=20
debconf: delaying package configuration, since apt-utils is not installed
Inserted and committed transaction: (207, 'wi-demo-python', Decimal('42.00'), 'Deposit via Teleport Workload Identity (Python)', datetime.datetime(2026, 8, 20, 3, 32, 28, 276241, tzinfo=zoneinfo.ZoneInfo(key='GMT')))
debconf:

Checklist

• README included
• .env.example (no secrets)
• Requested reviews

[github-actions]

📜 This PR is large (3516 changed lines)

This PR exceeds the 1500-line soft limit (additions + deletions, excluding lock files, vendored code, and generated files).

Large PRs are harder to review carefully and take longer to land. Please consider splitting this into smaller, independently reviewable pieces — for example by separating refactors from behaviour changes, or splitting by feature/module.

If the size is unavoidable (e.g. a generated-file update that the excludes missed, or a single atomic change), leave a note explaining why and a reviewer can proceed.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​psycopg@​3.3.5
	golang/​github.com/​jackc/​pgx/​v5@​v5.10.0

View full report

[jeffellin]

There's a lot going on in this PR for what it's demonstrating — a Postgres client authenticating with a Teleport-issued SPIFFE SVID instead of a password. Right now this ships:

• 3 separate Helm charts (postgres-chart, tbot-chart, plus one each for the Go/Python clients), each with the standard _helpers.tpl/NOTES.txt scaffolding
• A vendored binary chart dependency (postgres-chart/charts/postgresql-18.8.11.tgz) checked into git
• Two parallel client implementations (Go and Python) doing the identical thing
• A 619-line setup.sh orchestrating tctl/helm/kubectl end-to-end
• Full tsh vnet/TCP Application Access setup for the human path, plus an optional Database Access path

That's a k8s deployment, three Helm charts, and a vendored dependency tarball to illustrate what's fundamentally: tbot issues an SVID → a client presents it as an mTLS client cert → Postgres authenticates via cert auth. None of the Kubernetes/Helm/vnet machinery is load-bearing to that concept.

Compare to integrations/vault/vault-auth-via-svid: a single notebook + .env.example + requirements.txt, no cluster required. I'd like to see this PR reduced to that shape — a CLI/notebook-driven walkthrough (tsh workload-identity issue-x509 → connect with psql/one client library) that anyone can run locally without provisioning a k8s cluster, Helm, or tsh vnet. clients/cli/README.md already shows this path exists; I'd make that the whole demo and drop the CronJobs, Helm charts, and vnet/App Access setup (or, if the scheduled-workload story is important to keep, split it into a separate, later PR rather than bundling both here).

Given the shape after that trim (no k8s/Helm deployment, just a connector pattern against a third-party product), I'd also move this to integrations/ rather than use-cases/mwi/ — per the repo's own convention (README.md's "What lives here"), integrations/ is for "connectors and adapters to third-party products/platforms," which fits a Postgres-via-SVID example better than use-cases/.

[stevenGravy]

will refactor into another example