你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
应用程序网关入口控制器的批注
可以使用任意键/值对来批注 Kubernetes 入口资源。 应用程序网关入口控制器 (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 重定向
可将应用程序网关配置为向其 HTTPS 对等方自动重定向 HTTP URL。 如果存在此注释并且 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
重写前端端口
使用以下注释将前端侦听器配置为使用除 80 以外的端口（对于 HTTP）和 443（对于 HTTPS）。
如果端口位于应用程序网关授权范围内（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/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 证书
可以使用两种方法将 SSL 证书配置为应用程序网关，通过本地 PFX 证书文件，或者通过引用 Azure 密钥保管库的未版本化机密 ID。 当注释包含证书名称且证书已在应用程序网关中预安装时，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
重写规则集自定义资源
注意
适用于容器的应用程序网关的发布引入了许多性能、复原能力和功能变化。 请考虑使用适用于容器的应用程序网关进行下一次部署。
可以在此有关入口 API 的文章和此有关入口 API 的文章中找到适用于容器的应用程序网关的 URL 重写规则。 可以在此有关入口 API 的文章中找到适用于容器的应用程序网关的标头重写规则。
可以通过应用程序网关重写请求和响应的所选内容。 使用此功能，你可以转换 URL、更改查询字符串参数并修改请求标头和响应标头。 还可以使用此功能来添加条件，确保只有在满足特定条件的情况下才能重写 URL 或指定的标头。 重写规则集自定义资源将此功能引入了 AGIC。
HTTP 标头可让客户端和服务器连同请求或响应一起传递附加的信息。 重写这些标头可以完成重要的任务，例如，添加安全相关的标头字段（如 HSTS 和 X-XSS-Protection）、删除可能透露敏感信息的响应标头字段，以及从 X-Forwarded-For 标头中删除端口信息。
使用 URL 重写功能，可以：
- 重写请求 URL 的主机名、路径和查询字符串。
- 选择重写所有请求的 URL，或者只重写与所设置的一个或多个条件匹配的要求的 URL。 这些条件基于请求和响应属性（请求头、响应头和服务器变量）。
- 选择基于原始 URL 或重写 URL 传递请求。
注意
自 1.6.0-rc1 起支持此功能。 请使用 appgw.ingress.kubernetes.io/rewrite-rule-set，它允许在应用程序网关上使用现有的重写规则集。
使用情况
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
示例
apiVersion: appgw.ingress.azure.io/v1beta1
kind: AzureApplicationGatewayRewrite
metadata:
name: my-rewrite-rule-set-custom-resource
spec:
rewriteRules:
- name: rule1
ruleSequence: 21
conditions:
- ignoreCase: false
negate: false
variable: http_req_Host
pattern: example.com
actions:
requestHeaderConfigurations:
- actionType: set
headerName: incoming-test-header
headerValue: incoming-test-value
responseHeaderConfigurations:
- actionType: set
headerName: outgoing-test-header
headerValue: outgoing-test-value
urlConfiguration:
modifiedPath: "/api/"
modifiedQueryString: "query=test-value"
reroute: false
规则优先级
以下注释允许应用程序网关入口控制器显式设置关联的请求传递规则的优先级。
使用情况
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。