Policy type reference

This reference describes the fields and merging behavior for each Policy type.

AccessControl

The access control policy configures NGINX to deny or allow requests from clients with the specified IP addresses or subnets.

For example, the following policy allows access for clients from the subnet 10.0.0.0/8 and denies access for any other clients:

accessControl:
  allow:
  - 10.0.0.0/8

In contrast, the following policy does the opposite. It denies access for clients from 10.0.0.0/8 and allows access for any other clients:

accessControl:
  deny:
  - 10.0.0.0/8

This feature uses the NGINX ngx_http_access_module. The NGINX Ingress Controller access control policy supports either allow rules or deny rules, but not both, unlike the module itself.

AccessControl merging behavior

A VirtualServer or VirtualServerRoute can reference multiple access control policies. For example, this configuration references two policies, each with a configured allow list:

policies:
- name: allow-policy-one
- name: allow-policy-two

When a resource references more than one access control policy, NGINX Ingress Controller merges the contents into a single allow list or a single deny list.

NGINX Ingress Controller doesn’t support referencing both allow and deny policies together, as shown in the following example. If a resource references both allow and deny lists, NGINX Ingress Controller uses only the allow list policies.

policies:
- name: deny-policy
- name: allow-policy-one
- name: allow-policy-two

RateLimit

The rate limit policy configures NGINX to limit the processing rate of requests.

For example, the following policy limits all subsequent requests from a single IP address once the rate exceeds 10 requests per second:

rateLimit:
  rate: 10r/s
  zoneSize: 10M
  key: ${binary_remote_addr}

This feature uses the NGINX ngx_http_limit_req_module.

When you turn on the zone sync feature with NGINX Plus, NGINX Ingress Controller synchronizes the rate limiting zone across all replicas in the cluster. This means all replicas know about requests that other replicas in the cluster have already rate limited.

For each policy referenced in a VirtualServer or its VirtualServerRoutes, NGINX Ingress Controller generates a single rate limiting zone defined by the limit_req_zone directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller generates two different rate limiting zones, one zone per VirtualServer.

RateLimit merging behavior

A VirtualServer or VirtualServerRoute can reference multiple rate limit policies. For example, this configuration references two policies:

policies:
- name: rate-limit-policy-one
- name: rate-limit-policy-two

When a resource references more than one rate limit policy, NGINX Ingress Controller configures NGINX to use all referenced rate limits. When you define multiple policies, each additional policy inherits the dryRun, logLevel, and rejectCode parameters from the first policy referenced (rate-limit-policy-one, in the example above).

RateLimit.Condition

RateLimit.Condition defines a condition for a rate limit policy. For example:

condition:
  jwt:
    claim: user_details.level
    match: premium
  default: true

Conditions (jwt or variables) are optional, but each policy can only have one. If conditions are used and a request doesn’t match any of them, NGINX Ingress Controller applies the default policy, if one is defined. Otherwise, if no default is set, the request isn’t rate limited.

Combine the rate limit policy with condition with one or more rate limit policies. For example, you can combine multiple rate limit policies that use RateLimit.Condition.JWT to apply different tiers of rate limit based on the value of a JWT claim. For a practical example of tiered rate limiting by the value of a JWT claim, see the example in the GitHub repository.

RateLimit.Condition.JWT

This feature is only available with NGINX Plus.

RateLimit.Condition.JWT defines a condition for a rate limit by JWT claim. For example, the following condition applies a rate limit policy only to requests with a JWT claim user_details.level with a value premium:

jwt:
  claim: user_details.level
  match: premium

The rate limit policy applies only to requests that contain a JWT with the specified claim and value. For example, the following JWT payload matches the JWT condition:

{
  "user_details": {
    "level": "premium"
  },
  "sub": "client1"
}

RateLimit.Condition.Variables

RateLimit.Condition.Variables defines a condition for a rate limit by NGINX variable. The following example defines a condition for a rate limit policy that applies only to requests with the request method with a value GET:

variables:
  - name: $request_method
    match: GET

NGINX Ingress Controller currently supports only one variable at a time.

APIKey

The API Key auth policy configures NGINX to authorize client requests based on the presence of a valid API Key in a header or query parameter specified in the policy.

This feature uses the NGINX ngx_http_auth_request_module and NGINX JavaScript (NJS).

Subrequests may not function as expected and may cause issues when the APIKey policy and a WAF policy are applied together on the same route.

The policy stores API keys securely using SHA-256 hashing. When a client sends an API Key, NJS hashes it and compares it to the hashed API Key in the NGINX configuration.

If the hashed keys match, the NJS subrequest issues a 204 No Content response to the auth_request directive, indicating successful authorization. If the client doesn’t provide an API Key in the specified header or query parameter, NGINX returns a 401 Unauthorized response. If the client presents an invalid key in the expected header or query parameter, NGINX returns a 403 Forbidden response and denies access.

You can use the errorPages property on a route to change the default behavior for 401 or 403 errors.

The policy requires at least one header or query parameter.

The policy below configures NGINX Ingress Controller to require the API Key password in the header "my-header".

apiKey:
    suppliedIn:
      header:
      - "my-header"
    clientSecret: api-key-secret

apiVersion: v1
kind: Secret
metadata:
  name: api-key-secret
type: nginx.org/apikey
data:
    client1: cGFzc3dvcmQ= # password

Important

An APIKey policy must include at least one of the suppliedIn.header or suppliedIn.query parameters. You can also include both.

APIKey merging behavior

A VirtualServer or VirtualServerRoute can be associated with only one API Key policy per route or subroute. You can replace an API Key policy from a higher level with a different policy defined on a more specific route.

For example, a VirtualServer can implement different API Key policies at various levels. In the following configuration, the server-wide api-key-policy-server applies to /backend1 for authorization, because that route has no more specific policy. /backend2 uses api-key-policy-route, defined at the route level.

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: virtual-server
spec:
  host: virtual-server.example.com
  policies:
  - name: api-key-policy-server
  upstreams:
  - name: backend2
    service: backend2-svc
    port: 80
  - name: backend1
    service: backend1-svc
    port: 80
  routes:
  - path: /backend1
    action:
      pass: backend1
  - path: /backend2
    action:
      pass: backend2
    policies:
      - name: api-key-policy-route

BasicAuth

The basic auth policy configures NGINX to authenticate client requests using the HTTP Basic authentication scheme.

For example, the following policy rejects all requests that don’t include a valid username and password combination in the HTTP header Authentication:

basicAuth:
  secret: htpasswd-secret
  realm: "My API"

This feature uses the NGINX ngx_http_auth_basic_module.

BasicAuth merging behavior

A VirtualServer or VirtualServerRoute can reference multiple basic auth policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: basic-auth-policy-one
- name: basic-auth-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, basic-auth-policy-one, and ignores basic-auth-policy-two.

JWT using a local Kubernetes secret

This feature is only available with NGINX Plus.

The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens.

The following example policy rejects all requests that don’t include a valid JWT in the HTTP header token:

jwt:
  secret: jwk-secret
  realm: "My API"
  token: $http_token

You can pass the JWT claims and JOSE headers to the upstream servers. For example:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: user
        value: ${jwt_claim_user}
      - name: alg
        value: ${jwt_header_alg}

This example uses the requestHeaders of Action.Proxy to set the values of two headers that NGINX passes to the upstream servers.

The value of the ${jwt_claim_user} variable is the user claim of a JWT. For other claims, use ${jwt_claim_name}, where name is the name of the claim. Nested claims and claims that include a period (.) aren’t supported. Similarly, use ${jwt_header_name}, where name is the name of a header. This example uses the alg header.

This feature uses the NGINX Plus ngx_http_auth_jwt_module.

JWT merging behavior

A VirtualServer or VirtualServerRoute can reference multiple JWT policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: jwt-policy-one
- name: jwt-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, jwt-policy-one, and ignores jwt-policy-two.

JWT using JWKS from a remote location

This feature is only available with NGINX Plus.

The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. You can import the JWKS keys for a JWT policy from a URL, such as a remote server or an identity provider, so you don’t have to copy and update them on the Ingress Controller pod.

The following example policy rejects all requests that don’t include a valid JWT in the HTTP header fetched from the identity provider:

jwt:
  realm: MyProductAPI
  token: $http_token
  jwksURI: <uri_to_remote_server_or_idp>
  keyCache: 1h

This feature uses the NGINX Plus directive auth_jwt_key_request, part of ngx_http_auth_jwt_module.

Subrequests may not function as expected and may cause issues when fetching JWKs from a remote URI (jwksURI) in a JWT policy and a WAF policy are applied together on the same route.

NGINX Ingress Controller turns on content caching by default for each JWT policy, with a default time of 12 hours. This improves resiliency by letting NGINX Ingress Controller retrieve the JWKS (JSON Web Key Set) from the cache even after it expires.

JWT using JWKS merging behavior

This behavior is similar to using a local Kubernetes secret. A VirtualServer or VirtualServerRoute can reference multiple JWT policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: jwt-policy-one
- name: jwt-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, jwt-policy-one, and ignores jwt-policy-two.

IngressMTLS

The IngressMTLS policy configures client certificate verification.

For example, the following policy verifies a client certificate using the CA certificate specified in ingress-mtls-secret:

ingressMTLS:
  clientCertSecret: ingress-mtls-secret
  verifyClient: "on"
  verifyDepth: 1

Below is an example of ingress-mtls-secret using the secret type nginx.org/ca:

kind: Secret
metadata:
  name: ingress-mtls-secret
apiVersion: v1
type: nginx.org/ca
data:
  ca.crt: <base64encoded-certificate>

A VirtualServer that references an IngressMTLS policy must:

• Turn on TLS termination.
• Reference the policy in the VirtualServer spec. You can’t reference an IngressMTLS policy in a route or in a VirtualServerRoute subroute.

A Kubernetes Ingress that references an IngressMTLS policy must:

• Turn on TLS termination.
• Reference the policy on the Ingress. For mergeable Ingresses, reference the policy on the master Ingress only. You can’t reference an IngressMTLS policy on a minion Ingress.

If a resource doesn’t meet these conditions, NGINX sends the 500 status code to clients.

You can pass the client certificate details, including the certificate, to the upstream servers. For example:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: client-cert-subj-dn
        value: ${ssl_client_s_dn} # subject DN
      - name: client-cert
        value: ${ssl_client_escaped_cert} # client certificate in the PEM format (urlencoded)

This example uses the requestHeaders of Action.Proxy to set the values of the two headers that NGINX passes to the upstream servers. See the list of embedded variables that ngx_http_ssl_module supports, which you can use to pass the client certificate details.

This feature uses the NGINX ngx_http_ssl_module.

Configure a certificate revocation list

The IngressMTLS policy supports configuring a certificate revocation list (CRL) for your policy, in one of two ways.

You can use only one of these configuration options at a time.

1. Add the ca.crl field to the nginx.org/ca secret type, which accepts a base64 encoded certificate revocation list.

   Example:

   Copy

   kind: Secret
   metadata:
     name: ingress-mtls-secret
   apiVersion: v1
   type: nginx.org/ca
   data:
     ca.crt: <base64encoded-certificate>
     ca.crl: <base64encoded-crl>

2. Add the crlFileName field to your IngressMTLS policy spec with the name of the CRL file.

   Use this configuration option only when your CRL is larger than 1 MiB. Otherwise, use the nginx.org/ca secret type to manage your CRL.

   Example:

   Copy

   apiVersion: k8s.nginx.org/v1
   kind: Policy
   metadata:
     name: ingress-mtls-policy
   spec:
   ingressMTLS:
       clientCertSecret: ingress-mtls-secret
       crlFileName: webapp.crl
       verifyClient: "on"
       verifyDepth: 1

Important

When you configure a CRL with the ingressMTLS.crlFileName field, keep this additional context in mind:

• NGINX Ingress Controller expects the CRL, in this case webapp.crl, to be in /etc/nginx/secrets. Add a volume mount to the NGINX Ingress Controller deployment to add your CRL to /etc/nginx/secrets.
• When you update the content of your CRL, for example after you revoke a new certificate, NGINX needs to reload to pick up the latest changes. Depending on your environment, this may require you to update the name of your CRL and apply this update to your ingress-mtls.yaml policy so NGINX picks up the latest CRL.

See the Kubernetes documentation on volumes to find the best implementation for your environment.

IngressMTLS merging behavior

A VirtualServer or an Ingress can reference only a single IngressMTLS policy, and NGINX Ingress Controller ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: ingress-mtls-policy-one
- name: ingress-mtls-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, ingress-mtls-policy-one, and ignores ingress-mtls-policy-two.

EgressMTLS

The EgressMTLS policy configures upstream authentication and certificate verification.

For example, the following policy uses egress-mtls-secret to authenticate with the upstream application and egress-trusted-ca-secret to verify the certificate of the application:

egressMTLS:
  tlsSecret: egress-mtls-secret
  trustedCertSecret: egress-trusted-ca-secret
  verifyServer: on
  verifyDepth: 2

This feature uses the NGINX ngx_http_proxy_module.

EgressMTLS merging behavior

A VirtualServer or VirtualServerRoute can reference multiple EgressMTLS policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: egress-mtls-policy-one
- name: egress-mtls-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, egress-mtls-policy-one, and ignores egress-mtls-policy-two.

ExternalAuth

Subrequests may not function as expected and may cause issues when the ExternalAuth policy and a WAF policy are applied together on the same route.

The ExternalAuth policy configures NGINX to authenticate client requests using an external authentication server. You can use this policy with services such as oauth2-proxy or any custom authentication service that supports the auth_request pattern.

When a client sends a request, NGINX makes an internal subrequest to the external authentication service. If the service returns a 2xx response, NGINX forwards the original request to the upstream. If it returns 401 or 403, NGINX denies access. If you configure authSigninURI, NGINX redirects unauthenticated clients to a sign-in page.

For example, the following policy configures external authentication using an HTTP Basic Auth backend service:

externalAuth:
  authURI: "/auth"
  authServiceName: "default/basic-auth-svc"

The following policy uses OAuth2 Proxy with a sign-in redirect:

externalAuth:
  authURI: "/oauth2/auth"
  authSigninURI: "/oauth2/signin"
  authServiceName: "default/oauth2-proxy-svc"
  sslEnabled: true
  sslVerify: true
  sslVerifyDepth: 2
  sniName: "external-auth-tls"
  trustedCertSecret: "external-auth-ca-secret"

An example ExternalAuth policy for VirtualServer resources is available in the GitHub repository for basic auth and OAuth2 with basic auth. Examples for Ingress resources are also available for basic auth and OAuth2 with basic auth using mergeable Ingresses.

ExternalAuth merging behavior

A VirtualServer, VirtualServerRoute, Ingress, or mergeable Ingress can reference only one ExternalAuth policy per route, and NGINX Ingress Controller ignores every subsequent reference. This means you can’t combine different types of external authentication on the same route. For example, you can’t apply both an OAuth2 policy and a basic auth policy to the same route.

policies:
- name: external-auth-policy-one
- name: external-auth-policy-two

NGINX Ingress Controller uses the configuration from the first policy reference, external-auth-policy-one, and ignores external-auth-policy-two. To use different authentication methods on different routes, apply each ExternalAuth policy to its own route.

OAuth2 sign-in redirect location

When you configure authSigninURI, NGINX Ingress Controller generates an internal location block to handle sign-in redirects, based on authSigninRedirectBasePath, which defaults to /oauth2. Because NGINX location blocks are defined at the server level, only one sign-in redirect location can exist per host. If multiple routes on the same VirtualServer, VirtualServerRoute, Ingress, or mergeable Ingress host reference ExternalAuth policies with authSigninURI, NGINX Ingress Controller uses the sign-in redirect configuration from the first policy it processes. All routes that use authSigninURI share that single redirect location.

This means all routes on the same host that require OAuth2 sign-in must use the same OAuth2 Proxy backend for the redirect flow. If you need different OAuth2 providers for different routes, use separate hosts.

OIDC

This feature is turned off by default. To turn it on, set the enable-oidc command-line argument of NGINX Ingress Controller.

Subrequests may not function as expected and may cause issues when the OIDC policy and a WAF policy are applied together on the same route.

The OIDC policy configures NGINX Plus as a relying party for OpenID Connect authentication.

For example, the following policy uses the client ID nginx-plus and the client secret oidc-secret to authenticate with the OpenID Connect provider https://idp.example.com:

spec:
  oidc:
    clientID: nginx-plus
    clientSecret: oidc-secret
    authEndpoint: https://idp.example.com/openid-connect/auth
    tokenEndpoint: https://idp.example.com/openid-connect/token
    jwksURI: https://idp.example.com/openid-connect/certs
    endSessionEndpoint: https://idp.example.com/openid-connect/logout
    postLogoutRedirectURI: /
    accessTokenEnable: true
    pkceEnable: false

NGINX Plus passes the ID of an authenticated user to the backend in the HTTP header username.

This feature uses the reference implementation of NGINX Plus as a relying party for OpenID Connect authentication.

Prerequisites

To use OIDC, turn on zone synchronization. If you don’t set up zone synchronization, NGINX Plus fails to reload.

You also need to configure a resolver, which NGINX Plus uses to resolve the IDP authorization endpoint. You can find an example configuration in the GitHub repository.

Warning

The configuration in the example doesn’t turn on TLS, so synchronization between replicas happens in clear text. This can expose tokens.

Limitations

The OIDC policy defines a few internal locations that you can’t customize: /_jwks_uri, /_token, /_refresh, /_id_token_validation, /logout. In addition, /_codexch is the default value for the redirect URI, and /_logout is the default value for the post logout redirect URI. You can customize both. Specifying one of these locations as a route in the VirtualServer or VirtualServerRoute causes a collision, and NGINX Plus fails to reload.

Only one OIDC policy can be referenced in a VirtualServer and its VirtualServerRoutes. However, you can still apply the same policy to different routes in the VirtualServer and VirtualServerRoutes.

OIDC merging behavior

A VirtualServer or VirtualServerRoute can reference only a single OIDC policy, and NGINX Ingress Controller ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: oidc-policy-one
- name: oidc-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, oidc-policy-one, and ignores oidc-policy-two.

OIDCNative

This feature is only available with NGINX Plus and requires the enable-oidc command-line argument.

The OIDCNative policy configures NGINX Plus as a relying party for OpenID Connect authentication using the built-in ngx_http_oidc_module. Unlike the NJS-based oidc policy, the native implementation handles the entire OIDC flow within the NGINX core, including token exchange, session management, and front-channel logout.

For example, the following policy authenticates users against a Keycloak identity provider:

spec:
  oidcNative:
    issuer: https://idp.example.com/realms/master
    clientID: nginx-plus
    clientSecret: oidc-secret
    scope: openid profile email
    logoutURI: /logout
    postLogoutRedirectURI: /_logout

This feature uses the NGINX ngx_http_oidc_module.

Prerequisites

Configure a resolver so NGINX Plus can resolve the identity provider’s hostname for discovery and token exchange. Add the following to your ConfigMap:

data:
  resolver-addresses: "kube-dns.kube-system.svc.cluster.local"

When you use the zone synchronization feature, NGINX Ingress Controller synchronizes OIDC session data across all replicas. Put the ConfigMap in its final state, with or without zone sync turned on, before you create the OIDCNative policy and its referencing VirtualServer or Ingress. NGINX declares the native module’s session zone with sync only when zone sync is turned on, and NGINX can’t change the sync flag of an existing shared memory zone across a reload.

Differences from the NJS-based OIDC policy

Important

oidc and oidcNative are mutually exclusive. A Policy resource must define only one of them. If you set both, NGINX Ingress Controller marks the Policy as Invalid.

On a VirtualServer, if you apply both an oidc policy and an oidcNative policy to the same route, that route gets a Warning status and returns a static 500 response.

OIDCNative on Ingress

When using OIDCNative with Ingress resources, reference the policy through the nginx.com/policies annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: webapp
  annotations:
    nginx.com/policies: "oidc-native-policy"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - webapp.example.com
      secretName: tls-secret
  rules:
    - host: webapp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: webapp-svc
                port:
                  number: 80

For mergeable Ingress, you can apply the policy at the master level (server-wide) or on individual minions (location-level):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: webapp-master
  annotations:
    nginx.org/mergeable-ingress-type: "master"
    nginx.com/policies: "oidc-native-policy"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - webapp.example.com
      secretName: tls-secret
  rules:
    - host: webapp.example.com

Important

On Ingress, reference OIDCNative policies through nginx.com/policies, not nginx.org/policies.

Ingress resources don’t support the NJS-based oidc policy.

OIDCNative merging behavior

A VirtualServer, VirtualServerRoute, or Ingress can reference only a single OIDCNative policy per context, and NGINX Ingress Controller ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: oidc-policy-one
- name: oidc-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, oidc-policy-one, and ignores oidc-policy-two.

Multiple OIDCNative policies can coexist on the same host when applied to different routes (VirtualServer) or different mergeable Ingress minions. Each generates a unique oidc_provider block with its own session store.

If you override those paths and two policies on the same host claim the same one, for example by setting redirectURI to the same value, NGINX Ingress Controller rejects the conflicting policy and that route or minion returns a 500 response. postLogoutRedirectURI is the exception: providers may share it, and only one location is generated.

Cache

The cache policy configures proxy caching, which improves performance by storing and serving cached responses to clients instead of proxying every request to upstream servers.

Subrequests may not function as expected and may cause issues when cacheBackgroundUpdate in a Cache policy and a WAF policy are applied together on the same route.

For example, the following policy creates a cache zone named "mycache" with 10 MB of memory allocated, and caches all GET response codes for 30 seconds:

cache:
  cacheZoneName: "mycache"
  cacheZoneSize: "10m"
  allowedCodes: ["any"]
  allowedMethods: ["GET"]
  time: "30s"

Here’s an example with more specific configuration:

cache:
  cacheZoneName: "mycache"
  cacheZoneSize: "100m"
  allowedCodes: [200, 301, 302]
  allowedMethods: ["GET", "POST"]
  time: "5m"
  levels: "1:2"
  overrideUpstreamCache: true
  inactive: "60m"
  useTempPath: false
  maxSize: "10g"
  minFree: "1g"
  manager:
    files: 100
    sleep: "50ms"
    threshold: "200ms"
  cacheKey: "$scheme$host$request_uri"
  cacheUseStale: [ "error", "timeout", "updating", "http_500" ]
  cacheRevalidate: true
  cacheBackgroundUpdate: true
  cacheMinUses: 1
  lock:
    enable: true
    timeout: "5s"
    age: "30s"
  conditions:
    noCache: [ "$cookie_nocache", "$arg_nocache" ]
    bypass: [ "$http_authorization" ]

This feature uses the NGINX ngx_http_proxy_module proxy_cache_path and related directives.

Cache merging behavior

A VirtualServer or VirtualServerRoute can reference multiple cache policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference.

CORS

The CORS policy configures Cross-Origin Resource Sharing (CORS) headers.

This feature uses the NGINX add_header directive.

Below is an example of a CORS policy configuring all the available options:

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: cors-policy
spec:
  cors:
    allowOrigin:
      - "https://test.example.com"
      - "https://app.example.com"
      - "https://admin.example.com"

    allowMethods:
      - "GET"
      - "POST"
      - "PUT"

    allowHeaders:
      - "Content-Type"
      - "Authorization"
      - "X-Requested-With"
      - "X-API-Key"

    allowCredentials: true

    exposeHeaders:
      - "X-Total-Count"
      - "X-Page-Size"
      - "X-RateLimit-Remaining"
      - "X-RateLimit-Reset"

    maxAge: 3600 
    

If CORS is currently configured in deployments using snippets or responseHeaders.add, migrate those settings to the CORS policy and remove the duplicate configuration.

CORS merging behavior

A VirtualServer or VirtualServerRoute can reference multiple CORS policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference.

WAF

This feature uses the NGINX Plus F5 WAF for NGINX module.

Policies that rely on NGINX subrequests (such as ExternalAuth, APIKey, JWT with remote JWKS fetching, OIDC, or Cache with cacheBackgroundUpdate) and a WAF policy may not function as expected and may cause issues when applied together on the same route.

The WAF policy configures NGINX Plus to secure client requests using F5 WAF for NGINX policies.

For example, the following policy turns on the referenced APPolicy. You can configure multiple APLogConfs with log destinations:

waf:
  enable: true
  apPolicy: "default/dataguard-alarm"
  securityLogs:
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc.default:514"
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc-secondary.default:514"

The field waf.securityLog is deprecated and will be removed in a future release. NGINX Ingress Controller ignores it if waf.securityLogs is populated.

WAF.SecurityLogs

WAF.ApBundleSource

The apBundleSource object configures how NGINX Ingress Controller fetches a pre-compiled WAF bundle from a remote source. waf.securityLogs[].apLogBundleSource uses the same fields. NGINX Ingress Controller supports three source types:

• N1C (NGINX One Console) – fetch policies compiled and managed through NGINX One Console. See policy docs.
• NIM (NGINX Instance Manager) – fetch policies compiled and managed through NGINX Instance Manager. See bundle docs.
• HTTPS – fetch compiled .tgz bundles from any HTTPS server or endpoint.

For details and examples, see Connect F5 WAF for NGINX to bundle sources.

For example, see the snippets below:

for NGINX Instance Manager:

spec:
  waf:
    enable: true
    apBundleSource:
      type: NIM
      url: "https://<nim_host>"
      name: "<policy_name>"
      secret: "nim-credentials"
      enablePolling: true
      pollInterval: "5m"
    securityLogs:
    - enable: true
      apLogBundleSource:
        type: NIM
        url: "https://<nim_host>"
        name: "<log_profile_name>"
        secret: "nim-credentials"
        enablePolling: true
        pollInterval: "5m"
      logDest: "stderr"

for NGINX One Console:

spec:
  waf:
    enable: true
    apBundleSource:
      type: N1C
      url: "https://<tenant>.console.ves.volterra.io"
      name: "<policy_name>"
      namespace: "default"
      secret: "n1c-credentials"
      enablePolling: true
      pollInterval: "5m"
    securityLogs:
    - enable: true
      apLogBundleSource:
        type: N1C
        url: "https://<tenant>.console.ves.volterra.io"
        name: "secops_dashboard"
        namespace: "default"
        secret: "n1c-credentials"
        enablePolling: true
        pollInterval: "5m"
      logDest: "stderr"

For HTTPS:

spec:
  waf:
    enable: true
    apBundleSource:
      url: "https://bundle-server.default.svc.cluster.local/bundles/attack-signatures-blocking.tgz"
      secret: "bundle-client-tls"
      trustedCertSecret: "bundle-server-ca"
      enablePolling: true
      pollInterval: "5m"
    securityLogs:
    - enable: true
      apLogBundleSource:
        url: "https://bundle-server.default.svc.cluster.local/bundles/log-default.tgz"
        secret: "bundle-client-tls"
        trustedCertSecret: "bundle-server-ca"
        enablePolling: true
        pollInterval: "5m"
      logDest: "stderr"

WAF merging behavior

A VirtualServer or VirtualServerRoute can reference multiple WAF policies, but NGINX Ingress Controller applies only the first one. It ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: waf-policy-one
- name: waf-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, waf-policy-one, and ignores waf-policy-two.

HSTS

The HSTS policy sets up HTTP Strict Transport Security. It instructs browsers to enforce HTTPS connections to the host for a specified duration.

For example, the following policy sets an HSTS duration of 30 days and extends the policy to all host subdomains:

hsts:
  maxAge: 2592000
  includeSubDomains: true

When you deploy NGINX Ingress Controller behind a proxy or load balancer that terminates TLS upstream, set behindProxy to true. In this mode, NGINX uses the X-Forwarded-Proto request header to determine whether the connection is HTTPS, instead of checking the $https variable directly:

hsts:
  maxAge: 2592000
  behindProxy: true

A VirtualServer that references an HSTS policy must:

• Use TLS termination, or set behindProxy to true if TLS is terminated upstream.
• Reference the policy in the VirtualServer spec. You can’t reference an HSTS policy in a route or in a VirtualServerRoute subroute.

If a resource doesn’t meet these conditions, NGINX sends status code 500 to clients.

This feature uses the NGINX add_header directive and the ngx_http_ssl_module $https variable.

Important

HSTS instructs browsers to enforce HTTPS for the duration of maxAge. Deleting the policy doesn’t clear the browser’s cached directive, so users may be unable to access the application over HTTP until the cached policy expires.

To remove HSTS safely, first set maxAge to 0 and apply the updated policy. This instructs browsers to expire the cached directive immediately. Once applied, remove the policy reference from the VirtualServer and delete the policy resource.

See the MDN documentation on HSTS expiration for more details.

HSTS merging behavior

A VirtualServer can reference only a single HSTS policy, and NGINX Ingress Controller ignores every subsequent reference. For example, this configuration references two policies:

policies:
- name: hsts-policy-one
- name: hsts-policy-two

In this example, NGINX Ingress Controller uses the configuration from the first policy reference, hsts-policy-one, and ignores hsts-policy-two.

What’s next

Learn how to manage Policy resources with kubectl.