Merge pull request #216060 from MGoedtel/task1959640

Revised article to align with deprecation of K8s extensions/v1beta1

Author: v-regandowner

articles/application-gateway/ingress-controller-annotations.md

@@ -5,35 +5,33 @@ services: application-gateway
 author: greg-lindsay
 ms.service: application-gateway
 ms.topic: article
-ms.date: 3/18/2022
+ms.date: 10/26/2022
 ms.author: greglin
 ---
 
-# Annotations for Application Gateway Ingress Controller 
+# 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.
+The Kubernetes Ingress resource can be annotated with arbitrary key/value pairs. AGIC relies on annotations to program Application Gateway features, which aren't configurable using the Ingress YAML. Ingress annotations are applied to all HTTP settings, 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.
+For an Ingress resource to be observed by AGIC, it **must be annotated** with `kubernetes.io/ingress.class: azure/application-gateway`. Only then AGIC works with the Ingress resource in question.
 
-| Annotation Key | Value Type | Default Value | Allowed Values
+| Annotation Key | Value Type | Default Value | Allowed Values |
 | -- | -- | -- | -- |
-| [appgw.ingress.kubernetes.io/backend-path-prefix](#backend-path-prefix) | `string` | `nil` | |
+| [appgw.ingress.kubernetes.io/backend-path-prefix](#backend-path-prefix) | `string` | `nil` ||
 | [appgw.ingress.kubernetes.io/ssl-redirect](#tls-redirect) | `bool` | `false` | |
-| [appgw.ingress.kubernetes.io/connection-draining](#connection-draining) | `bool` | `false` | |
-| [appgw.ingress.kubernetes.io/connection-draining-timeout](#connection-draining) | `int32` (seconds) | `30` | |
-| [appgw.ingress.kubernetes.io/cookie-based-affinity](#cookie-based-affinity) | `bool` | `false` | |
-| [appgw.ingress.kubernetes.io/request-timeout](#request-timeout) | `int32` (seconds) | `30` | |
-| [appgw.ingress.kubernetes.io/use-private-ip](#use-private-ip) | `bool` | `false` | |
+| [appgw.ingress.kubernetes.io/connection-draining](#connection-draining) | `bool` | `false` ||
+| [appgw.ingress.kubernetes.io/connection-draining-timeout](#connection-draining) | `int32` (seconds) | `30` ||
+| [appgw.ingress.kubernetes.io/cookie-based-affinity](#cookie-based-affinity) | `bool` | `false` ||
+| [appgw.ingress.kubernetes.io/request-timeout](#request-timeout) | `int32` (seconds) | `30` ||
+| [appgw.ingress.kubernetes.io/use-private-ip](#use-private-ip) | `bool` | `false` ||
 | [appgw.ingress.kubernetes.io/backend-protocol](#backend-protocol) | `string` | `http` | `http`, `https` |
-| [appgw.ingress.kubernetes.io/rewrite-rule-set](#rewrite-rule-set) | `string` | `nil`  | |
+| [appgw.ingress.kubernetes.io/rewrite-rule-set](#rewrite-rule-set) | `string` | `nil`  ||
 
 ## 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.
+The following annotation allows the backend path specified in an ingress resource to be rewritten with prefix specified in this annotation. It allows users to expose services whose endpoints are different than endpoint names used to expose a service in an ingress resource.
 
 ### Usage
 
@@ -44,7 +42,7 @@ appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>
 ### Example
 
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-bkprefix
@@ -57,22 +55,26 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 80
+          service:
+            name: go-server-service
+            port:
+              number: 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.
+In the previous example, you've 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 has a path prefix override for the path `/hello` to `/test/`.
+
+> [!NOTE]
+> In the above example, only one rule is defined. However, the annotations are applicable to the entire ingress resource, so if a user defined multiple rules, the backend path prefix would be set up for each of the paths specified. 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](./redirect-overview.md)
 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](./redirect-http-to-https-portal.md#add-a-routing-rule-with-a-redirection-configuration)
-and apply the changes to your Application Gateway. The redirect created will be HTTP `301 Moved Permanently`.
+controller creates a [routing rule with a redirection configuration](./redirect-http-to-https-portal.md#add-a-routing-rule-with-a-redirection-configuration)
+and applies the changes to your Application Gateway. The redirect created will be HTTP `301 Moved Permanently`.
 
 ### Usage
 
@@ -83,7 +85,7 @@ appgw.ingress.kubernetes.io/ssl-redirect: "true"
 ### Example
 
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-redirect
@@ -101,14 +103,16 @@ spec:
     http:
       paths:
       - backend:
-          serviceName: websocket-repeater
-          servicePort: 80
+          service:
+            name: websocket-repeater
+            port:
+              number: 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.
+`connection-draining`: This annotation allows us to specify whether to enable connection draining.
+`connection-draining-timeout`: This annotation allows us to specify a timeout, after which Application Gateway terminates the requests to the draining backend endpoint.
 
 ### Usage
 
@@ -120,7 +124,7 @@ appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
 ### Example
 
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-drain
@@ -134,14 +138,17 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 80
+          service:
+            name: go-server-service
+            port:
+              number: 80
 ```
 
 ## Cookie Based Affinity
 
-This annotation allows to specify whether to enable cookie based affinity.
+The following annotation allows you to specify whether to enable cookie based affinity.
 
 ### Usage
 
@@ -152,7 +159,7 @@ appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
 ### Example
 
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-affinity
@@ -165,14 +172,17 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 80
+          service:
+            name: go-server-service
+            port:
+              number: 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.
+The following annotation allows you to specify the request timeout in seconds, after which Application Gateway fails the request if response is not received.
 
 ### Usage
 
@@ -183,7 +193,7 @@ appgw.ingress.kubernetes.io/request-timeout: "20"
 ### Example
 
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-timeout
@@ -196,28 +206,32 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 80
+          service:
+            name: go-server-service
+            port:
+              number: 80
 ```
 
 ## Use Private IP
 
-This annotation allows us to specify whether to expose this endpoint on Private IP of Application Gateway.
+The following annotation allows you 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 with `appgw.ingress.kubernetes.io/use-private-ip: "true"` on `HTTP` 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 with `NoPrivateIP` warning.
-
+> * 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 with `appgw.ingress.kubernetes.io/use-private-ip: "true"` on `HTTP` will cause AGIC to fail while updating the Application Gateway.
+> * For Application Gateway that doesn't have a private IP, Ingresses with `appgw.ingress.kubernetes.io/use-private-ip: "true"` is ignored. This is reflected in the controller logs and ingress events for those ingresses with `NoPrivateIP` warning.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/use-private-ip: "true"
 ```
 
 ### Example
+
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-timeout
@@ -230,27 +244,33 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 80
+          service:
+            name: go-server-service
+            port:
+              number: 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`
+The following annotation allows you to specify the protocol that Application Gateway should use while communicating with the pods. Supported Protocols are `http` and `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.
+> While self-signed certificates are supported on Application Gateway, currently AGIC only supports `https` when pods are using a certificate signed by a well-known CA.
+>
+> Don't use port 80 with HTTPS and port 443 with HTTP on the pods.
 
 ### Usage
+
 ```yaml
 appgw.ingress.kubernetes.io/backend-protocol: "https"
 ```
 
 ### Example
+
 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: go-server-ingress-timeout
@@ -263,14 +283,17 @@ spec:
   - http:
       paths:
       - path: /hello/
+        pathType: Exact
         backend:
-          serviceName: go-server-service
-          servicePort: 443
+          service:
+            name: go-server-service
+            port:
+              number: 443
 ```
 
 ## Rewrite Rule Set
 
-This annotation allows you to assign an existing rewrite rule set to the corresponding request routing rule.
+The following annotation allows you to assign an existing rewrite rule set to the corresponding request routing rule.
 
 ### Usage