Kubernetes Nginx Ingress: Traffic Redirect Using Annotations Demystified

24/04/2020  

GUEST BLOG: Ionut Craciunescu


Ionut is currently Lead Platform Engineer at financial advice technology provider, Wealth Wizards. A featured speaker at several DevOps `Exchange events, we reached out to Ionut to discuss Traffic Redirect using Kubernetes Ingress and Nginx Ingress controller. 

Redirect HTTP traffic or rewrite URLs using Kubernetes ingress annotations and Nginx ingress controller. This article explains annotations usage and their effect on the resulting nginx.conf configuration file.

1. nginx.ingress.kubernetes.io/rewrite-target

Example 1:

This one does a transparent reverse proxy.

It does not update the Location header so the URL in the browser does not change.

Example 2:


This one changes the Location header and the URL in the browser is updated:

This is because the replacement string as specified in rewrite-target annotation starts with https:// .

From nginx docs:


Using nginx.ingress.kubernetes.io/permanent-redirect-code: ‘308’annotation has no effect on the code returned as this is controlled by the rewrite rule in nginx.conf . The directive added in nginx.conf is similar to:



If you need to control the return code using a rewrite rule, then you need to use a return directive after the rewrite directive. More info here: https://www.nginx.com/blog/creating-nginx-rewrite-rules.

I assume this can be used using:
(Although, I have not tried it yet).

This one is nice: defines the Application Root that the Controller must redirect if it’s in / context:


In the resulting nginx.conf an if statement will be added to the server context :


2. nginx.ingress.kubernetes.io/configuration-snippet: |


This one looks like it gives the greatest control over the redirect/rewrite as it will add the additional configuration snippet to the resulting nginx.conf location.


Additional docs here.

3. nginx.ingress.kubernetes.io/server-snippet: |

Use carefully. While it can be used similar to the one above (only the annotation is slightly different) it will add your custom config to the server block in the resulting nginx.conf , thus taking effect server-wide. A redirect/rewrite rule placed in here will be processed before any other statement in a location directive (controlled by a Kubernetes ingress resource) so it might lead to undesired behaviour.

Additional docs here.

4. nginx.ingress.kubernetes.io/permanent-redirect


Pretty self-explanatory, works a treat.

It adds an if statement in the nginx.conf under /source location as follows:

Additional docs: annotations.md#permanent-redirect and here.

Permanent Redirect
This annotation allows to return a permanent redirect instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com would redirect everything to Google.

Permanent Redirect Code
This annotation allows you to modify the status code used for permanent redirects. For example, nginx.ingress.kubernetes.io/permanent-redirect-code: ‘308’ would return your permanent-redirect with a 308.

Temporal Redirect
This annotation allows you to return a temporal redirect (Return Code 302) instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com would redirect everything to Google with a Return Code of 302 (Moved Temporarily)


Ionut Craciunescu has a background in running and designing infrastructure environments, with a focus on cloud and microservices. He is focused on the delivery of a secure, scalable and efficient platform for running Wealth Wizards applications.

 You can see his latest DevOps Exchange talk here and read more of his personal blogs on Medium, here.