Kubernetes
Authenticate your pod as its service account: bind a trust, project a token with your workspace id as audience, and hand it to penv run.
Your pod authenticates to us as its service account through a projected token. Projection mechanics: Kubernetes service account token projection. To deliver values without penv in the container, use External Secrets Operator.
Trust
Create the trust under Machine Identities, then Connect a Platform (connect a platform). The issuer field differs per cluster:
| Cluster | Connect page |
|---|---|
| Any Kubernetes | Kubernetes |
| Amazon EKS | EKS |
| Google Kubernetes Engine | GKE |
| Azure Kubernetes Service | AKS (keep the issuer's trailing slash) |
| Oracle Container Engine | OKE |
| Trust part | Value |
|---|---|
| Subject | system:serviceaccount:<namespace>:<service-account>, matched exactly |
| Audience | Your workspace id (single-audience rule) |
Your cluster issuer must be reachable from the internet. We fetch its discovery document when the trust binds; an issuer readable only inside the cluster never binds.
Projected token
volumes:
- name: penv-token
projected:
sources:
- serviceAccountToken:
path: token
audience: <ORG_ID> # your workspace id, and no other audience
expirationSeconds: 3600
containers:
- name: api
volumeMounts:
- name: penv-token # required, or no container can read the volume
mountPath: /var/run/secrets/penv
readOnly: trueOn EKS, do not reuse AWS_WEB_IDENTITY_TOKEN_FILE for this trust: its audience is fixed to sts.amazonaws.com. On AKS, AZURE_FEDERATED_TOKEN_FILE has Microsoft's audience. Project a separate token.
Run
PENV_OIDC_TOKEN="$(cat /var/run/secrets/penv/token)" penv run -- node server.jspenv exchanges the token with us for a 15-minute credential; penv run reads once and the child runs indefinitely. Probe and image setup: run in a container.
The console snippet exchanges with curl and ends in penv pull; prefer penv run, which writes nothing to disk.
| Route | penv at runtime | A rotated value reaches the pod |
|---|---|---|
penv run in the container | Yes, one call to us per start | On the next start |
| External Secrets Operator | No | On the operator's refresh interval |
EKS IRSA and Pod Identity
| penv version | IRSA web identity or Pod Identity credential |
|---|---|
| 1.0.0-beta.2 | penv reads it and proves the pod's AWS role, but does not sign your workspace id, so we refuse the exchange. Use the projected token above. |
| 1.0.0-beta.3 and later | penv signs your workspace id and we accept it against an AWS trust. |
AWS trust setup: authenticate an AWS workload.
Setup
Read the cluster issuer (or the OKE discovery key) per the connect page above.
Open Machine Identities, then Connect a Platform, pick the cluster entry, and enter the issuer, namespace, and service account.
Add the projected volume with your workspace id as audience, mounted read only.
Copy penv into the image and set the command to penv run, with PENV_OIDC_TOKEN read from the mounted file.
Roll the deployment and read the pod log. 401 unauthorized means the trust does not name this service account.
Run in a container
Copy penv into your image from ghcr.io/penvhq/penv, pass a credential at run time, handle the per-start read, or ship an encrypted bundle instead.
Serverless functions
Deliver your values to Lambda, Cloud Run, Workers, Vercel, and Deno Deploy with an export sync, or run penv inside Lambda through the layer.