Application Gateway イングレス コントローラーの注釈Annotations for Application Gateway Ingress Controller

はじめにIntroductions

Kubernetes イングレス リソースには、任意のキー/値のペアを使用して注釈を付けることができます。The Kubernetes Ingress resource can be annotated with arbitrary key/value pairs. AGIC は、イングレス YAML を介して構成できない Application Gateway 機能をプログラムするために、注釈に依存します。AGIC relies on annotations to program Application Gateway features, which are not configurable via the Ingress YAML. イングレス注釈は、イングレス リソースから派生したすべての HTTP 設定、バックエンド プール、およびリスナーに適用されます。Ingress annotations are applied to all HTTP setting, backend pools, and listeners derived from an ingress resource.

サポートされている注釈の一覧List of supported annotations

イングレス リソースを AGIC によって監視するためには、kubernetes.io/ingress.class: azure/application-gateway を使用してリソースに 注釈を付ける必要がありますFor an Ingress resource to be observed by AGIC, it must be annotated with kubernetes.io/ingress.class: azure/application-gateway. そうしないと、AGIC は問題のイングレス リソースに対して機能しません。Only then AGIC will work with the Ingress resource in question.

注釈キーAnnotation Key 値の種類Value Type 既定値Default Value 使用できる値Allowed Values
appgw.ingress.kubernetes.io/backend-path-prefixappgw.ingress.kubernetes.io/backend-path-prefix string nil
appgw.ingress.kubernetes.io/ssl-redirectappgw.ingress.kubernetes.io/ssl-redirect bool false
appgw.ingress.kubernetes.io/connection-drainingappgw.ingress.kubernetes.io/connection-draining bool false
appgw.ingress.kubernetes.io/connection-draining-timeoutappgw.ingress.kubernetes.io/connection-draining-timeout int32 (秒)int32 (seconds) 30
appgw.ingress.kubernetes.io/cookie-based-affinityappgw.ingress.kubernetes.io/cookie-based-affinity bool false
appgw.ingress.kubernetes.io/request-timeoutappgw.ingress.kubernetes.io/request-timeout int32 (秒)int32 (seconds) 30
appgw.ingress.kubernetes.io/use-private-ipappgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/backend-protocolappgw.ingress.kubernetes.io/backend-protocol string http http, httpshttp, https

バックエンド パス プレフィックスBackend Path Prefix

この注釈を使用すると、イングレス リソースで指定されたバックエンド パスを、この注釈で指定されたプレフィックスで書き換えることができます。This annotation allows the backend path specified in an ingress resource to be rewritten with prefix specified in this annotation. これによりユーザーは、サービスのエンドポイントが、イングレス リソースでサービスを公開するために使用されるエンドポイント名と異なっている場合でも、そのサービスを公開できます。This allows users to expose services whose endpoints are different than endpoint names used to expose a service in an ingress resource.

使用法Usage

appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>

Example

apiVersion: extensions/v1beta1
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/
        backend:
          serviceName: go-server-service
          servicePort: 80

上の例では、注釈 appgw.ingress.kubernetes.io/backend-path-prefix: "/test/" を使用して、go-server-ingress-bkprefix という名前のイングレス リソースを定義しました。In the example above, we have defined an ingress resource named go-server-ingress-bkprefix with an annotation appgw.ingress.kubernetes.io/backend-path-prefix: "/test/" . この注釈は、パス /hello から /test/ へのパス プレフィックス オーバーライドを含む HTTP 設定を作成するよう、アプリケーション ゲートウェイに指示します。The annotation tells application gateway to create an HTTP setting, which will have a path prefix override for the path /hello to /test/.

注意

上記の例では、1 つの規則のみを定義しています。In the above example we have only one rule defined. ただし、注釈はイングレス リソース全体に適用可能なため、ユーザーが複数の規則を定義した場合、指定されたパスのそれぞれに対してバックエンド パス プレフィックスが設定されます。However, the annotations are applicable to the entire ingress resource, so if a user had defined multiple rules, the backend path prefix would be set up for each of the paths specified. したがって、(同じサービスに対するものであっても) パス プレフィックスが異なっている別々の規則が必要な場合、ユーザーは別々のイングレス リソースを定義する必要があります。Thus, if a user wants different rules with different path prefixes (even for the same service) they would need to define different ingress resources.

TLS リダイレクトTLS Redirect

対応する HTTPS に HTTP URL を自動的にリダイレクトするように Application Gateway を構成できますApplication Gateway can be configured to automatically redirect HTTP URLs to their HTTPS counterparts. この注釈が存在し、TLS が正しく構成されている場合、Kubernetes イングレス コントローラーは、リダイレクト構成を持つルーティング規則を作成し、変更を Application Gateway に適用します。When this annotation is present and TLS is properly configured, Kubernetes Ingress controller will create a routing rule with a redirection configuration and apply the changes to your Application Gateway. 作成されるリダイレクトは HTTP 301 Moved Permanently になります。The redirect created will be HTTP 301 Moved Permanently.

使用法Usage

appgw.ingress.kubernetes.io/ssl-redirect: "true"

Example

apiVersion: extensions/v1beta1
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:
          serviceName: websocket-repeater
          servicePort: 80

接続のドレインConnection Draining

connection-draining: この注釈によりユーザーは、接続のドレインを有効にするかどうかを指定できます。connection-draining: This annotation allows users to specify whether to enable connection draining. connection-draining-timeout: この注釈により、ユーザーはタイムアウトを指定できます。この時間の経過後に Application Gateway は、ドレイン状態のバックエンド エンドポイントへの要求を終了します。connection-draining-timeout: This annotation allows users to specify a timeout after which Application Gateway will terminate the requests to the draining backend endpoint.

使用法Usage

appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"

Example

apiVersion: extensions/v1beta1
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/
        backend:
          serviceName: go-server-service
          servicePort: 80

この注釈では、Cookie ベースのアフィニティを有効にするかどうかを指定できます。This annotation allows to specify whether to enable cookie based affinity.

使用法Usage

appgw.ingress.kubernetes.io/cookie-based-affinity: "true"

Example

apiVersion: extensions/v1beta1
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/
        backend:
          serviceName: go-server-service
          servicePort: 80

要求タイムアウトRequest Timeout

この注釈では、要求タイムアウトを秒単位で指定できます。この時間を過ぎても応答が受信されない場合、Application Gateway は要求を失敗と見なします。This annotation allows to specify the request timeout in seconds after which Application Gateway will fail the request if response is not received.

使用法Usage

appgw.ingress.kubernetes.io/request-timeout: "20"

Example

apiVersion: extensions/v1beta1
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/
        backend:
          serviceName: go-server-service
          servicePort: 80

プライベート IP を使用Use Private IP

この注釈では、このエンドポイントを Application Gateway のプライベート IP で公開するかどうかを指定できます。This annotation allows us to specify whether to expose this endpoint on Private IP of Application Gateway.

注意

  • Application Gateway では、同じポート上の複数の IP (例: 80/443) はサポートされません。Application Gateway doesn't support multiple IPs on the same port (example: 80/443). HTTP で、appgw.ingress.kubernetes.io/use-private-ip: "false" という注釈を持つイングレスと、appgw.ingress.kubernetes.io/use-private-ip: "true" という注釈を持つ別のイングレスがある場合、AGIC は Application Gateway の更新に失敗します。Ingress with annotation appgw.ingress.kubernetes.io/use-private-ip: "false" and another with appgw.ingress.kubernetes.io/use-private-ip: "true" on HTTP will cause AGIC to fail in updating the Application Gateway.
  • プライベート IP を持たない Application Gateway では、appgw.ingress.kubernetes.io/use-private-ip: "true" という注釈を持つイングレスは無視されます。For Application Gateway that doesn't have a private IP, Ingresses with appgw.ingress.kubernetes.io/use-private-ip: "true" will be ignored. NoPrivateIP 警告が有効なイングレスの場合、これはコントローラーのログとイングレス イベントに反映されます。This will reflected in the controller logs and ingress events for those ingresses with NoPrivateIP warning.

使用法Usage

appgw.ingress.kubernetes.io/use-private-ip: "true"

Example

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  namespace: test-ag
  annotations:
    kubernetes.io/ingress.class: azure/application-gateway
    appgw.ingress.kubernetes.io/use-private-ip: "true"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        backend:
          serviceName: go-server-service
          servicePort: 80

バックエンド プロトコルBackend Protocol

この注釈では、ポッドとの通信中に Application Gateway が使用するプロトコルを指定できます。This annotation allows us to specify the protocol that Application Gateway should use while talking to the Pods. サポートされるプロトコル: httphttpsSupported Protocols: http, https

注意

  • 自己署名証明書は Application Gateway でサポートされていますが、現在は、よく知られた CA によって署名された証明書をポッドが使用している場合、AGIC は https のみをサポートします。While self-signed certificates are supported on Application Gateway, currently, AGIC only support https when Pods are using certificate signed by a well-known CA.
  • ポッドでは、HTTPS ではポート 80、HTTP ではポート 443 を使用しないようにしてください。Make sure to not use port 80 with HTTPS and port 443 with HTTP on the Pods.

使用法Usage

appgw.ingress.kubernetes.io/backend-protocol: "https"

Example

apiVersion: extensions/v1beta1
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: /hello/
        backend:
          serviceName: go-server-service
          servicePort: 443