应用程序网关入口控制器的批注Annotations for Application Gateway Ingress Controller

简介Introductions

可以用任意键/值对来批注 Kubernetes 入口资源。The Kubernetes Ingress resource can be annotated with arbitrary key/value pairs. AGIC 依赖使用批注来对应用程序网关功能进行编程,而无法通过入口 YAML 配置这些功能。AGIC relies on annotations to program Application Gateway features, which are not configurable via the Ingress YAML. 入口批注适用于派生自入口资源的所有 HTTP 设置、后端池和侦听器。Ingress annotations are applied to all HTTP setting, backend pools, and listeners derived from an ingress resource.

支持的批注列表List of supported annotations

对于 AGIC 要观察的入口资源,必须使用 kubernetes.io/ingress.class: azure/application-gateway 对其进行批注。For an Ingress resource to be observed by AGIC, it must be annotated with kubernetes.io/ingress.class: azure/application-gateway. 只有在批注之后,AGIC 才能使用相关的入口资源。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-prefixappgw.ingress.kubernetes.io/backend-path-prefix string nil
appgw.ingress.kubernetes.io/ssl-redirectappgw.ingress.kubernetes.io/ssl-redirect bool false
appgw.ingress.kubernetes.io/connection-drainingappgw.ingress.kubernetes.io/connection-draining bool false
appgw.ingress.kubernetes.io/connection-draining-timeoutappgw.ingress.kubernetes.io/connection-draining-timeout int32(秒)int32 (seconds) 30
appgw.ingress.kubernetes.io/cookie-based-affinityappgw.ingress.kubernetes.io/cookie-based-affinity bool false
appgw.ingress.kubernetes.io/request-timeoutappgw.ingress.kubernetes.io/request-timeout int32(秒)int32 (seconds) 30
appgw.ingress.kubernetes.io/use-private-ipappgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/backend-protocolappgw.ingress.kubernetes.io/backend-protocol string http http, httpshttp, 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

在以上示例中,我们使用批注 appgw.ingress.kubernetes.io/backend-path-prefix: "/test/" 定义了名为 go-server-ingress-bkprefix 的入口资源。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/" . 该批注告知应用程序网关创建一个 HTTP 设置,该设置包含路径 /hello/test/ 的路径前缀重写。The annotation tells application gateway to create an HTTP setting, which will have a path prefix override for the path /hello to /test/.

备注

在以上示例中,我们只定义了一个规则。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 重定向TLS Redirect

可将应用程序网关配置为向其 HTTPS 对等方自动重定向 HTTP URL。Application Gateway can be configured to automatically redirect HTTP URLs to their HTTPS counterparts. 如果此批注存在且已正确配置 TLS,Kubernetes 入口控制器将创建采用某种重定向配置的路由规则,并将更改应用到应用程序网关。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. 创建的重定向是 HTTP 301 Moved PermanentlyThe 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:此批注可让用户指定是否启用连接清空。connection-draining: This annotation allows users to specify whether to enable connection draining. connection-draining-timeout:此批注可让用户指定超时,在此超时过后,应用程序网关将终止对清空后端终结点的请求。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 的相关性。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

使用专用 IPUse Private IP

此批注可用于指定是否在应用程序网关的专用 IP 上公开此终结点。This annotation allows us to specify whether to expose this endpoint on Private IP of Application Gateway.

备注

  • 应用程序网关不支持同一端口上的多个 IP(例如:80/443)。Application Gateway doesn't support multiple IPs on the same port (example: 80/443). HTTP 上使用带有批注 appgw.ingress.kubernetes.io/use-private-ip: "false" 的入口和带有 appgw.ingress.kubernetes.io/use-private-ip: "true" 的另一个入口会导致 AGIC 在更新应用程序网关时失败。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.
  • 对于没有专用 IP 的应用程序网关,将忽略带有 appgw.ingress.kubernetes.io/use-private-ip: "true" 的入口。For Application Gateway that doesn't have a private IP, Ingresses with appgw.ingress.kubernetes.io/use-private-ip: "true" will be ignored. 这些入口的控制器日志和入口事件中会通过 NoPrivateIP 警告反映这种情况。This will reflected in the controller logs and ingress events for those ingresses with NoPrivateIP 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

使用此注释可以指定应用程序网关在与 Pod 通信时应使用的协议。This annotation allows us to specify the protocol that Application Gateway should use while talking to the Pods. 支持的协议:httphttpsSupported Protocols: http, https

备注

  • 应用程序网关支持自签名的证书,不过,目前仅当 Pod 使用已知 CA 签名的证书时,AGIC 才支持 httpsWhile self-signed certificates are supported on Application Gateway, currently, AGIC only support https when Pods are using certificate signed by a well-known CA.
  • 请务必不要在 Pod 上将端口 80 与 HTTPS 配合使用,或者将端口 443 与 HTTP 配合使用。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