应用程序网关入口控制器的批注

你可以使用任意键/值对来对 Kubernetes Ingress 资源进行注释。 应用程序网关入口控制器 (AGIC) 依靠注释对无法通过入口 YAML 配置的 Azure 应用程序网关功能进行编程。 入口注释适用于派生自入口资源的所有 HTTP 设置、后端池和侦听器。

支持的批注列表

要让 AGIC 观察入口资源，必须使用 kubernetes.io/ingress.class: azure/application-gateway 对资源 进行注释。

注释键	值类型	默认值	允许的值
appgw.ingress.kubernetes.io/backend-path-prefix	string	nil
appgw.ingress.kubernetes.io/backend-hostname	string	nil
appgw.ingress.kubernetes.io/health-probe-hostname	string	127.0.0.1
appgw.ingress.kubernetes.io/health-probe-port	int32	80
appgw.ingress.kubernetes.io/health-probe-path	string	/
appgw.ingress.kubernetes.io/health-probe-status-code	string	200-399
appgw.ingress.kubernetes.io/health-probe-interval	int32	30（秒）
appgw.ingress.kubernetes.io/health-probe-timeout	int32	30（秒）
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold	int32	3
appgw.ingress.kubernetes.io/ssl-redirect	bool	false
appgw.ingress.kubernetes.io/connection-draining	bool	false
appgw.ingress.kubernetes.io/connection-draining-timeout	int32（秒）	30
appgw.ingress.kubernetes.io/use-private-ip	bool	false
appgw.ingress.kubernetes.io/override-frontend-port	bool	false
appgw.ingress.kubernetes.io/cookie-based-affinity	bool	false
appgw.ingress.kubernetes.io/request-timeout	int32（秒）	30
appgw.ingress.kubernetes.io/use-private-ip	bool	false
appgw.ingress.kubernetes.io/backend-protocol	string	http	http, https
appgw.ingress.kubernetes.io/hostname-extension	string	nil
appgw.ingress.kubernetes.io/waf-policy-for-path	string	nil
appgw.ingress.kubernetes.io/appgw-ssl-certificate	string	nil
appgw.ingress.kubernetes.io/appgw-ssl-profile	string	nil
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate	string	nil
appgw.ingress.kubernetes.io/rewrite-rule-set	string	nil
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
appgw.ingress.kubernetes.io/rule-priority	int32	nil

后端路径前缀

以下注释允许使用指定的前缀重写入口资源中指定的后端路径。 使用它来公开其端点与你在入口资源中公开服务所使用的端点名称不同的服务。

使用情况

appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>

示例

apiVersion: networking.k8s.io/v1
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/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

上述示例使用名为 appgw.ingress.kubernetes.io/backend-path-prefix: "/test/" 的注释定义了一个名为 go-server-ingress-bkprefix 的入口资源。 该注释指示应用程序网关创建一个 HTTP 设置，该设置具有 /hello 到 /test/ 路径的路径前缀替代。

该示例仅定义一个规则。 但是，此注释适用于整个入口资源。 因此，如果定义多个规则，应为每个指定路径设置后端路径前缀。 如果需要具有不同路径前缀的不同规则（甚至对于同一服务），那么你需要定义不同的入口资源。

后端主机名

请使用以下注释指定应用程序网关在与 Pod 通信时应使用的主机名。

使用情况

appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        backend:
          service:
            name: store-service
            port:
              number: 80
        pathType: Exact

自定义运行状况探测

你可以配置应用程序网关，以将自定义运行状况探测发送到后端地址池。 当存在以下注释时，Kubernetes 入口控制器会创建自定义探测来监控后端应用程序。 然后，控制器将更改应用于应用程序网关。

• health-probe-hostname：此注释允许在运行状况探测中使用自定义主机名。
• health-probe-port：此注释会为运行状况探测配置自定义端口。
• health-probe-path：此注释将定义运行状况探测的路径。
• health-probe-status-code：此注释允许运行状况探测接受不同的 HTTP 状态代码。
• health-probe-interval：此注释定义运行状况探测运行的间隔。
• health-probe-timeout：此注释定义运行状况探测在探测失败之前等待响应的时间。
• health-probe-unhealthy-threshold：此注释将定义在运行状况探测失败多少次后会将后端标记为不正常。

使用情况

appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
appgw.ingress.kubernetes.io/health-probe-port: 80
appgw.ingress.kubernetes.io/health-probe-path: "/"
appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
appgw.ingress.kubernetes.io/health-probe-interval: 30
appgw.ingress.kubernetes.io/health-probe-timeout: 30
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
    appgw.ingress.kubernetes.io/health-probe-port: 81
    appgw.ingress.kubernetes.io/health-probe-path: "/probepath"
    appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
    appgw.ingress.kubernetes.io/health-probe-interval: 31
    appgw.ingress.kubernetes.io/health-probe-timeout: 31
    appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

TLS 重定向

你可以将应用程序网关配置为自动将 HTTP URL 重定向到其 HTTPS 对应项。 当存在此注释并正确配置 TLS 时，Kubernetes 入口控制器会使用重定向配置创建路由规则。 然后，控制器将更改应用于你的应用程序网关实例。 创建的重定向是 HTTP 301 Moved Permanently。

使用情况

appgw.ingress.kubernetes.io/ssl-redirect: "true"

示例

apiVersion: networking.k8s.io/v1
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:
          service:
            name: websocket-repeater
            port:
              number: 80

连接清空

如果要使用连接排出，请使用以下注释：

• connection-draining：此注释指定是否启用连接排出。
• connection-draining-timeout：此注释指定超时，超过此超时后，应用程序网关将终止对排出后端终结点的请求。

使用情况

appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"

示例

apiVersion: networking.k8s.io/v1
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/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

基于 Cookie 的相关性

使用以下注释启用基于 Cookie 的相关性。

使用情况

appgw.ingress.kubernetes.io/cookie-based-affinity: "true"

示例

apiVersion: networking.k8s.io/v1
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/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

请求超时

使用以下注释指定请求超时（以秒为单位）。 超时后，如果未收到响应，应用程序网关请求失败。

使用情况

appgw.ingress.kubernetes.io/request-timeout: "20"

示例

apiVersion: networking.k8s.io/v1
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/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

使用专用 IP

使用以下注释指定是否在应用程序网关的专用 IP 地址上公开此终结点。

对于没有专用 IP 的应用程序网关实例，将忽略 appgw.ingress.kubernetes.io/use-private-ip: "true" 的入口。 这些入口的控制器日志和入口事件会显示 NoPrivateIP 警告。

使用情况

appgw.ingress.kubernetes.io/use-private-ip: "true"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-privateip
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/use-private-ip: "true"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

重写前端端口

使用以下注释将前端侦听器配置为对 HTTP 使用 80 以外的端口，对 HTTPS 使用 443 以外的端口。

如果端口在应用程序网关授权范围内（1 到 64999），则会在此特定端口上创建侦听器。 如果在注释中设置了无效的端口或无端口，则配置将使用默认值 80 或 443。

使用情况

appgw.ingress.kubernetes.io/override-frontend-port: "port"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-overridefrontendport
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/override-frontend-port: "8080"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        backend:
          service:
            name: store-service
            port:
              number: 80
        pathType: Exact

后端协议

使用以下内容指定应用程序网关在与 Pod 通信时应使用的协议。 支持的协议包括 HTTP 和 HTTPS。

尽管应用程序网关支持自签名证书，但 AGIC 目前仅在 Pod 使用由知名证书颁发机构签名的证书时才支持 HTTPS。

不要在 Pod 上将端口 80 与 HTTPS 配合使用，或者将端口 443 与 HTTP 配合使用。

使用情况

appgw.ingress.kubernetes.io/backend-protocol: "https"

示例

apiVersion: networking.k8s.io/v1
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: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 443

主机名扩展

你可以将应用程序网关配置为接受多个主机名。 请使用 hostname-extension 注释来定义多个主机名，包括通配符主机名。 此操作会将主机名附加到前端侦听器的入口 spec.rules.host 信息中定义的 FQDN 上，因此将其 配置为多站点侦听器。

使用情况

appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-multisite
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
spec:
  rules:
  - host: contoso.com
    http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 443

前面的示例将侦听器配置为接受主机名 hostname1.contoso.com 和 hostname2.contoso.com 的流量。

路径的 WAF 策略

使用以下注释将现有 Web 应用程序防火墙 (WAF) 策略附加到要进行注释的 Kubernetes 入口资源中的主机列表路径。 WAF 策略会同时应用于 /ad-server 和 /auth URL。

使用情况

appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0000-bb11-2222-33cc-444444dddddd/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ad-server-ingress
  namespace: commerce
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/abcd/resourceGroups/rg/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/adserver"
spec:
  rules:
  - http:
      paths:
      - path: /ad-server
        backend:
          service:
            name: ad-server
            port:
              number: 80
        pathType: Exact
      - path: /auth
        backend:
          service:
            name: auth-server
            port:
              number: 80
        pathType: Exact

应用程序网关 SSL 证书

你可以从本地 PFX 证书文件或对未版本化的 Azure Key Vault 机密 ID 的引用对应用程序网关配置 SSL 证书。 当注释与证书名称一起存在并且证书预安装在应用程序网关中时，Kubernetes 入口控制器会创建一个带有 HTTPS 侦听器的路由规则，并将更改应用于应用程序网关实例。 在 SSL 重定向的情况下，你还可以将 appgw-ssl-certificate 注释与 ssl-redirect 注释一起使用。

使用情况

appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

应用程序网关 SSL 配置文件

你可以在应用程序网关实例上为每个侦听器配置 SSL 配置文件。 当注释与配置文件名称一起存在并且配置文件预安装在应用程序网关中时，Kubernetes 入口控制器会创建一个带有 HTTPS 侦听器的路由规则，并将更改应用于应用程序网关实例。

使用情况

appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
    appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

应用程序网关受信任的根证书

你现在可以将自己的根证书配置为通过 AGIC 信任应用程序网关。 你可以将 appgw-trusted-root-certificate 注释与 backend-protocol 批注一起使用，来指示端到端 SSL 加密。 如果指定多个根证书，请用逗号分隔它们；例如，name-of-my-root-cert1,name-of-my-root-cert2。

使用情况

appgw.ingress.kubernetes.io/backend-protocol: "https"
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-certificate
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/backend-protocol: "https"
    appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"
spec:
  rules:
  - host: www.contoso.com
    http:
      paths:
      - backend:
          service:
            name: websocket-repeater
            port:
              number: 80

重写规则集

使用以下注释将现有重写规则集分配给相应的请求路由规则。

使用情况

appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-bkprefix
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/rewrite-rule-set: add-custom-response-header
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 8080

规则优先级

以下注释允许应用程序网关入口控制器显式设置关联的请求路由规则的优先级。

使用情况

appgw.ingress.kubernetes.io/rule-priority:

示例

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-rulepriority
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/rule-priority: 10
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 8080

前面的示例设置的请求路由规则的优先级为 10。