From 9bfc11f90ef7a9157cdb3b5cf9f199fed5103b8c Mon Sep 17 00:00:00 2001 From: k8s-ci-robot Date: Thu, 28 Sep 2023 16:03:25 +0000 Subject: [PATCH] Deploy GitHub Pages --- sitemap.xml.gz | Bin 741 -> 741 bytes .../nginx-configuration/annotations/index.html | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/sitemap.xml.gz b/sitemap.xml.gz index b02b5121dc3fa3a6f984ec37e1cdeb7f8fdc19b5..87d3fb15fdf817b4bd93ece29d20042abd735dc9 100644 GIT binary patch delta 15 WcmaFL`jnMTzMF&N)Z&e7_n81J@dcUy delta 15 WcmaFL`jnMTzMF%?c-}^~`%C~SP6Yk{ diff --git a/user-guide/nginx-configuration/annotations/index.html b/user-guide/nginx-configuration/annotations/index.html index dcafb6266..cdb47017b 100644 --- a/user-guide/nginx-configuration/annotations/index.html +++ b/user-guide/nginx-configuration/annotations/index.html @@ -4,7 +4,7 @@

The auth-secret can have two forms:

nginx.ingress.kubernetes.io/auth-realm: "realm string"

Example

Please check the auth example.

Custom NGINX upstream hashing

NGINX supports load balancing by client-server mapping based on consistent hashing for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.

There is a special mode of upstream hashing called subset. In this mode, upstream servers are grouped into subsets, and stickiness works by mapping keys to a subset instead of individual upstream servers. Specific server is chosen uniformly at random from the selected sticky subset. It provides a balance between stickiness and load distribution.

To enable consistent hashing for a backend:

nginx.ingress.kubernetes.io/upstream-hash-by: the nginx variable, text value or any combination thereof to use for consistent hashing. For example: nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri" or nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host" or nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value" to consistently hash upstream requests by the current request URI.

"subset" hashing can be enabled setting nginx.ingress.kubernetes.io/upstream-hash-by-subset: "true". This maps requests to subset of nodes instead of a single one. nginx.ingress.kubernetes.io/upstream-hash-by-subset-size determines the size of each subset (default 3).

Please check the chashsubset example.

Custom NGINX load balancing

This is similar to load-balance in ConfigMap, but configures load balancing algorithm per ingress.

Note that nginx.ingress.kubernetes.io/upstream-hash-by takes preference over this. If this and nginx.ingress.kubernetes.io/upstream-hash-by are not set then we fallback to using globally configured load balancing algorithm.

Custom NGINX upstream vhost

This configuration setting allows you to control the value for host in the following statement: proxy_set_header Host $host, which forms part of the location block. This is useful if you need to call the upstream server by something other than $host.

Client Certificate Authentication

It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.

Client Certificate Authentication is applied per host and it is not possible to specify rules that differ for individual paths.

To enable, add the annotation nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName. This secret must have a file named ca.crt containing the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress.

You can further customize client certificate authentication and behavior with these annotations:

The following headers are sent to the upstream service according to the auth-tls-* annotations:

Example

Please check the client-certs example.

Attention

TLS with Client Authentication is not possible in Cloudflare and might result in unexpected behavior.

Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/

Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls

Backend Certificate Authentication

It is possible to authenticate to a proxied HTTPS backend with certificate using additional annotations in Ingress Rule.

Configuration snippet

Using this annotation you can add additional configuration to the NGINX location. For example:

nginx.ingress.kubernetes.io/configuration-snippet: |
   more_set_headers "Request-Id: $req_id";
-

Since version 1.9.0 this annotation is disabled by default and has to be explicitly enabled, see allow-snippet-annotations. Enabling it can be dangerous in multi-tenant clusters, as it can lead to people with otherwise limited permissions being able to retrieve all secrets on the cluster. See CVE-2021-25742 and the related issue on github for more information.

Custom HTTP Errors

Like the custom-http-errors value in the ConfigMap, this annotation will set NGINX proxy-intercept-errors, but only for the NGINX location associated with this ingress. If a default backend annotation is specified on the ingress, the errors will be routed to that annotation's default backend service (instead of the global default backend). Different ingresses can specify different sets of error codes. Even if multiple ingress objects share the same hostname, this annotation can be used to intercept different error codes for each ingress (for example, different error codes to be intercepted for different paths on the same hostname, if each path is on a different ingress). If custom-http-errors is also specified globally, the error values specified in this annotation will override the global value for the given ingress' hostname and path.

Example usage: 

nginx.ingress.kubernetes.io/custom-http-errors: "404,415"
+

Since version 1.9.0 this annotation is disabled by default and has to be explicitly enabled, see allow-snippet-annotations. Enabling it can be dangerous in multi-tenant clusters, as it can lead to people with otherwise limited permissions being able to retrieve all secrets on the cluster. See CVE-2021-25742 and the related issue on github for more information.

Custom HTTP Errors

Like the custom-http-errors value in the ConfigMap, this annotation will set NGINX proxy-intercept-errors, but only for the NGINX location associated with this ingress. If a default backend annotation is specified on the ingress, the errors will be routed to that annotation's default backend service (instead of the global default backend). Different ingresses can specify different sets of error codes. Even if multiple ingress objects share the same hostname, this annotation can be used to intercept different error codes for each ingress (for example, different error codes to be intercepted for different paths on the same hostname, if each path is on a different ingress). If custom-http-errors is also specified globally, the error values specified in this annotation will override the global value for the given ingress' hostname and path.

Example usage: 

nginx.ingress.kubernetes.io/custom-http-errors: "404,415"

Default Backend

This annotation is of the form nginx.ingress.kubernetes.io/default-backend: <svc name> to specify a custom default backend. This <svc name> is a reference to a service inside of the same namespace in which you are applying this annotation. This annotation overrides the global default backend. In case the service has multiple ports, the first one is the one which will receive the backend traffic.

This service will be used to handle the response when the configured service in the Ingress rule does not have any active endpoints. It will also be used to handle the error responses if both this annotation and the custom-http-errors annotation are set.

Enable CORS

To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule, add the annotation nginx.ingress.kubernetes.io/enable-cors: "true". This will add a section in the server location enabling this functionality.

CORS can be controlled with the following annotations:

Note

For more information please see https://enable-cors.org

HTTP2 Push Preload.

Enables automatic conversion of preload links specified in the “Link” response header fields into push requests.

Example

Server Alias

Allows the definition of one or more aliases in the server definition of the NGINX configuration using the annotation nginx.ingress.kubernetes.io/server-alias: "<alias 1>,<alias 2>". This will create a server with the same configuration, but adding new values to the server_name directive.

Note

A server-alias name cannot conflict with the hostname of an existing server. If it does, the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created, the new server configuration will take place over the alias configuration.

For more information please see the server_name documentation.

Server snippet

Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block.

apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata: