TAK-OS Ingress annotation reference

Set these annotations on Ingress or HTTPRoute metadata.annotations. Quote boolean and numeric values because Kubernetes annotation values are strings. Annotations apply to all routes generated from that object.

Annotation aliases

For the routing and authentication suffixes below, the first non-empty value wins in this order:

ingress.tak-os.org/<suffix>
nginx.ingress.kubernetes.io/<suffix>
ingress.kubernetes.io/<suffix>

For example, ingress.tak-os.org/backend-protocol overrides nginx.ingress.kubernetes.io/backend-protocol. This is a defined set of aliases, not general support for ingress-nginx annotations. OAuth uses the separate key k8s.tak-os.com/oauth2-secret, and certificate selection uses the cert-manager keys listed below.

Boolean values accept true/false, on/off, yes/no, and 1/0, ignoring case. Unrecognized boolean values fall back to the feature default.

Backend and TLS settings

Use the prefix ingress.tak-os.org/ with these suffixes:

Suffix	Default	Behavior
`backend-protocol`	`http`	`https` enables TLS to the Service; the value is case insensitive
`backend-keepalive`	`true`	`false` disables reuse of ordinary backend HTTP connections; WebSocket tunnels are independent
`proxy-ssl-verify`	`true`	Validate backend TLS certificates; `false` skips verification for HTTPS backends
`ssl-redirect`	Ingress: enabled for a matching TLS host; HTTPRoute: `false`	Redirect HTTP to the same host, path, and query over HTTPS with status 308
`proxy-connect-timeout`	`300`	Backend TCP connection timeout in whole seconds
`proxy-read-timeout`	`300`	Idle timeout between backend response reads, in whole seconds
`proxy-send-timeout`	`300`	Idle timeout between request writes to the backend, in whole seconds

An explicit timeout of "0" disables that timeout. Invalid or negative timeout values use the default. Read and send timeouts also apply to WebSocket tunnels; active traffic does not consume an absolute stream lifetime. Backend connection reuse normally retires idle connections after 4 seconds.

The backend port comes from the Service reference. Setting backend-protocol does not change the referenced port. Client HTTPS termination and backend TLS are independent settings.

CORS settings

Use the prefix ingress.tak-os.org/:

Suffix	Default
`enable-cors`	`false`
`cors-allow-origin`	`*`
`cors-allow-methods`	`GET, PUT, POST, DELETE, PATCH, OPTIONS`
`cors-allow-headers`	`DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization`
`cors-allow-credentials`	`true`
`cors-max-age`	`1728000`

With CORS enabled, the proxy adds the configured response headers and handles preflight OPTIONS requests with 204 before authentication or rate limiting. Set a specific allowed origin when credentials are enabled; browsers do not allow credentialed requests with wildcard Access-Control-Allow-Origin. Origin, method, header, and max-age values are emitted as configured.

Rate limits

Use the prefix ingress.tak-os.org/:

Suffix	Default	Behavior
`limit-rps`	disabled	Positive integer requests per second; takes precedence over `limit-rpm` when valid
`limit-rpm`	disabled	Positive integer requests per minute, converted to requests per second
`limit-burst-multiplier`	`5`	Positive integer multiplier for the per-second rate to obtain burst capacity
`limit-whitelist`	empty	Comma-separated client IPs or CIDRs exempt from the route limit

Each process maintains its own token buckets per route and TCP peer IP. An exhausted bucket returns 429 with Retry-After: 1. Authentication attempt and OAuth callback throttles are separate built-in controls and are not disabled by these route annotations. Failed authentication attempts can receive a longer Retry-After due to backoff.

Authentication settings

Annotation	Default	Behavior
`ingress.tak-os.org/auth-url`	unset	External authentication check URL; 2xx permits access
`ingress.tak-os.org/auth-signin`	unset	Redirect destination after external auth returns 401/403
`ingress.tak-os.org/auth-type`	unset	Set `basic` to enable Basic authentication with `auth-secret`
`ingress.tak-os.org/auth-secret`	unset	Basic authentication Secret name in the route namespace
`ingress.tak-os.org/auth-secret-type`	`auth-file`	`auth-file` or `auth-map` Secret format
`ingress.tak-os.org/auth-realm`	`Authentication Required`	Basic authentication challenge realm
`k8s.tak-os.com/oauth2-secret`	unset	Built-in OAuth2/OIDC configuration Secret name in the route namespace

The auth-* settings accept the aliases described above; the OAuth key does not. To activate Basic authentication, set both auth-type: basic and auth-secret. When multiple mechanisms are configured, the proxy selects OAuth, then external authentication, then Basic authentication. A load failure for a selected Basic or OAuth configuration returns 501 rather than allowing access.

Authentication Secrets

Basic authentication Secret

For the default auth-file format, Secret data key auth holds an htpasswd file. See the password prompt example. Bcrypt and other formats supported by the bundled htpasswd library are accepted.

With auth-secret-type: auth-map, each Secret data key is a username and its value is the plaintext password. For example:

apiVersion: v1
kind: Secret
metadata:
  name: app-basic-auth
  namespace: apps
type: Opaque
stringData:
  alice: REPLACE_WITH_PASSWORD

Use HTTPS for Basic authentication. Treat either Secret format as credentials; Kubernetes base64 encoding is not encryption.

OAuth configuration Secret

Create this Secret in the Ingress or HTTPRoute namespace. Replace the client credentials and jwtSecret before applying. Generate a signing key with openssl rand -base64 32 and place its output directly in the stringData jwtSecret value; the controller decodes it to 32 bytes.

apiVersion: v1
kind: Secret
metadata:
  name: app-oidc
  namespace: apps
type: Opaque
stringData:
  clientID: REPLACE_WITH_CLIENT_ID
  clientSecret: REPLACE_WITH_CLIENT_SECRET
  jwtSecret: REPLACE_WITH_BASE64_ENCODED_32_BYTE_KEY
  discoveryURL: https://identity.example.com/realms/apps/.well-known/openid-configuration
  sessionTTL: 1h

Secret key	Requirement or default
`clientID`	Required OAuth client ID
`clientSecret`	Required unless `publicClient` is `true`
`jwtSecret`	Required signing key, exactly 32 bytes after decoding; base64 is preferred; values that are not valid base64 are treated as raw bytes
`discoveryURL`	Required unless all of `authURL`, `tokenURL`, and `jwksURL` are supplied; accepts the provider discovery URL or issuer base URL
`publicClient`	Default `false`; `true` enables public-client mode using PKCE
`authURL`, `tokenURL`, `jwksURL`	Explicit authorization, token, and JWKS endpoints; all three select explicit endpoint configuration
`issuer`	Expected issuer with explicit endpoints; discovery configuration takes its issuer from provider metadata
`userinfoURL`	Needed for flows without an ID token to obtain identity claims
`introspectionURL`	Opaque bearer-token validation endpoint
`scopes`	Space- or comma-separated values; default `openid email profile`
`sessionTTL`	Go duration string; default `1h`
`cookieName`	Default `tak-os-auth`; HTTPS cookies without a domain use a `__Host-` prefix
`cookieDomain`	Default empty, for host-only cookies
`rolesClaim`	Default `roles`
`emailClaim`	Default `email`
`nameClaim`	Default `name`
`audience`	Expected token audience override; otherwise validation uses `clientID`

Configure issuer with explicit endpoints to enforce issuer checks. Identity provider requests use CA validation and a 10-second HTTP client timeout. Use the same signing key and compatible cookie settings only across applications meant to share trust. Rotating the key invalidates existing sessions.

The built-in endpoints are /_tak/oauth2/callback and /_tak/oauth2/logout. Register the full callback URI at the provider. These paths are reserved by the proxy and should not be used for application endpoints.

Certificate issuer selection

These keys apply to automatic Certificate creation for Ingress TLS blocks that omit secretName; they do not enable Gateway certificate provisioning.

Annotation	Behavior
`cert-manager.io/cluster-issuer`	Select a cluster-scoped ClusterIssuer; takes precedence over `issuer`
`cert-manager.io/issuer`	Select an Issuer in the Ingress namespace

With neither key, TAK-OS uses ClusterIssuer letsencrypt-staging. See the TLS workflow and administrator guidance.