Application Gateway イングレス コントローラーの注釈

Kubernetes イングレス リソースには、任意のキー/値のペアを使用して注釈を付けることができます。 Application Gateway イングレス コントローラー (AGIC) は注釈に依存して、イングレス YAML を介して構成できない Azure Application Gateway 機能をプログラムします。 イングレス注釈は、イングレス リソースから派生したすべての 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 設定を作成するよう、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

バックエンド プロトコル

次の注釈を使用して、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 注釈と共に使用することもできます。

使用方法

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

書き換えルール セット カスタム リソース

Application Gateway を使用すると、選択した要求と応答のコンテンツを書き換えることができます。 この機能により、URL の変換、クエリ文字列パラメーターの変更、要求ヘッダーと応答ヘッダーの変更を行えます。 また、条件を追加することで、特定の条件が満たされた場合にのみ、URL または指定したヘッダーが確実に書き換えられるようにできます。 "書き換えルール セット カスタム リソース" によって、この機能を AGIC で利用できるようになります。

クライアントとサーバーは、HTTP ヘッダーを使用して、要求または応答に追加の情報を渡すことができます。 これらのヘッダーの書き換えによって、セキュリティ関連ヘッダー フィールドの追加 (HSTS や X-XSS-Protection など)、機密情報が漏れる可能性のある応答ヘッダー フィールドの削除、X-Forwarded-For ヘッダーからのポート情報の削除など、重要なタスクを実現できます。

URL 書き換え機能を使用すると、次のことができます。

• 要求 URL のホスト名、パス、およびクエリ文字列の書き換え。
• 全要求の URL の書き換え、または設定した 1 つ以上の条件に一致する要求の URL のみの書き換え。 これらの条件は、要求と応答のプロパティ (要求ヘッダー、応答ヘッダー、およびサーバー変数) に基づいています。
• 要求のルーティングを元の URL と書き換え後の URL のどちらに基づいて行うかを選択する。

使用方法

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 に設定します。