應用程式閘道輸入控制器的註釋
您可以使用任意索引鍵/值組來標註 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 的輸入資源。 這個註釋會指示應用程式閘道建立會將路徑 /hello 的路徑前置詞覆寫為 /test/ 的 HTTP 設定。
此範例只會定義一個規則。 不過，註釋會套用至整個輸入資源。 因此，如果您定義多個規則，則會為每個指定的路徑設定後端路徑前置詞。 如果您想要擁有有不同路徑前置詞的不同規則 (即使是針對相同服務)，便需要定義不同的輸入資源。
後端主機名稱
使用下列註釋可指定應用程式閘道在與 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 未設定版本之秘密識別碼的參考，將 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
重寫規則集自訂資源
注意
適用於容器的應用程式閘道 (部分機器翻譯) 的發行版本引進了許多效能、復原能力和功能變更。 請考慮使用適用於容器的應用程式閘道來進行下一個部署。
您可以在這篇關於閘道 API 的文章中和這篇關於輸入 API 的文章中找到適用於容器的應用程式閘道的 URL 重寫規則。 您可以在這篇關於閘道 API 的文章中找到適用於容器的應用程式閘道的標頭重寫規則。
應用程式閘道可讓您重寫要求和回應的選定內容。 透過此功能，您可以轉譯 URL、變更查詢字串參數，以及修改要求和回應標頭。 您還可以使用此功能來新增條件，以確保僅在符合特定條件時，才重寫 URL 或指定的標頭。 重寫規則集自訂資源會將這項功能帶到 AGIC。
HTTP 標頭可讓用戶端和伺服器透過要求或回應傳遞其他資訊。 藉由重寫這些標頭，您可以完成各項重要工作，例如新增安全性相關標頭欄位 (例如 HSTS 或 X-XSS-Protection)、移除可能會顯示敏感性資訊的回應標頭欄位，以及從 X-Forwarded-For 標頭中移除連接埠資訊。
透過 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 的優先順序。