Can someone please explain to me when I would use the "App Root" annotation in Kubernetes

Question

I've read the docs a thousand times but I still don't understand how I would use the nginx.ingress.kubernetes.io/app-root annotation.

Can someone please provide an example + description in plain english?

Docs: https://kubernetes.github.io/ingress-nginx/examples/rewrite/

I might as well copy paste the entire text; it's not that much.

nginx.ingress.kubernetes.io/app-root Defines the Application Root that the Controller must redirect if it's in '/' context string

App Root

Create an Ingress rule with a app-root annotation:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/app-root: /app1
  name: approot
  namespace: default
spec:
  rules:
  - host: approot.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /

Check the rewrite is working

$ curl -I -k http://approot.bar.com/
HTTP/1.1 302 Moved Temporarily
Server: nginx/1.11.10
Date: Mon, 13 Mar 2017 14:57:15 GMT
Content-Type: text/html
Content-Length: 162
Location: http://stickyingress.example.com/app1
Connection: keep-alive

Answer 1

It simply redirects requests coming to '/' to a different path internally. This is useful if your application's root path is different from '/'.

For example, say your application is listening in '/server', you'd set your Nginx annotiations like:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    annotations:
        nginx.ingress.kubernetes.io/app-root: /server

At this point, any incoming requests at example.com/ would be redirected with HTTP status code 302 to indicate where the resource is: example.com/server.

Answer 2

Using the nginx.ingress.kubernetes.io/app-root: /destination annotation will add the following lines the the nginx.conf

if ($uri = /) {
    return 302 $scheme://$http_host/destination;
}

This means that it will instruct the browser to redirect (302 temporarily moved) to the path /destination. There is no internal rewrite going on here, as stated by others.

The annotation is very useful if you have a default location that you want to redirect your users to when they hit the root path: /