Kubernetes Deployment Reference

Pomerium-specific parameters should be configured via the ingress.pomerium.io/Pomerium CRD. The default Pomerium deployment is listening to the CRD global, that may be customized via command line parameters.

Pomerium posts updates to the CRD /status:

kubectl describe pomerium

Kubernetes-specific deployment parameters should be added via kustomize to the manifests.

Spec

PomeriumSpec defines Pomerium-specific configuration parameters.

accessLogFields   []string  AccessLogFields sets the access fields to log.
authenticate   object  (authenticate) Authenticate sets authenticate service parameters. If not specified, a Pomerium-hosted authenticate service would be used.
authorizeLogFields   []string  AuthorizeLogFields sets the authorize fields to log.
bearerTokenFormat   string  BearerTokenFormat sets the Bearer Token Format.
caSecrets   []string  CASecret should refer to k8s secrets with key ca.crt containing a CA certificate.
certificates   []string  (namespace/name) Certificates is a list of secrets of type TLS to use Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
circuitBreakerThresholds   object  (circuitBreakerThresholds) CircuitBreakerThresholds sets the circuit breaker thresholds settings.
codecType   string  CodecType sets the Codec Type.
cookie   object  (cookie) Cookie defines Pomerium session cookie options.
dataBroker   object  (dataBroker) DataBroker sets the databroker settings.
dns   object  (dns) DNS sets the dns settings.
downstreamMtls   object  (downstreamMtls) DownstreamMTLS sets the Downstream MTLS Settings.
identityProvider   object  (identityProvider) IdentityProvider configure single-sign-on authentication and user identity details by integrating with your Identity Provider
idpAccessTokenAllowedAudiences   []string  IDPAccessTokenAllowedAudiences specifies the idp access token allowed audiences list.
jwtClaimHeaders   map[string]string JWTClaimHeaders convert claims from the assertion token into HTTP headers and adds them into JWT assertion header. Please make sure to read Getting User Identity guide.
mcpAllowedClientIdDomains   []string  MCPAllowedClientIDDomains specifies the allowed domains for MCP client ID metadata URLs. This is required when MCP is enabled. See MCP Settings.
otel   object  (otel) OTEL sets the OpenTelemetry Tracing.
passIdentityHeaders   boolean  PassIdentityHeaders sets the pass identity headers option.
programmaticRedirectDomains   []string  ProgrammaticRedirectDomains specifies a list of domains that can be used for programmatic redirects.
runtimeFlags   map[string]boolean RuntimeFlags sets the runtime flags to enable/disable certain features.
secrets   string  (namespace/name) Required.  Secrets references a Secret with Pomerium bootstrap parameters. shared_secret - secures inter-Pomerium service communications. cookie_secret - encrypts Pomerium session browser cookie. See also other Cookie parameters. signing_key signs Pomerium JWT assertion header. See Getting the user's identity guide. In a default Pomerium installation manifest, they would be generated via a one-time job and stored in a pomerium/bootstrap Secret. You may re-run the job to rotate the secrets, or update the Secret values manually. When defining the Secret in a manifest, put raw values in stringData so Kubernetes base64-encodes them. Use data only when values are already base64-encoded. Example: stringData.shared_secret and stringData.cookie_secret are raw strings, while data.signing_key is base64-encoded. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
setResponseHeaders   map[string]string SetResponseHeaders specifies a mapping of HTTP Header to be added globally to all managed routes and pomerium's authenticate service. See Set Response Headers
ssh   object  (ssh) SSH sets the ssh settings.
storage   object  (storage) Storage defines persistent storage for sessions and other data. See Storage for details. If no storage is specified, Pomerium would use a transient in-memory storage (not recommended for production).
timeouts   object  (timeouts) Timeout specifies the global timeouts for all routes.
useProxyProtocol   boolean  UseProxyProtocol enables Proxy Protocol support.

authenticate

Authenticate sets authenticate service parameters. If not specified, a Pomerium-hosted authenticate service would be used.

url   string  (uri) Required.  AuthenticateURL is a dedicated domain URL the non-authenticated persons would be referred to. You do not need to create a dedicated Ingress for this virtual route, as it is handled by Pomerium internally. You do need create a secret with corresponding TLS certificate for this route and reference it via certificates. If you use cert-manager with HTTP01 challenge, you may use pomerium ingressClass to solve it. Format: an URI as parsed by Golang net/url.ParseRequestURI.

circuitBreakerThresholds

CircuitBreakerThresholds sets the circuit breaker thresholds settings.

maxConnectionPools   integer  MaxConnectionPools sets the maximum number of connection pools per cluster that Envoy will concurrently support at once. If not specified, the default is unlimited. Set this for clusters which create a large number of connection pools.
maxConnections   integer  MaxConnections sets the maximum number of connections that Envoy will make to the upstream cluster. If not specified, the default is 1024.
maxPendingRequests   integer  MaxPendingRequests sets the maximum number of pending requests that Envoy will allow to the upstream cluster. If not specified, the default is 1024. This limit is applied as a connection limit for non-HTTP traffic.
maxRequests   integer  MaxRequests sets the maximum number of parallel requests that Envoy will make to the upstream cluster. If not specified, the default is 1024. This limit does not apply to non-HTTP traffic.
maxRetries   integer  MaxRetries sets the maximum number of parallel retries that Envoy will allow to the upstream cluster. If not specified, the default is 3.

cookie

Cookie defines Pomerium session cookie options.

domain   string  Domain defaults to the same host that set the cookie. If you specify the domain explicitly, then subdomains would also be included.
expire   string  (duration) Expire sets cookie and Pomerium session expiration time. Once session expires, users would have to re-login. If you change this parameter, existing sessions are not affected. See Session Management (Enterprise) for a more fine-grained session controls. Defaults to 14 hours. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
httpOnly   boolean  HTTPOnly if set to false, the cookie would be accessible from within the JavaScript. Defaults to true.
name   string  Name sets the Pomerium session cookie name. Defaults to _pomerium
sameSite   string  SameSite sets the SameSite option for cookies. Defaults to .

dataBroker

DataBroker sets the databroker settings.

clusterLeaderId   string  ClusterLeaderID defines the cluster leader in a clustered databroker.

dns

DNS sets the dns settings.

failureRefreshRate   string  (duration) FailureRefreshRate is the rate at which DNS lookups are refreshed when requests are failing. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
lookupFamily   string  LookupFamily is the DNS IP address resolution policy.
queryTimeout   string  (duration) QueryTimeout is the amount of time each name server is given to respond to a query on the first try of any given server. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
queryTries   integer  QueryTries is the maximum number of query attempts the resolver will make before giving up. Each attempt may use a different name server.
refreshRate   string  (duration) RefreshRate is the rate at which DNS lookups are refreshed. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
udpMaxQueries   integer  UDPMaxQueries caps the number of UDP based DNS queries on a single port.
useTcp   boolean  UseTCP uses TCP for all DNS queries instead of the default protocol UDP.

downstreamMtls

DownstreamMTLS sets the Downstream MTLS Settings.

ca   string  (byte) CA is a bundle of PEM-encoded X.509 certificates that will be treated as trust anchors when verifying client certificates. Format: base64 encoded binary data.
crl   string  (byte) CRL is a bundle of PEM-encoded certificate revocation lists to be consulted during certificate validation. Format: base64 encoded binary data.
enforcement   string  Enforcement controls Pomerium's behavior when a client does not present a trusted client certificate.
matchSubjectAltNames   object  (matchSubjectAltNames) Match Subject Alt Names can be used to add an additional constraint when validating client certificates.
maxVerifyDepth   integer  MaxVerifyDepth sets a limit on the depth of a certificate chain presented by the client.

file

File specifies file storage options.

path   string  Required.  Path defines the local file system path to store data.

identityProvider

IdentityProvider configure single-sign-on authentication and user identity details by integrating with your Identity Provider

provider   string  Required.  Provider is the short-hand name of a built-in OpenID Connect (oidc) identity provider to be used for authentication. To use a generic provider, set to oidc.
refreshDirectory   object  (refreshDirectory) RefreshDirectory is no longer supported, please see Upgrade Guide.
requestParams   map[string]string RequestParams to be added as part of a sign-in request using OAuth2 code flow.
requestParamsSecret   string  (namespace/name) RequestParamsSecret is a reference to a secret for additional parameters you'd prefer not to provide in plaintext. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
scopes   []string  Scopes Identity provider scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749.
secret   string  (namespace/name) Required.  Secret containing IdP provider specific parameters. and must contain at least client_id and client_secret values. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
serviceAccountFromSecret   string  ServiceAccountFromSecret is no longer supported, see Upgrade Guide.
url   string  (uri) URL is the base path to an identity provider's OpenID connect discovery document. See Identity Providers guides for details. Format: an URI as parsed by Golang net/url.ParseRequestURI.

matchSubjectAltNames

Match Subject Alt Names can be used to add an additional constraint when validating client certificates.

dns   string
email   string
ipAddress   string
uri   string
userPrincipalName   string

otel

OTEL sets the OpenTelemetry Tracing.

bspMaxExportBatchSize   integer  BSPMaxExportBatchSize sets the maximum number of spans to export in a single batch
bspScheduleDelay   string  (duration) BSPScheduleDelay sets interval between two consecutive exports Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
endpoint   string  Required.  An OTLP/gRPC or OTLP/HTTP base endpoint URL with optional port. Example: http://localhost:4318
headers   map[string]string Extra headers
logLevel   string  LogLevel sets the log level for the OpenTelemetry SDK.
protocol   string  Required.  Valid values are "grpc" or "http/protobuf".
resourceAttributes   map[string]string ResourceAttributes sets the additional attributes to be added to the trace.
sampling   string  Sampling sets sampling probability between [0, 1].
timeout   string  (duration) Export request timeout duration Format: a duration string like "22s" as parsed by Golang time.ParseDuration.

postgres

Postgres specifies PostgreSQL database connection parameters

caSecret   string  (namespace/name) CASecret should refer to a k8s secret with key ca.crt containing CA certificate that, if specified, would be used to populate sslrootcert parameter of the connection string. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
secret   string  (namespace/name) Required.  Secret specifies a name of a Secret that must contain connection key. See DSN Format and Parameters. Do not set sslrootcert, sslcert and sslkey via connection string, use tlsSecret and caSecret CRD options instead. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.
tlsSecret   string  (namespace/name) TLSSecret should refer to a k8s secret of type kubernetes.io/tls and allows to specify an optional client certificate and key, by constructing sslcert and sslkey connection string parameter values. Format: reference to Kubernetes resource with namespace prefix: namespace/name format.

refreshDirectory

RefreshDirectory is no longer supported, please see Upgrade Guide.

interval   string  (duration) Required.  interval is the time that pomerium will sync your IDP directory. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
timeout   string  (duration) Required.  timeout is the maximum time allowed each run. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.

ssh

SSH sets the ssh settings.

hostKeySecrets   []string
userCaKeySecret   string

storage

Storage defines persistent storage for sessions and other data. See Storage for details. If no storage is specified, Pomerium would use a transient in-memory storage (not recommended for production).

file   object  (file) File specifies file storage options.
postgres   object  (postgres) Postgres specifies PostgreSQL database connection parameters

timeouts

Timeout specifies the global timeouts for all routes.

idle   string  (duration) Idle specifies the time at which a downstream or upstream connection will be terminated if there are no active streams. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
read   string  (duration) Read specifies the amount of time for the entire request stream to be received from the client. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.
write   string  (duration) Write specifies max stream duration is the maximum time that a stream’s lifetime will span. An HTTP request/response exchange fully consumes a single stream. Therefore, this value must be greater than read_timeout as it covers both request and response time. Format: a duration string like "22s" as parsed by Golang time.ParseDuration.

Status

PomeriumStatus represents configuration and Ingress status.

ingress   map[string] ingress Routes provide per-Ingress status.
settingsStatus   object  (settingsStatus) SettingsStatus represent most recent main configuration reconciliation status.

ingress

ResourceStatus represents the outcome of the latest attempt to reconcile relevant Kubernetes resource with Pomerium.

error   string  Error that prevented latest observedGeneration to be synchronized with Pomerium.
observedAt   string  (date-time) ObservedAt is when last reconciliation attempt was made. Format: a date time string like "2014-12-15T19:30:20.000Z" as defined by date-time in RFC3339.
observedGeneration   integer  ObservedGeneration represents the .metadata.generation that was last presented to Pomerium.
reconciled   boolean  Required.  Reconciled is whether this object generation was successfully synced with pomerium.
warnings   []string  Warnings while parsing the resource.

settingsStatus

SettingsStatus represent most recent main configuration reconciliation status.

error   string  Error that prevented latest observedGeneration to be synchronized with Pomerium.
observedAt   string  (date-time) ObservedAt is when last reconciliation attempt was made. Format: a date time string like "2014-12-15T19:30:20.000Z" as defined by date-time in RFC3339.
observedGeneration   integer  ObservedGeneration represents the .metadata.generation that was last presented to Pomerium.
reconciled   boolean  Required.  Reconciled is whether this object generation was successfully synced with pomerium.
warnings   []string  Warnings while parsing the resource.