Configuring Nginx Ingresses Using Annotations

The nginx-ingress add-on in CCE uses the community chart and image. If the default add-on parameters cannot meet your demands, you can add annotations to define what you need, such as the default backend, timeout, and size of a request body.

This section describes common annotations used for creating an ingress of the Nginx type.

The key value of an annotation can only be a string. Other types (such as Boolean values or numeric values) must be enclosed in quotation marks (""), for example, "true", "false", and "100".
Nginx Ingress supports native annotations of the community. For details, see Annotations.

Ingress Type
Configuring a Redirection Rule
Configuring a URL Rewriting Rule
Interconnecting with HTTPS Backend Services
Creating a Consistent Hashing Rule for Load Balancing
Customized Timeout Interval
Customizing Body Size
Documentation

Ingress Type

**Table 1** Ingress type annotations
Parameter	Type	Description	Supported Cluster Version
kubernetes.io/ingress.class	String	nginx: Nginx ingress is used. cce: The self-developed ELB ingress is used. This parameter is mandatory when an ingress is created by calling the API. For clusters of v1.23 or later, use the parameter ingressClassName. For details, see Using kubectl to Create an Nginx Ingress.	Only clusters of v1.21 or earlier

For details about how to use the preceding annotations, see Using kubectl to Create an Nginx Ingress.

Configuring a Redirection Rule

**Table 2** Redirection rule annotations
Parameter	Type	Description
nginx.ingress.kubernetes.io/permanent-redirect	String	Permanently redirects an access request to a target website (status code 301).
nginx.ingress.kubernetes.io/permanent-redirect-code	String	Changes the returned status code of a permanent redirection rule to a specified value.
nginx.ingress.kubernetes.io/temporal-redirect	String	Temporarily redirects an access request to a target website (status code 302).
nginx.ingress.kubernetes.io/ssl-redirect	Bool	Specifies whether an HTTP request can be redirected to HTTPS only through SSL. The default value is true when the Ingress contains an SSL certificate.
nginx.ingress.kubernetes.io/force-ssl-redirect	Bool	Indicates whether to forcibly redirect a request to HTTPS even if TLS is not enabled for the Ingress. When HTTP is used for access, the request is forcibly redirected (status code 308) to HTTPS.

Configuring a URL Rewriting Rule

**Table 3** URL rewriting rule annotations
Parameter	Type	Description
nginx.ingress.kubernetes.io/rewrite-target	String	Target URI where the traffic must be redirected.

For details about the application scenarios, see Configuring URL Rewriting Rules for Nginx Ingresses.

Interconnecting with HTTPS Backend Services

**Table 4** Annotations for interconnecting with HTTPS backend services
Parameter	Type	Description
nginx.ingress.kubernetes.io/backend-protocol	String	If this parameter is set to HTTPS, HTTPS is used to forward requests to the backend service container.

For details about the application scenarios, see Interconnecting Nginx Ingresses with HTTPS Backend Services.

Creating a Consistent Hashing Rule for Load Balancing

**Table 5** Annotation of consistent hashing for load balancing
Parameter	Type	Description
nginx.ingress.kubernetes.io/upstream-hash-by	String	Enable consistent hashing for load balancing for backend servers. The parameter value can be an Nginx parameter, a text value, or any combination. For example: nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri" indicates that requests are hashed based on the request URI. nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host" indicates that requests are hashed based on the request URI and domain name. nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value" indicates that requests are hashed based on the request URI and text value.

For details about the application scenarios, see Nginx Ingresses Using Consistent Hashing for Load Balancing.

Customized Timeout Interval

**Table 6** Customized timeout interval annotations
Parameter	Type	Description
nginx.ingress.kubernetes.io/proxy-connect-timeout	String	Customized connection timeout interval. You do not need to set the unit when setting the timeout interval. The default unit is second. Example: nginx.ingress.kubernetes.io/proxy-connect-timeout: '120'

Customizing Body Size

**Table 7** Annotations of customizing body size
Parameter	Type	Description
nginx.ingress.kubernetes.io/proxy-body-size	String	When the body size in a request exceeds the upper limit, error 413 is returned to the client. You can use this parameter to adjust the upper limit of the body size. Example: nginx.ingress.kubernetes.io/proxy-body-size: 8m