Help Center> Cloud Container Engine> User Guide> Network> Ingresses> Nginx Ingresses> Configuring URL Rewriting Rules for Nginx Ingresses
Updated on 2024-03-04 GMT+08:00
View PDF

Configuring URL Rewriting Rules for Nginx Ingresses

In some application scenarios, the access URL provided by the backend service is different from the path specified in the ingress rule. The ingress directly forwards the access path to the same backend path. If URL rewriting is not configured, 404 is returned for all access requests. For example, if the access path in the ingress rule is set to /app/demo and the access path provided by the backend service is /demo, access requests are directly forwarded to the /app/demo path of the backend service, which does not match the actual access path (/demo) provided by the backend service. As a result, 404 is returned.

In this case, you can use the Rewrite method to implement URL rewriting. That is, you can use the nginx.ingress.kubernetes.io/rewrite-target annotation to implement rewriting rules for different paths.

Configuring Rewriting Rules

For clusters of v1.23 or later: 
apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
    - host: 'rewrite.bar.com'
      http:
        paths:
          - path: '/something(/|$)(.*)'
            backend:
              service:
                name: <your_service_name>  # Replace it with the name of your target Service.
                port:
                  number: <your_service_port>  # Replace 8080 with the port number of your target Service.
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx
For clusters of v1.21 or earlier: 
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
    - host: 'rewrite.bar.com'
      http:
        paths:
          - path: '/something(/|$)(.*)'
            backend:
              serviceName: <your_service_name>  # Replace it with the name of your target Service.
              servicePort: <your_service_port>  # Replace 8080 with the port number of your target Service.

As long as rewrite-target is specified for one ingress, all paths under the same host in all ingress definitions are case-sensitive, including the ingresses that do not have rewrite-target specified.

In the preceding example, the placeholder $2 indicates that all characters matched by the second parenthesis (.*) are filled in the nginx.ingress.kubernetes.io/rewrite-target annotation.

For example, the preceding ingress definition will result in the following rewrites:
  • rewrite.bar.com/something rewrites to rewrite.bar.com/.
  • rewrite.bar.com/something/ rewrites to rewrite.bar.com/.
  • rewrite.bar.com/something/new rewrites to rewrite.bar.com/new.

In the nginx-ingress-controller container, you can view all ingress configurations in the nginx.conf file in the /etc/nginx directory. The rewriting rule in the preceding example generates a Rewrite command and writes it to the location field in the nginx.conf file.

## start server rewrite.bar.com
        server {
                server_name rewrite.bar.com ;
                ...
                location ~* "^/something(/|$)(.*)" {
                        set $namespace      "default";
                        set $ingress_name   "ingress-test";
                        set $service_name   "<your_service_name>";
                        set $service_port   "80";
                        ...
                        rewrite "(?i)/something(/|$)(.*)" /$2 break;
                        ...
                }
        }
        ## end server rewrite.bar.com
The basic syntax of the Rewrite command is as follows: 
rewrite regex replacement [flag];
  • regex: regular expression for matching URIs. In the preceding example, (?i)/something(/|$)(.*) is the regular expression for matching URIs, where (?i) indicates case-insensitive.
  • replacement: content to rewrite. In the preceding example, /$2 indicates that the path is rewritten to all the characters matched by the second parenthesis (.*).
  • flag: rewrite format.
    • last: continues to match the next rule after the current rule is matched.
    • break: stops matching after the current rule is matched.
    • redirect: returns a temporary redirect with the 302 code.
    • permanent: returns a permanent redirect with the 301 code.

Advanced Rewrite Configuration

Some complex, advanced Rewrite requirements can be implemented by modifying the Nginx configuration file nginx.conf. However, the nginx.ingress.kubernetes.io/rewrite-target annotation function can be customized to meet more complex Rewrite requirements.

  • nginx.ingress.kubernetes.io/server-snippet: Add custom settings to the server field in the nginx.conf file.
  • nginx.ingress.kubernetes.io/configuration-snippet: Add custom settings to the location field in the nginx.conf file.

You can use the preceding two annotations to insert a Rewrite command into the server or location field in the nginx.conf file to rewrite the URL. The following is an example:

annotations:
     kubernetes.io/ingress.class: "nginx"
     nginx.ingress.kubernetes.io/configuration-snippet: |
        rewrite ^/stylesheets/(.*)$ /something/stylesheets/$1 redirect;  # Add the /something prefix.
        rewrite ^/images/(.*)$ /something/images/$1 redirect;  # Add the /something prefix.
In the preceding two rules, the /something path is added to the access URL.
  • When a user accesses rewrite.bar.com/stylesheets/new.css, it rewrites to rewrite.bar.com/something/stylesheets/new.css.
  • When a user accesses rewrite.bar.com/images/new.jpg, it rewrites to rewrite.bar.com/something/images/new.jpg.
Parent topic: Nginx Ingresses