Policy specification

Below is an example of a policy that allows access for clients from the subnet 10.0.0.0/8 and denies access for any other clients:

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: allow-localhost
spec:
  accessControl:
    allow:
    - 10.0.0.0/8

NGINX Ingress Controller LTS added Policy resource support for Ingress objects through the nginx.org/policies annotation in v5.4.0.

A policy must include exactly one 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 LTS 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 LTS merges the contents into a single allow list or a single deny list.

NGINX Ingress Controller LTS 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 LTS 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 LTS 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 LTS generates a single rate limiting zone defined by the limit_req_zone directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller LTS 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 LTS 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 LTS 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

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 LTS 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).

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 LTS 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 LTS 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 LTS uses the configuration from the first policy reference, basic-auth-policy-one, and ignores basic-auth-policy-two.

JWT using a local Kubernetes secret

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 LTS 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 LTS uses the configuration from the first policy reference, jwt-policy-one, and ignores jwt-policy-two.

JWT using JWKS from a remote location

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.

NGINX Ingress Controller LTS 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 LTS retrieve the JWKS (JSON Web Key Set) from the cache even after it expires.

JWT 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 LTS 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 LTS 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.

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 LTS expects the CRL, in this case webapp.crl, to be in /etc/nginx/secrets. Add a volume mount to the NGINX Ingress Controller LTS 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 can reference only a single IngressMTLS policy, and NGINX Ingress Controller LTS 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 LTS 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 LTS 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 LTS uses the configuration from the first policy reference, egress-mtls-policy-one, and ignores egress-mtls-policy-two.

OIDC

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

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 LTS 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 LTS uses the configuration from the first policy reference, oidc-policy-one, and ignores oidc-policy-two.

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.

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 LTS 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 LTS applies only the first one. It ignores every subsequent reference.

What’s next

Learn how to manage Policy resources with kubectl.