Annotations for Application Gateway Ingress Controller
Introductions
The Kubernetes Ingress resource can be annotated with arbitrary key/value pairs. AGIC relies on annotations to program Application Gateway features, which are not configurable via the Ingress YAML. Ingress annotations are applied to all HTTP setting, backend pools, and listeners derived from an ingress resource.
List of supported annotations
For an Ingress resource to be observed by AGIC, it must be annotated with kubernetes.io/ingress.class: azure/application-gateway
. Only then AGIC will work with the Ingress resource in question.
Annotation Key | Value Type | Default Value | Allowed Values |
---|---|---|---|
appgw.ingress.kubernetes.io/backend-path-prefix | string |
nil |
|
appgw.ingress.kubernetes.io/ssl-redirect | bool |
false |
|
appgw.ingress.kubernetes.io/connection-draining | bool |
false |
|
appgw.ingress.kubernetes.io/connection-draining-timeout | int32 (seconds) |
30 |
|
appgw.ingress.kubernetes.io/cookie-based-affinity | bool |
false |
|
appgw.ingress.kubernetes.io/request-timeout | int32 (seconds) |
30 |
|
appgw.ingress.kubernetes.io/use-private-ip | bool |
false |
|
appgw.ingress.kubernetes.io/backend-protocol | string |
http |
http , https |
Backend Path Prefix
This annotation allows the backend path specified in an ingress resource to be rewritten with prefix specified in this annotation. This allows users to expose services whose endpoints are different than endpoint names used to expose a service in an ingress resource.
Usage
appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-bkprefix
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 80
In the example above, we have defined an ingress resource named go-server-ingress-bkprefix
with an annotation appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"
. The annotation tells application gateway to create an HTTP setting, which will have a path prefix override for the path /hello
to /test/
.
Note
In the above example we have only one rule defined. However, the annotations are applicable to the entire ingress resource, so if a user had defined multiple rules, the backend path prefix would be set up for each of the paths specified. Thus, if a user wants different rules with different path prefixes (even for the same service) they would need to define different ingress resources.
TLS Redirect
Application Gateway can be configured
to automatically redirect HTTP URLs to their HTTPS counterparts. When this
annotation is present and TLS is properly configured, Kubernetes Ingress
controller will create a routing rule with a redirection configuration
and apply the changes to your Application Gateway. The redirect created will be HTTP 301 Moved Permanently
.
Usage
appgw.ingress.kubernetes.io/ssl-redirect: "true"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-redirect
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/ssl-redirect: "true"
spec:
tls:
- hosts:
- www.contoso.com
secretName: testsecret-tls
rules:
- host: www.contoso.com
http:
paths:
- backend:
serviceName: websocket-repeater
servicePort: 80
Connection Draining
connection-draining
: This annotation allows users to specify whether to enable connection draining.
connection-draining-timeout
: This annotation allows users to specify a timeout after which Application Gateway will terminate the requests to the draining backend endpoint.
Usage
appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-drain
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 80
Cookie Based Affinity
This annotation allows to specify whether to enable cookie based affinity.
Usage
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-affinity
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 80
Request Timeout
This annotation allows to specify the request timeout in seconds after which Application Gateway will fail the request if response is not received.
Usage
appgw.ingress.kubernetes.io/request-timeout: "20"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/request-timeout: "20"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 80
Use Private IP
This annotation allows us to specify whether to expose this endpoint on Private IP of Application Gateway.
Note
- Application Gateway doesn't support multiple IPs on the same port (example: 80/443). Ingress with annotation
appgw.ingress.kubernetes.io/use-private-ip: "false"
and another withappgw.ingress.kubernetes.io/use-private-ip: "true"
onHTTP
will cause AGIC to fail in updating the Application Gateway. - For Application Gateway that doesn't have a private IP, Ingresses with
appgw.ingress.kubernetes.io/use-private-ip: "true"
will be ignored. This will reflected in the controller logs and ingress events for those ingresses withNoPrivateIP
warning.
Usage
appgw.ingress.kubernetes.io/use-private-ip: "true"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/use-private-ip: "true"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 80
Backend Protocol
This annotation allows us to specify the protocol that Application Gateway should use while talking to the Pods. Supported Protocols: http
, https
Note
- While self-signed certificates are supported on Application Gateway, currently, AGIC only support
https
when Pods are using certificate signed by a well-known CA. - Make sure to not use port 80 with HTTPS and port 443 with HTTP on the Pods.
Usage
appgw.ingress.kubernetes.io/backend-protocol: "https"
Example
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-protocol: "https"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
serviceName: go-server-service
servicePort: 443