Configuring Redirection Rules for an Nginx Ingress

Configuring a Permanent Redirection Rule

To permanently redirect an access request to a target website (status code 301), use the nginx.ingress.kubernetes.io/permanent-redirect annotation. For example, to permanently redirect all access requests to www.example.com, run the following command:

nginx.ingress.kubernetes.io/permanent-redirect: https://www.example.com

The configuration in an Nginx Ingress is as follows:

1. Use kubectl to access the cluster. For details, see Connecting to 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/permanent-redirect: https://www.example.com
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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/permanent-redirect: https://www.example.com
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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.

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 -I ${ELB_IP}

   The access path will be redirected to www.example.com.

   HTTP/1.1 301 Moved Permanently
   Date: Sat, 20 Jul 2024 07:55:49 GMT
   Content-Type: text/html
   Content-Length: 162
   Connection: keep-alive
   Location: https://www.example.com

Configuring the Returned Status Code for the Permanent Redirection Rule

When configuring a permanent redirection rule, you can use the nginx.ingress.kubernetes.io/permanent-redirect-code annotation to modify its returned status code. For example, to set the status code for the permanent redirection to 308, run the following command:

nginx.ingress.kubernetes.io/permanent-redirect-code: '308'

The configuration in an Nginx Ingress is as follows:

1. Use kubectl to access the cluster. For details, see Connecting to 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/permanent-redirect: https://www.example.com
       nginx.ingress.kubernetes.io/permanent-redirect-code: '308'
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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/permanent-redirect: https://www.example.com
       nginx.ingress.kubernetes.io/permanent-redirect-code: '308'
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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.

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 -I ${ELB_IP}

   The access path will be redirected to www.example.com, and the status code is 308.

   HTTP/1.1 308 Moved Permanently
   Date: Sat, 20 Jul 2024 07:55:49 GMT
   Content-Type: text/html
   Content-Length: 162
   Connection: keep-alive
   Location: https://www.example.com

Configuring a Temporary Redirection Rule

To temporarily redirect an access request to a target website (status code 302), use the nginx.ingress.kubernetes.io/temporal-redirect annotation. For example, to temporarily redirect all access requests to www.example.com, run the following command:

nginx.ingress.kubernetes.io/temporal-redirect: https://www.example.com

The configuration in an Nginx Ingress is as follows:

1. Use kubectl to access the cluster. For details, see Connecting to 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/temporal-redirect: https://www.example.com
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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/temporal-redirect: https://www.example.com
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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.

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 -I ${ELB_IP}

   The access path will be redirected to www.example.com, and the status code is 302.

   HTTP/1.1 302 Moved Temporarily
   Date: Sat, 20 Jul 2024 08:01:02 GMT
   Content-Type: text/html
   Content-Length: 138
   Connection: keep-alive
   Location: https://www.example.com

Redirecting HTTP to HTTPS

By default, if an ingress uses TLS, requests will be redirected (status code 308) to HTTPS when HTTP is used for access. You can configure the redirection by using the nginx.ingress.kubernetes.io/ssl-redirect annotation.

• If the value of this annotation is set to true, an HTTP access is redirected to HTTPS (status code 308) when the TLS certificate is used.
• If the value of this annotation is set to false, an HTTP access cannot be redirected to HTTPS when the TLS certificate is used.

If you need to forcibly redirect an HTTP access to HTTPS without a TLS, you can configure the redirection by setting the value of nginx.ingress.kubernetes.io/force-ssl-redirect to true.

1. Use kubectl to access the cluster. For details, see Connecting to 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/ssl-redirect: 'true'
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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/ssl-redirect: 'true'
   spec:
     rules:
       - host: ''
         http:
           paths:
             - path: /
               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.

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 -I ${ELB_IP}

   The access path will be redirected to HTTPS, and the status code is 308.

   HTTP/1.1 308 Permanent Redirect
   Date: Sat, 20 Jul 2024 08:03:36 GMT
   Content-Type: text/html
   Content-Length: 164
   Connection: keep-alive
   Location: https://${ELB_IP}