NGINX Ingress Configuration Reference
When configuring the cce-ingress-nginx-controller component, there are two ways to set parameters: for the component itself or for individual ingress resources.
Global component parameters can be set in ConfigMap, and specific configurations for an ingress, host, or rule can be modified using ingress annotations.
Ingress NGINX Controller ConfigMap
Each instance of the cce-ingress-nginx-controller plugin in the cluster has an associated ConfigMap, whose settings apply to the entire plugin.
The settings in the ConfigMap can override the default configurations of the components.
In the cluster, this ConfigMap is located in the kube-system namespace and named {ingressclass}-ngx-control-controller.
All configuration items in ConfigMap are key-value strings:
- For numeric and Bool-type values, add quotes, e.g., "true", "101"
- For array values, use comma-separated strings
For complete ConfigMap parameters, refer to ConfigMap - NGINX Ingress Controller
Example
The following is a cce-ingress-nginx-controller ConfigMap in a cluster for reference
1apiVersion: v1
2data:
3 compute-full-forwarded-for: 'true'
4 forwarded-for-header: X-Forwarded-For
5 use-forwarded-headers: 'true'
6 keep-alive-requests: '10000'
7 log-format-upstream: >-
8 {"time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr",
9 "x_forward_for": "$proxy_add_x_forwarded_for", "request_id": "$req_id",
10 "remote_user": "$remote_user", "bytes_sent": $bytes_sent, "request_time":
11 $request_time, "status": $status, "vhost": "$host", "request_proto":
12 "$server_protocol", "path": "$uri", "request_query": "$args",
13 "request_length": $request_length, "duration": $request_time,"method":
14 "$request_method", "http_referrer": "$http_referer", "http_user_agent":
15 "$http_user_agent" }
16 max-worker-connections: '65536'
17 upstream-keepalive-connections: '200'
18kind: ConfigMap
19metadata:
20 annotations:
21 meta.helm.sh/release-name: cce-ngx-control
22 meta.helm.sh/release-namespace: kube-system
23 labels:
24 app.kubernetes.io/component: controller
25 app.kubernetes.io/instance: cce-ngx-control
26 app.kubernetes.io/managed-by: Helm
27 app.kubernetes.io/name: cce-ingress-nginx-controller
28 app.kubernetes.io/version: 0.45.0
29 helm.sh/chart: cce-ingress-nginx-controller-3.29.0
30 name: cce-ngx-control-controller
31 namespace: kube-systemNGINX Ingress Annotation
NGINX ingress annotations allow changes to the default behavior of an ingress, host, or specific rules.
For complete ingress annotation configurations, refer to Annotations - NGINX Ingress Controller
Example
The following is an ingress resource content in a cluster for reference:
1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4 annotations:
5 cce.ingress.blb-backup-content: ''
6 kubernetes.io/ingress.class: cce
7 nginx.ingress.kubernetes.io/use-regex: 'true'
8 nginx.ingress.kubernetes.io/ssl-redirect: 'false'
9 name: test
10 namespace: default
11spec:
12 rules:
13 - host: a.com
14 http:
15 paths:
16 - backend:
17 service:
18 name: service-example
19 port:
20 number: 80
21 path: /*Common service scenarios
The following describes common usage scenarios and their related configurations
Use X-Forwarded-For Header to record source IPs
When we want requests passing through ingress to include the original ClientIP, modify the configuration as follows:
1# Configuration located in ConfigMap
2 compute-full-forwarded-for: 'true' # Calculate the complete X-Forwarded-For Header, appending the source IP to the header instead of directly overwriting the original value
3 forwarded-for-header: X-Forwarded-For # Use X-Forwarded-For Header to identify source IP
4 use-forwarded-headers: 'true’ # Preserve the X-Forwarded-* headers from the upstream requestIngress simultaneously receives both HTTP and HTTPS requests
By default, NGINX ingress returns a 308 response for HTTP requests to domain names configured with HTTPS. After applying the following annotation to the ingress resource, HTTPS redirection will be disabled, allowing direct HTTP access:
1# Configuration located in ingress annotation
2 nginx.ingress.kubernetes.io/ssl-redirect: "false" # SSL redirection is disabledURL rewriting
Using annotations with ingress enables URL rewriting functionality.
In regex match extraction, $N represents the content matched by the Nth parenthesis in the URL regular expression template.
For example, suppose we want to forward the ^/nginx/(.) URL under a specific ingress to the backend service while removing the /nginx prefix, and also forward the ^/tomcat/(.) URL under a specific ingress to the backend service while removing the /tomcat prefix. In such cases, we can add the following annotation to the ingress:
1# Configuration located in ingress annotation
2nginx.ingress.kubernetes.io/configuration-snippet: |
3 rewrite ^/nginx/(.*) /$1 break;
4 rewrite ^/tomcat/(.*) /$1 break;