Configuring URL Rewriting Rules for an Nginx Ingress

Configuring a Rewriting Rule

1. Use kubectl to access the cluster. For details, see Accessing a Cluster Using kubectl.
2. Create a YAML file named ingress-test.yaml. The file name can be customized.

   vi ingress-test.yaml
   
   

   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: ''
         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 it 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: ''
         http:
           paths:
             - path: '/something(/|$)(.*)'
               backend:
                 serviceName: <your_service_name>  # Replace it with the name of your target Service.
                 servicePort: <your_service_port>  # Replace it with the port number of your target Service.
   
   

   Note

   In an NGINX Ingress Controller, if any Nginx ingress for a given host uses the rewrite-target annotation, all paths for that host across all Nginx ingresses will be case-insensitive to regular expressions.

   In the preceding example, the placeholder $2 specifies that all characters matched by the second parenthesis (.*) are added to the nginx.ingress.kubernetes.io/rewrite-target annotation as the rewritten URL path.

   For example, the preceding regular expression matching for ingress causes URL rewriting in multiple cases. These cases include:

   • /something is rewritten to /.
   • /something/ is rewritten to /.
   • /something/new is rewritten to /new.

3. Create an ingress.

   kubectl create -f ingress-test.yaml
   
   

   If information similar to the following is displayed, the ingress has been created:

   ingress/ingress-test created
   
   

4. Check the created ingress.

   kubectl get ingress
   
   

   If information similar to the following is displayed, the ingress has been created:

   NAME          CLASS   HOSTS     ADDRESS          PORTS   AGE
   ingress-test  nginx   *         121.**.**.**     80      10s
   
   

5. Access the ingress. ${ELB_IP} specifies the IP address of the load balancer associated with the Nginx ingress.

   curl ${ELB_IP}/something
   
   

   The access path will be redirected to /.

Checking the Configurations of an Ingress

1. Obtain the name of the pod that runs nginx-ingress-controller.

   kubectl get pod -n kube-system | grep nginx-ingress-controller
   
   

   Command output:

   cceaddon-nginx-ingress-controller-66855ccb9b-52qcd        1/1     Running   0          37m
   
   

2. Log in to the nginx-ingress-controller pod.

   kubectl exec -it cceaddon-nginx-ingress-controller-66855ccb9b-52qcd -n kube-system -- /bin/bash
   
   

3. Check the nginx.conf file in /etc/nginx.

   cat /etc/nginx/nginx.conf
   
   

   The rewriting rule in this example generates a Rewrite command and writes it to the location field in the nginx.conf file as follows:

   ## start server _
           server {
                   server_name _ ;
                   ...
                   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 _
   
   

   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

• 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.

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 rules, the /something prefix is added to the access URL. Specifically:

• When a user accesses /stylesheets/new.css in the example, the path will be rewritten as /something/stylesheets/new.css.
• When a user accesses /images/new.jpg in the example, the path will be rewritten as /something/images/new.jpg.