Volcengine Kubernetes Engine
Volcengine Kubernetes Engine
Document
- Documentation
Volcengine Kubernetes EngineVolcengine Kubernetes EngineUser guideNetworkingIngressNginx IngressCommon annotations of NGINX Ingresses
Copy page
Download PDFNginx Ingress
Common annotations of NGINX Ingresses
Copy pageDownload PDFCommon annotations of NGINX Ingresses
The NGINX Ingress in Volcengine Kubernetes Engine (VKE) provides annotations that are fully compatible with the community, which provide more diverse Layer 7 load balancing capabilities and Ingresses. This topic describes the meaning and usage of common annotations of the NGINX Ingress in VKE.
warning
- NGINX Ingress support will soon be discontinued. For details, see [Product announcement] NGINX Ingress EOM.
- The provided annotations are slightly different because the version of the NGINX Ingress varies based on the cluster version. The annotations displayed in the console shall prevail.
- If you do not find the target annotation in the following content, see NGINX official documentation.
Canary release
Annotation | Description |
Enable the canary release feature. If it is set to true, the feature is enabled. | |
Implement canary release based on headers. Traffic is routed to the service specified in the canary Ingress. | |
When the header value in the request matches the configuration, the request will be routed to the service specified in the canary Ingress. | |
Traffic is split based on request header values. Regular expression matching is supported. | |
Implement canary release based on cookies. Traffic is routed to the service specified in the canary Ingress. | |
Implement canary release based on weight, and traffic is randomly routed to the service specified in the canary Ingress based on the assigned weights. | |
Specify the total weight during traffic splitting based on weight. |
tip
For details on how to use canary release-related annotations, see Implementing canary release and blue-green deployment by using NGINX Ingresses.
Redirect
Annotation | Description |
Determines whether to forcibly redirect HTTP requests to the HTTPS port when HTTPS traffic from clients undergoes SSL offloading outside the cluster. Valid values:
| |
Specify whether to redirect from www.domain.com to domain.com. Valid values:
| |
Specify the target address for a permanent redirect. | |
Configure the response code used for permanent redirects. | |
Specify the target address for temporary redirects. | |
Specify whether to preserve the trailing slash in the URI with ssl-redirect. Valid values:
| |
Set the text to be replaced, which is the same as the first parameter of the proxy_redirect directive of NGINX. | |
Specify the text to be replaced. It corresponds to the second parameter of the Nginx proxy_redirect command. | |
Specify whether to forcibly redirect HTTP requests to HTTPS.
tip The default value true is used when a certificate exists on the Ingress. It means that HTTP requests are redirected. |
tip
For details on how to use redirect-related annotations, see Configuring redirect rules by using NGINX Ingresses.
Traffic replication
Annotation | Description |
Configure the address of the mirrored backend. | |
By default, the Host header of mirrored requests will be set to the same as the configuration of the mirror-target annotation. You can use this field to override the content of the Host header. | |
By default, the request body is sent to the mirrored backend. If you set this field to off, the request body is prohibited from being sent to the image backend. |
tip
For details on how to use traffic replication-related annotations, see Configuring traffic replication by using Nginx Ingresses.
Backend service
Annotation | Description |
Specify the protocol used by the backend service. Valid values: HTTP (default value), HTTP2, HTTPS, GRPC, and GRPCS. | |
Specify the service name of the default backend resource object. |
tip
For details on how to use backend service-related annotations, see Connecting NGINX Ingresses to backend HTTPS services.
URL rewriting
In certain scenarios, the URL exposed in the backend service differs from the path specified in the Ingress. Without a rewrite, any request will return 404.
Annotation | Description |
Configure a URL rewriting rule. | |
Specify the root directory for application redirects. |
tip
For details on how to use URL rewriting-related annotations, see Configuring URL rewriting rules by using Nginx Ingresses.
Authentication
You can enable authentication by adding annotations to Ingresses.
Annotation | Description |
Specify the authentication type. Valid values: basic and digest. | |
Specify the name of the secret used for authentication. | |
Specify the format of the secret used for authentication. The following two formats are supported:
| |
Specify the authentication message. |
External authentication
Annotation | Description |
Specify the URL of the external authentication service. | |
Specify the maximum keepalive duration for the external authentication URL connection. | |
Specify whether to share NGINX variables among the current request and the external authentication request.
| |
Specify the maximum number of requests that can be handled through one keepalive connection of external authentication. | |
Specify the timeout duration for the external authentication URL. | |
Specify the name of a ConfigMap of the headers to be passed to the authentication service. | |
Enable caching for authentication requests and specify a keyword for authentication caches. | |
Specify a caching time for authentication responses based on their response codes. | |
Configure custom code segments for external authentication. | |
Specify whether to enable GlobalExternalAuth. Valid values:
|
Session affinity
Annotation | Description |
Specify the session affinity type. You can set the value only to cookie. | |
Configure the session affinity mode. Valid values:
| |
Configure the session affinity policy for blue-green deployment. Valid values:
|
Client certificate authentication
Annotation | Description |
Specify the name of the secret for client authentication. The secret must have a file named ca.crt, which can be used to authenticate this Ingress. | |
Specify the validation depth between the provided client certificate and the Certification Authority chain. Default value: 1. | |
Specify whether to enable verification of client certificates. | |
Configure the page that users will be redirected to in case of a client certificate authentication error. | |
Specify whether to pass the certificates to the upstream server. Valid values:
| |
Add a sanity check for the CN of the client certificate for a request starting with CN=. |
Backend certificate authentication
Annotation | Description |
Specify the name of the secret used for backend authentication. The secret must contain a file named ca.crt used to verify the certificate of the proxy. | |
Enable or disable the verification of the proxy certificate. Valid values:
| |
Specify the verification depth in the proxy certificate chain. Default value: 1. | |
Specify the enabled ciphers for requests to a proxy. The ciphers need to be specified in the format understood by the OpenSSL library. | |
Override the server name used to verify the proxy certificate. This value is passed through SNI when a connection is established to the proxy. | |
Enable the specified protocols for requests to a proxy. | |
Pass the server name through TLS Server Name Indication (SNI) extension when you establish a connection with the proxied HTTPS server. |
CORS
Annotation | Description |
Specify whether to enable Cross-Origin Resource Sharing (CORS). Valid values:
| |
Specify the domain name, which is the accepted origin for CORS. | |
Specify which methods of CORS are allowed. | |
Specify which request headers are accepted for CORS. | |
Configure headers to be exposed to the response of the browser. | |
Specify whether to allow the client to carry credentials. Valid values:
| |
Configure the maximum duration for request result caching. |
Timeout duration
Annotation | Description |
Specify the timeout duration for sending requests to the upstream servers. | |
Specify the maximum interval at which write operations are performed. | |
Specify the timeout between two successive read operations from the upstream server before the connection is closed. | |
Specify retry policies or conditions. | |
Specify the timeout duration for forwarding a connection to the next server. | |
Specify the maximum number of request retries. | |
Specify whether to enable the request buffering feature. Valid values:
|
Global rate limiting
Annotation | Description |
Specify the maximum allowed number of requests per window. | |
Configures a time window. | |
Specify a key used for counting. | |
Specify the list of IP addresses and CIDRs that are not subject to rate limiting. Separate different IP addresses and CIDRs with commas (,). |
Others
Annotation | Description |
Set the buffer size for reading the client request body per location | |
Add the NGINX configuration directive to the NGINX location. | |
Set error status based on the response code. This annotation only applies to the location associated with the current Ingress. | |
This annotation can be used to disable NGINX proxy-intercept-errors when custom-http-errors are set, but only for the NGINX location associated with this ingress. | |
Specify whether NGINX can automatically push preload links specified in the Link header to clients. Valid values:
| |
Specify the number of concurrent connections allowed from a single IP address. | |
Specify the number of requests accepted from an IP address each second. | |
Specify the maximum allowed size of the request body in NGINX. If the size of the client request body exceeds the upper limit, NGINX will return the 413 error code. | |
Set the Domain attribute set by the upstream server through the Set-Cookie field to the specified value. | |
Specify the Set-Cookie field of a proxied server response. | |
Specify the HTTP version that the NGINX reverse proxy uses to communicate with the backend. Valid values: 1.0 and 1.1. | |
Specify whether to enable rewrite logs. Valid values:
| |
By default, a request can be allowed only if it satisfies all authentication requirements. You can use this annotation to allow requests that satisfy either any or all authentication requirements. | |
Specify one or more aliases in the server definition of the NGINX configuration. | |
Add custom configurations to the server configuration block. | |
Configure the upstream member list. Valid values:
| |
Specify the cookie name. | |
Set the value of the Path field of the cookie. | |
Specify the Domain attribute of the cookie. | |
Specify whether the next request will be forwarded to another proxied server if a request to a proxied server with session persistence fails.
| |
Apply the SameSite attribute to the cookie. | |
Omit the SameSite=None attribute from browsers that are incompatible with SameSite=None. | |
Specify whether the controller directly sends TLS connections to the backend. Valid values:
| |
Add custom stream configuration to the server block. | |
The NGINX variable, text value, or any combination used for consistent hashing. | |
Add the non-standard X-Forwarded-Prefix header to the upstream request with a string value. | |
Specify a load balancing algorithm for backend services. Valid values: round_robin (default value) and ewma. | |
Modify the value of host in the statement proxy_set_header Host $host. | |
Specify the blocked client IP source ranges. You can set the value to a list of IP addresses or CIDRs that are separated by commas (,). | |
Specify the allowed client IP source ranges. You can set the value to a list of IP addresses or CIDRs that are separated by commas (,). | |
Specify whether to enable proxy buffering. Valid values:
| |
Specify the number of buffers used for reading the response received from the proxy. Default value: 4. | |
Specify the size of the buffer used for reading the response received from the proxy. Default value: 4k. | |
Specify the size of the temporary buffer. When buffering of responses from the proxied server is enabled, any response larger than the buffer size can have part of it saved to a temporary buffer. | |
Configure the cipher combinations used by TLS for negotiation. | |
Specify whether the server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used. Valid values:
| |
Override the default connection header set by NGINX. | |
Specify whether to enable access logs. Valid values:
| |
Specify whether to enable opentracing. Valid values:
| |
Specify whether to trust trace spans. Valid values:
| |
Specify whether to enable OpenTelemetry. Valid values:
| |
Specify whether to trust the trace spans of OpenTelemetry. Valid values:
| |
Specify whether the paths use regular expressions. Valid values:
| |
Specify whether to enable ModSecurity. Valid values:
| |
Specify whether to enable the OWASP Core Rule Set. Valid values:
| |
Pass transaction IDs from NGINX instead of generating the IDs in the library. | |
Configure the custom ModSecurity rule. |
Last updated: 2026.07.24 14:51:37
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
