Application Gateway イングレス コントローラーの注釈
Kubernetes イングレス リソースには、任意のキー/値のペアを使用して注釈を付けることができます。 Application Gateway イングレス コントローラー (AGIC) は注釈に依存して、イングレス YAML を介して構成できない Azure Application Gateway 機能をプログラムします。 イングレス注釈は、イングレス リソースから派生したすべての HTTP 設定、バックエンド プール、およびリスナーに適用されます。
ヒント
「Application Gateway for Containers とは」も参照してください。
サポートされている注釈の一覧
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 設定を作成するよう、Application Gateway に指示します。
この例では、1 つの規則のみを定義します。 ただし、注釈はイングレス リソース全体に適用されます。 したがって、複数の規則を定義する場合は、指定された各パスのバックエンド パス プレフィックスを設定します。 (同じサービスに対するものであっても) パス プレフィックスが異なっている別々の規則が必要な場合、別々のイングレス リソースを定義する必要があります。
バックエンド ホスト名
次の注釈を使用して、Application Gateway がポッドとの通信時に使用するホスト名を指定します。
使用方法
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
カスタム正常性プローブ
カスタム正常性プローブをバックエンド アドレス プールに送信するように Application Gateway を構成できます。 次の注釈が存在する場合、Kubernetes イングレス コントローラーはカスタム プローブを作成し、バックエンド アプリケーションを監視します。 その後、コントローラーによって Application Gateway に変更が適用されます。
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 を自動的にリダイレクトするように Application Gateway を構成できます。 この注釈が存在し、TLS が正しく構成されている場合、Kubernetes イングレス コントローラーは、リダイレクト構成を持つルーティング規則を作成します。 その後、コントローラーによって Application Gateway インスタンスに変更が適用されます。 作成されたリダイレクトは 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: この注釈はタイムアウトを指定します。この時間の経過後に Application Gateway は、ドレイン状態のバックエンド エンドポイントへの要求を終了します。
使用方法
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
Request Timeout
次の注釈を使用して、要求タイムアウトを秒単位で指定します。 タイムアウト後、応答が受信されない場合、Application Gateway は要求を失敗します。
使用方法
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 を使用
次の注釈を使用して、このエンドポイントを Application Gateway のプライベート IP で公開するかどうかを指定します。
プライベート IP を持たない Application Gateway インスタンスの場合、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 以外のポートを使用するようにフロントエンド リスナーを構成します。
ポートが Application Gateway の承認された範囲内 (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
Note
外部要求の宛先は http://somehost ではなく http://somehost:8080 とする必要があります。
バックエンド プロトコル
次の注釈を使用して、Application Gateway がポッドと通信するときに使用するプロトコルを指定します。 サポートされているプロトコルは、HTTP および HTTPS です。
自己署名証明書は Application Gateway でサポートされていますが、AGIC は現在、ポッドが既知の証明機関によって署名された証明書を使用する場合にのみ HTTPS をサポートしています。
ポッドでは、HTTPS ではポート 80、HTTP ではポート 443 を使用しないようにしてください。
使用方法
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
ホスト名拡張
複数のホスト名を受け入れるように Application Gateway を構成できます。 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
Application Gateway SSL 証明書
SSL 証明書を Application Gateway に対して構成するには、ローカルの PFX 証明書ファイルから行うことも、Azure Key Vault バージョン指定なしシークレット ID への参照を使用することもできます。 証明書名を指定した注釈が存在しているときに、その証明書が Application Gateway にプレインストールされている場合は、HTTPS リスナーを使用するルーティング規則が Kubernetes イングレス コントローラーによって作成され、その変更が Application Gateway インスタンスに適用されます。 SSL リダイレクトの場合は、appgw-ssl-certificate 注釈を ssl-redirect 注釈と共に使用することもできます。
Note
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
Application Gateway SSL プロファイル
リスナーごとに Application Gateway インスタンスで SSL プロファイルを構成できます。 プロファイル名を指定した注釈が存在しているときに、そのプロファイルが Application Gateway にプレインストールされている場合は、HTTPS リスナーを使用するルーティング規則が Kubernetes イングレス コントローラーによって作成され、その変更が Application Gateway インスタンスに適用されます。
使用方法
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
Application Gateway 信頼されたルート証明書
AGIC 経由で信頼されるために自身のルート証明書を Application Gateway に対して構成できるようになりました。 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
書き換えルール セット カスタム リソース
Note
Application Gateway for Containers のリリースでは、パフォーマンス、回復性、機能に関する多数の変更が導入されています。 Application Gateway for Containers を次回のデプロイに使用することを検討してください。
Application Gateway for Containers の URL 書き換え規則については、ゲートウェイ API に関する記事およびイングレス API に関する記事を参照してください。 Application Gateway for Containers のヘッダー書き換え規則については、ゲートウェイ API に関する記事を参照してください。
Application Gateway を使用すると、選択した要求と応答のコンテンツを書き換えることができます。 この機能により、URL の変換、クエリ文字列パラメーターの変更、要求ヘッダーと応答ヘッダーの変更を行えます。 また、条件を追加することで、特定の条件が満たされた場合にのみ、URL または指定したヘッダーが確実に書き換えられるようにできます。 "書き換えルール セット カスタム リソース" によって、この機能を AGIC で利用できるようになります。
クライアントとサーバーは、HTTP ヘッダーを使用して、要求または応答に追加の情報を渡すことができます。 これらのヘッダーの書き換えによって、セキュリティ関連ヘッダー フィールドの追加 (HSTS や X-XSS-Protection など)、機密情報が漏れる可能性のある応答ヘッダー フィールドの削除、X-Forwarded-For ヘッダーからのポート情報の削除など、重要なタスクを実現できます。
URL 書き換え機能を使用すると、次のことができます。
- 要求 URL のホスト名、パス、およびクエリ文字列の書き換え。
- 全要求の URL の書き換え、または設定した 1 つ以上の条件に一致する要求の URL のみの書き換え。 これらの条件は、要求と応答のプロパティ (要求ヘッダー、応答ヘッダー、およびサーバー変数) に基づいています。
- 要求のルーティングを元の URL と書き換え後の URL のどちらに基づいて行うかを選択する。
Note
この機能は 1.6.0-rc1 以降でサポートされています。 Application Gateway に対して既存の書き換えルール セットを使用できる、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
ルールの優先順位
この注釈を使用すると、Application Gateway イングレス コントローラーが、関連付けられている要求ルーティング規則の優先順位を明示的に設定できます。
使用方法
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 に設定します。