NCP では、TLS 仕様の Ingress と、TLS 仕様でない Ingress 用に、レイヤー 7 のロード バランサが 1 つずつ作成されます。また、Ingress のスケーリングを処理するために、CRD (CustomResourceDefinitions) を作成することもできます。

次の点に注意してください。
  • すべての Ingress が、単一の IP アドレスを取得します。
  • Ingress リソースには、ncp.ini[nsx_v3] セクションにある external_ip_pools オプションで指定された外部 IP アドレス プールから、IP アドレスが割り当てられます。ロード バランサは、この IP アドレスと HTTP および HTTPS ポート(80 と 443)上に公開されます。
  • Ingress リソースには、ncp.ini[nsx_v3] セクションにある external_ip_pools_lb オプションで指定された外部 IP アドレス プールから、IP アドレスが割り当てられます。external_ip_pools_lb オプションがない場合は、external_ip_pools で指定されたプールが使用されます。ロード バランサは、この IP アドレスと HTTP および HTTPS ポート(80 と 443)上に公開されます。
  • 設定を変更して NCP を再起動することで、異なる IP アドレス プールに変更できます。
  • TLS 用のデフォルト証明書を指定できます。証明書の生成および NCP ポッドへの証明書のマウントについては、以下を参照してください。
  • TLS 仕様でない Ingress は、HTTP 仮想サーバ(ポート 80)上でホストされます。
  • TLS 仕様の Ingress は、HTTPS 仮想サーバ(ポート 443)上でホストされます。ロード バランサは SSL サーバとして機能し、クライアントの SSL 接続を終了します。
  • Ingress への TLS セクションの追加または削除はサポートされています。Ingress の仕様から tls キーが削除されると、Ingress ルールは HTTPS 仮想サーバ(ポート 443)から HTTP 仮想サーバ(ポート 80)に転送されます。同様に、Ingress の仕様に tls キーが追加されると、Ingress ルールは HTTP 仮想サーバ(ポート 80)から HTTPS 仮想サーバ(ポート 443)に転送されます。
  • Ingress の定義で、単一クラスタに対するルールが重複している場合、最初のルールのみが適用されます。ルールが重複する他の Ingress にはエラーのアノテーションが追加されます。たとえば、同じ hostpath を使用して 2 つの Ingress を作成し、一方の Ingress が TLS でもう一方が TLS でなく、kubernetes.io/ingress.allow-httpfalse の場合、2 つのルールが別々の仮想サーバ上に作成され、互いに競合することはありません。しかし、kubernetes.io/ingress.allow-httptrue の場合、後で適用される Ingress にはエラーのアノテーションが追加されます。詳細については、以下の「エラー」セクションを参照してください。
  • 1 つのクラスタでサポートされるのは、デフォルトのバックエンドを持つ単一の Ingress のみです。どの Ingress ルールとも一致しないトラフィックは、デフォルトのバックエンドに転送されます。
  • デフォルトのバックエンドを持つ Ingress が複数ある場合は、最初の 1 つのみが設定されます。その他の Ingress は、エラーと見なされます。詳細については、以下の「エラー」セクションを参照してください。
  • ルールは以下の順序で適用されます。
    1. hostpath の両方が指定されたルール。
      1. Exact pathType が指定されたルール。
      2. Prefix pathType が指定されたルール。
      3. Regex pathType が指定されたルール。
    2. host または path が指定されたルール。
      1. Exact pathType が指定されたルール。
      2. Prefix pathType が指定されたルール。
      3. Regex pathType が指定されたルール。

    注: 複数のパスが要求と一致する場合、一致した最も長いパスが優先されます。

    pathType について:
    • Kubernetes 1.19 以降では、pathType は必須です。
    • use-regex が設定されている場合、pathTypeImplementationSpecific の場合にのみ有効になります。
    • use-regex が設定されていない場合、ImplementationSpecificExact と同じように処理されます。pathType は他の NCP アノテーションよりも優先されます。
    • pathType が異なる 2 つ一致パスが共存できます。
    • Prefix タイプの場合、/foo/foo/ に一致しますが、/foo/bar/foo や /foobar に一致しません。/foo と一致させるには、入力方向ルールに Exact パス /foo を追加します。
  • ホスト名のワイルドカード
    ホスト名を指定する場合は、abc.example.com のように正確な名前を指定することも、*.example.com のようにワイルドカードを使用することもできます。ワイルドカードは 1 つ以上の DNS ラベルと一致します。*.example.com を指定した場合の一致結果を次の表に示します。
    Host ヘッダー 一致結果
    abc.example.com 一致
    abc.def.example.com 一致
    example.com 一致しません
  • これは、ポリシー モードを使用する場合に適用されます。TLS Ingress がデフォルトのバックエンドで作成されている場合は、次の理由から、HTTP と HTTPS の両方の要求に応答するようにデフォルトのバックエンドを設定することをおすすめします。
    • TLS Ingress(Kubernetes/TKGI の場合はクラスタ、Project Pacific の場合は同じネームスペース)に要求内のホストと一致するホストが指定されている場合、ロード バランサは TLS を終了し、デフォルトのバックエンド サーバに HTTP 要求を送信します。
    • TLS Ingress(Kubernetes/TKGI の場合はクラスタ、Project Pacific の場合は同じネームスペース)に要求内のホストと一致するホストが指定されていない場合、ロード バランサは再度暗号化を行い、バックエンド サーバに HTTPS 要求を送信します。
  • IngressClass リソースはサポートされています。
  • pathType 属性はサポートされています。
  • JWT(JSON Web トークン)クライアント認証はサポートされています。この機能には、NSX-T Data Center 3.0.0 以降が必要です。
Kubernetes 1.18 以降では、 kubernetes.io/ingress.class アノテーションが廃止され、IngressClass リソースに置き換えられています。IngressClass リソースで Ingress コントローラとして NSX-T を指定するには、コントローラのパラメータを k8s.io/nsx に設定します。次はその例です。
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx
サードパーティの Ingress コントローラを指定するには、コントローラのパラメータを k8s.io/<controller name> に設定します。次はその例です。
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: false
spec:
  controller: k8s.io/ingress-nginx

IngressClass をクラスタのデフォルトとして設定するには、ingressclass.kubernetes.io/is-default-class アノテーションを true に設定します。上の例を参照してください。

kubernetes.io/ingress.class アノテーションと IngressClass リソースの両方は使用できません。

Endpoints オブジェクトを手動で構成する場合は、必ず targetRef パラメータを設定してください。値は、バックエンド ポッドの UID にする必要があります。次はその例です。
apiVersion: networking.k8s.io/v1
kind: Endpoints
metadata:
  name: tea-svc
subsets:
  - addresses:
    - ip: 172.26.0.2
      targetRef:
        uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e
...

機能のアノテーション

次の表に、NCP がサポートするアノテーションを示します。
アノテーション 説明 サポートされる値 デフォルト値
kubernetes.io/ingress.allow-http HTTPS に加えて HTTP 要求を有効にします true、false true
ncp/use-regex パス パターンの一致を有効にします true、false false
ingress.kubernetes.io/rewrite-target 受信した要求のパスを書き換えます
  • / で始まるパス
  • 正規表現でキャプチャされたグループの番号付きプレースホルダを含むパス(たとえば、/$1)
デフォルト値はありません
ncp/http-redirect HTTP 要求を HTTPS にリダイレクトします true、false false
kubernetes.io/ingress.class この Ingress を担う入力方向コントローラを示します nsx、nginx など nsx
nsx/loadbalancer 専用のロード バランサに Ingress を配置します LoadBalancer CRD の名前 デフォルト値はありません
ncp/allowed-source-range 要求の送信元 IP によって Ingress のアクセスを制限します。 CIDR、IP アドレス、または IP 範囲のカンマ区切りのリスト。 デフォルト値はありません
ncp/ssl-mode Ingress のすべてのルールに SSL モードを選択します。 offload、reencrypt、passthrough offload
ncp/jwt-alg JWT 署名の検証に使用されるアルゴリズムを決定します。ncp/jwt-secret を設定した場合、JWT クライアントの認証が有効になります。 HS256、RS256 デフォルト値はありません
ncp/jwt-secret 署名の検証に使用する JWT シークレットまたはパブリック キーを含む Kubernetes シークレットの名前を指定します。ncp/jwt-alg を設定した場合、JWT クライアントの認証が有効になります。 Kubernetes シークレットの名前 デフォルト値はありません
ncp/jwt-token HTTP 要求で JWT を検索する追加の場所。 _arg_<param_name>、_cookie_<cookie_name> デフォルト値はありません
ncp/jwt-realm 認証に失敗した場合に 401 で返される Realm ヘッダーを指定します。 レルムを表す文字列 入力方向ルールのホスト名
ncp/jwt-preserve JWT を保持し、認証の成功後にバックエンドに渡すオプション。 true、false true
ncp/connection_multiplexing_enabled TCP 多重化を有効にします。 true、false false
ncp/connection_multiplexing_number TCP 多重化が有効になっている場合、使用可能なアイドル状態の TCP 接続の数を指定します。 0 - 2147483647 6
アノテーションの詳細:
  • パスの Regex(正規表現)一致
    • アノテーション ncp/use-regex を使用して、Ingress pathhost ではない)パラメータの正規表現一致を有効または無効にできます。false に設定されている場合は、equals 一致を使用してパスの完全一致が実行されます。true に設定した場合、文字列開始文字 (^) と文字列終了文字 ($) をパスに追加することによって、正規表現の一致が実行されます。これにより、要求 URI 全体がパターンに一致するようになります。OR 演算子 (|) を使用する場合は、常に括弧で範囲を指定して、^ と $ がすべてのオペランドに適用されるようにします。例:path: /(tea|coffee|milk)。Ingress の仕様の例:
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          #/tea/cup will be served by tea-svc:80
          ncp/use-regex: "True"
      spec:
        rules:
        - host: cafe.example.com
          http:
            paths:
            # for this tea and coffee NCP will configure regex rule
            - path: /tea/(.*)
              pathType: ImplementationSpecific
              backend:
                service:
                  name: tea-svc
                  port:
                    number: 80
            - path: /coffee/(.*)
              pathType: ImplementationSpecific
              backend:
                service:
                  name: coffee-svc
                  port:
                    number: 80
            # for juice and alcohol NCP will configure Exact and Prefix rules
            - path: /juice
              pathType: Exact
              backend:
                service:
                  name: juice-svc
                  port:
                    number: 80
            - path: /alcohol
              pathType: Prefix
              backend:
                service:
                  name: bar
                    number: 80
    • NCP をアップグレードする前に Ingress を更新する
      これは、Ingress が文字「.」および「*」を使用するすべてのサブパス一致を必要とする場合にのみ必要です。
      1. アノテーション ncp/use-regex: true を含めるように Ingress を更新します。
      2. すべてのサブパス一致では、/coffee/*/* などのパスがある場合はそれらのパスを /coffee/.* および /.* に変更します。

        /coffee/.*/coffee//coffee/a/coffee/b/coffee/a/b などと一致します。/.*/coffee/tea/coffee/a などと一致します。パスを省略すると、path: /.* と同じ動作が生成されます。

  • 以下の ingress.kubernetes.io/rewrite-target アノテーションの例で、パス /tea/coffee は、バックエンド サービスに URL を送信する前に / に書き換えられます。
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        ingress.kubernetes.io/rewrite-target: /
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80
    正規表現を使用して path が指定されている場合、キャプチャされたグループは、$1、$2 などの番号付きプレースホルダの形式で保存されます。これらのプレースホルダは、 ingress.kubernetes.io/rewrite-target アノテーションのパラメータとして使用できます。名前付きキャプチャ グループと名前付きプレースホルダはサポートされていません。次はその例です。
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        kubernetes.io/ingress.class: "nsx"
        ncp/use-regex: "true"
        #/tea/cup will be rewritten to /cup before sending request to endpoint
        ingress.kubernetes.io/rewrite-target: /$1
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80
  • アノテーション kubernetes.io/ingress.allow-http について:
    • アノテーションが false に設定されている場合は、HTTPS 仮想サーバのルールが作成されます。
    • アノテーションが true に設定されているか、存在しない場合は、HTTP と HTTPS 仮想サーバの両方のルールが作成されます。Ingress の仕様に TLS セクションがある場合のみ、HTTPS ルールが作成されます。
  • アノテーション ncp/http-redirect について:
    • アノテーションが false に設定されている場合、HTTP 仮想サーバへの受信 HTTP トラフィック(ポート 80)は HTTPS 仮想サーバにリダイレクトされません。
    • アノテーションが true に設定されている場合、HTTP 仮想サーバへの受信 HTTP トラフィック(ポート 80)は HTTPS 仮想サーバ(ポート 443)にリダイレクトされます。

    この注釈は、TLS セクションが存在する場合にのみ有効です。このアノテーションは kubernetes.io/ingress.allow-http よりも優先されます。true に設定すると、kubernetes.io/ingress.allow-http の設定に関係なく、一致する HTTP トラフィックが HTTPS に直接送信されます。

  • アノテーション kubernetes.io/ingress.class について:
    • 値が nsx の場合、この Ingress は NCP によって処理されます。他の値が指定されている場合、Ingress は NCP によって無視されます。詳細については、サードパーティの入力方向コントローラを参照してください。
  • アノテーション nsx/loadbalancer に関する詳細は、Ingress のスケーリングを処理する LoadBalancer CRDを参照してください。
  • アノテーション ncp/allowed-source-range について:
    • ポリシー モードでのみサポートされます。
    • 設定すると、送信元 IP アドレスがこの注釈に含まれている場合にのみ、受信要求が受け入れられます。それ以外の場合は、トラフィックがドロップされます。
    • CIDR、IP アドレス、IP 範囲の組み合わせを指定できます。たとえば、1.1.1.1/24, 2.2.2.2, 3.3.3.3-4.4.4.4 と指定できます。
    • YAML の例:
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          #Source IP addresses allowed to access ingress URL
          ncp/allowed-source-range: "192.168.128.0/17, 192.168.64.0-192.168.64.255, 192.168.16.32"
      spec:
        tls:
        - hosts:
          - cafe.example.com
        rules:
        - host: cafe.example.com
          http:
            paths:
            - path: /tea
              pathType: ImplementationSpecific
              backend:
                service:
                  name: tea-svc
                  port:
                    number: 80
            - path: /coffee
              pathType: ImplementationSpecific
              backend:
                service:
                  name: coffee-svc
                  port:
                    number: 80
  • アノテーション ncp/ssl-mode について:
    • ポリシー モードでのみサポートされます。
    • この注釈は、Ingress のすべてのルールに適用されます。ロード バランサは、これらのルールに対して選択された SSL モードで動作します。

      ncp/ssl-modereencrypt または passthrough に設定されている場合は、kubernetes.io/ingress.allow-httpFalse に設定する必要があります。ingress.kubernetes.io/rewrite-targetncp/use-regex、または ncp/allowed-source-range 注釈が設定されていない場合、この注釈に passthrough を設定することはできません。

      ncp/ssl-modepassthrough に設定されている場合、rules 仕様の属性 path はサポートされません。

  • JWT クライアント認証について:
    • 入力方向のすべてのルールで JWT クライアント認証を有効にするには、ncp/jwt-algncp/jwt-secret の両方に有効な値を設定する必要があります。有効にすると、有効な JSON Web Token がある場合にのみ、受信 HTTP トラフィックがバックエンドに渡されます。それ以外の場合は、401 状態でトラフィックが拒否されます。
    • この機能は次の注釈と互換性がありません。
      • kubernetes.io/ingress.allow-http: true
      • ncp/http-redirect: true
      • ncp/ssl-mode: passthrough
    • ncp/jwt-alg
      • サポートされている対称アルゴリズム:HS256
      • サポートされている非対称アルゴリズム:RS256
    • ncp/jwt-secret
      • 入力方向と同じネームスペースで、この注釈に指定された名前の Kubernetes シークレットに対称キーまたはパブリック証明書を構成する必要があります。
      • 対称アルゴリズムの場合、シークレットを jwt.key フィールドに保存する必要があります。
      • 非対称アルゴリズムの場合は、パブリック証明書を tls.crt フィールドに保存する必要があります。
      • 対称シークレットまたはパブリック証明書が上記の場所に保存されていない場合、またはシークレットに保存されているデータが無効な場合、JWT クライアント認証は無効になります。
    • ncp/jwt-token
      • この注釈では 1 つのアイテムのみを構成できます。
      • _arg_<param_name>:JWT が URI パラメータとして渡された場合。JWT を含むパラメータ名を指定します。
      • _cookie_<cookie_name>:JWT が Cookie として渡された場合。JWT を含む Cookie 名を指定します。
  • 注釈 ncp/connection_multiplxing_enabledncp/connection_multiplxing_number について:
    • TCP 多重化は HTTP NTLM と共存できません。NSX では、TCP 多重化が有効になっているロード バランサ プールが、NTLM が有効なレイヤー 7 サーバにバインドされている場合、NTLM 構成が TCP 多重化よりも優先されます。
    • YAML の例:
      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          ncp/connection_multiplexing_enabled: "true"
          ncp/connection_multiplexing_number: 100
      spec:
        tls:
        - hosts:
          - cafe.example.com
        rules:
        - host: cafe.example.com
          http:
            paths:
            - path: /tea
              backend:
                service:
                  name: tea-svc
                  port:
                    number: 80
            - path: /coffee
              backend:
                service:
                  name: coffee-svc
                  port:
                    number: 80

エラー

Ingress リソースにエラーのアノテーションが追加されます。エラー キーは ncp/error.loadbalancer で、警告キーは ncp/warning.loadbalancer です。想定されるエラーおよび警告は次のとおりです。
  • ncp/error.loadbalancer: DEFAULT_BACKEND_IN_USE

    このエラーは、デフォルトのバックエンドがある Ingress があることを示しています。Ingress は非アクティブになります。このエラーは、(1) この Ingress が HTTP 用であり、デフォルトのバックエンドが使用されている HTTP の別の Ingress が存在する場合、(2) この Ingress が HTTPS 用で、デフォルトのバックエンドが使用されている HTTPS の別の Ingress が存在する場合、または (3) この Ingress が HTTP および HTTPS 用で、デフォルトのバックエンドが使用されている HTTP および HTTPS の別の Ingress が存在する場合に発生します。エラーを修正するには、Ingress を削除して適切な仕様で再作成します。

  • ncp/warning.loadbalancer: SECRET_NOT_FOUND

    このエラーは、入力方向に指定されたシークレットが存在しないことを表します。また、ncp/jwt-algncp/jwt-secret に注釈が付いている場合は、そのシークレットが入力方向と同じネームスペースに存在しないことを表します。Ingress は、部分的にアクティブになります。エラーを修正するには、不足している Secret を作成します。アノテーションに警告がある場合、Ingress リソースのライフ サイクルでは消去されません。

  • ncp/warning.loadbalancer: INVALID_INGRESS
    このエラーは、次の条件のいずれかが True であることを示します。Ingress は非アクティブになります。エラーを修正するには、Ingress を削除して適切な仕様で再作成します。
    • Ingress ルールが、同じ Kubernetes クラスタ内の別の Ingress ルールと競合します。競合が決定されるのは、一致戦略が同じ、つまり ncp/use-regex アノテーション値が同じ Ingress の場合のみです。
    • kubernetes.io/ingress.allow-http アノテーションは false に設定され、Ingress には TLS セクションが設定されません。
    • ncp/http-redirect アノテーションは true に設定され、Ingress には TLS セクションが設定されません。
    • Ingress ルールには host および path が指定されていません。このような Ingress ルールには Ingress のデフォルトのバックエンドと同じ機能があります。代わりに Ingress のデフォルトのバックエンドを使用します。
    • 入力方向の JWL 注釈が正しく処理できません。次はその例です。
      • ncp/jwt-alg または ncp/jwt-secret のいずれかが見つかりません。
      • ncp/jwt-alg が、サポートされていないアルゴリズムで構成されています。
      • ncp/jwt-algncp/jwt-secret に HTTP を有効にする他の注釈が構成されているか、SSL パススルーが構成されています。