应用程序网关入口控制器的批注
你可以使用任意键/值对来对 Kubernetes Ingress 资源进行注释。 应用程序网关入口控制器 (AGIC) 依靠注释对无法通过入口 YAML 配置的 Azure 应用程序网关功能进行编程。 入口注释适用于派生自入口资源的所有 HTTP 设置、后端池和侦听器。
支持的批注列表
要让 AGIC 观察入口资源,必须使用 kubernetes.io/ingress.class: azure/application-gateway
对资源 进行注释。
后端路径前缀
以下注释允许使用指定的前缀重写入口资源中指定的后端路径。 使用它来公开其端点与你在入口资源中公开服务所使用的端点名称不同的服务。
使用情况
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
注意
外部请求需要针对 http://somehost:8080
而不是 http://somehost
。
后端协议
使用以下内容指定应用程序网关在与 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/00000000-0000-0000-0000-000000000000/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
注释一起使用。
注意
当入口中同时定义 TLS 规范时,appgw-ssl-certificate
注释会被忽略。 如果希望不同的主机具有不同的证书(终止多个 TLS 证书),则需要定义不同的入口资源。
使用情况
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。