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 について:
    • ImplementationSpecific は、Exact と同じように扱われます。
    • pathType が異なる 2 つ一致パスが共存できます。
    • Prefix タイプの場合、/foo/foo/ に一致しますが、/foo/bar/foo や /foobar に一致しません。/foo と一致させるには、入力方向ルールに Exact パス /foo を追加します。
  • これは、ポリシー モードを使用する場合に適用されます。TLS Ingress がデフォルトのバックエンドで作成されている場合は、次の理由から、HTTP と HTTPS の両方の要求に応答するようにデフォルトのバックエンドを設定することをおすすめします。
    • TLS Ingress(Kubernetes/PKS の場合はクラスタ、Project Pacific の場合は同じネームスペース)に要求内のホストと一致するホストが指定されている場合、ロード バランサは TLS を終了し、デフォルトのバックエンド サーバに HTTP 要求を送信します。
    • TLS Ingress(Kubernetes/PKS の場合はクラスタ、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 に設定します。次はその例です。
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx
サードパーティの Ingress コントローラを指定するには、コントローラのパラメータを k8s.io/<controller name> に設定します。次はその例です。
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 リソースの両方は使用できません。

機能のアノテーション

次の表に、NCP がサポートするアノテーションを示します。
アノテーション 説明 サポートされる値 デフォルト値 NCP バージョン
kubernetes.io/ingress.allow-http HTTPS に加えて HTTP 要求を有効にします true、false true 2.5 以降
ncp/use-regex パス パターンの一致を有効にします true、false false 2.5.1 以降
ingress.kubernetes.io/rewrite-target 受信した要求のパスを書き換えます
  • (NCP 2.5 以降)「/」で始まるパス
  • (NCP 2.5.1 以降と NSX-T 2.5.1 以降)正規表現でキャプチャされたグループの番号付きプレースホルダを含むパス(たとえば、/$1)
デフォルト値はありません [サポートされる値] 列を参照
ncp/http-redirect HTTP 要求を HTTPS にリダイレクトします true、false false 2.5.1 以降
kubernetes.io/ingress.class この Ingress を担う入力方向コントローラを示します nsx、nginx など nsx 2.5 以降
nsx/loadbalancer 専用のロード バランサに Ingress を配置します LoadBalancer CRD の名前 デフォルト値はありません 2.5.1 以降
ncp/whitelist-source-range 要求の送信元 IP によって Ingress のアクセスを制限します。 CIDR、IP アドレス、または IP 範囲のカンマ区切りのリスト。 デフォルト値はありません 3.0.0 以降
ncp/ssl-mode Ingress のすべてのルールに SSL モードを選択します。 offload、reencrypt、passthrough offload 3.0.1 以降
ncp/jwt-alg JWT 署名の検証に使用されるアルゴリズムを決定します。ncp/jwt-secret を設定した場合、JWT クライアントの認証が有効になります。 HS256、RS256 デフォルト値はありません 3.0.2 以降
ncp/jwt-secret 署名の検証に使用する JWT シークレットまたはパブリック キーを含む Kubernetes シークレットの名前を指定します。ncp/jwt-alg を設定した場合、JWT クライアントの認証が有効になります。 Kubernetes シークレットの名前 デフォルト値はありません 3.0.2 以降
ncp/jwt-token HTTP 要求で JWT を検索する追加の場所。 _arg_<param_name>、_cookie_<cookie_name> デフォルト値はありません 3.0.2 以降
ncp/jwt-realm 認証に失敗した場合に 401 で返される Realm ヘッダーを指定します。 レルムを表す文字列 入力方向ルールのホスト名 3.0.2 以降
ncp/jwt-preserve JWT を保持し、認証の成功後にバックエンドに渡すオプション。 true、false true 3.0.2 以降
アノテーションの詳細:
  • パスの Regex(正規表現)一致
    • NCP 2.5.0 以前の場合

      NCP 2.5.0 以前では、正規表現文字「.」および「*」を使用すると、すべてのサブパスの一致が自動的に有効になります。たとえば、パス /coffee/.* は、/coffee//coffee/a、および /coffee/b のように後に 0 または 1 文字以上の文字が続く /coffee/ に一致しますが、/coffee/coffeecup、または /coffeecup/a には一致しません。

      Ingress の仕様の例:
      kind: Ingress
      metadata:
        name: cafe-ingress
      spec:
        rules:
        - http:
            paths:
            - path: /coffee/.*    #Matches /coffee/, /coffee/a but NOT /coffee, /coffeecup, etc.
              backend:
                serviceName: coffee-svc
                servicePort: 80
    • NCP 2.5.1 以降の場合
      アノテーション ncp/use-regex を使用して、Ingress pathhost ではない)パラメータの正規表現一致を有効または無効にできます。 false に設定されている場合は、 equals 一致を使用してパスの完全一致が実行されます。 true に設定した場合、文字列開始文字 (^) と文字列終了文字 ($) をパスに追加することによって、正規表現の一致が実行されます。これにより、要求 URI 全体がパターンに一致するようになります。 OR 演算子 (|) を使用する場合は、常に括弧で範囲を指定して、^ と $ がすべてのオペランドに適用されるようにします。例: path: /(tea|coffee|milk)Ingress の仕様の例:
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          ncp/use-regex: "true"
      spec:
        rules:
        - host: cafe.example.com
          http:
            paths:
            - path: /tea/.*
              backend:
                serviceName: tea-svc
                servicePort: 80
    • NCP を 2.5.1 以降にアップグレードする前に 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 の例:
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        ingress.kubernetes.io/rewrite-target: /
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            backend:
              serviceName: tea-svc
              servicePort: 80
          - path: /coffee
            backend:
              serviceName: coffee-svc
              servicePort: 80

    パス「/tea」および「/coffee」は、バックエンド サービスへの URL 送信前に「/」に書き換えられます。

    NCP 2.5.1 および NSX-T 2.5.1 以降では、正規表現を使用して path が指定されている場合、キャプチャされたグループは、$1、$2 などの番号付きプレースホルダの形式で保存されます。これらのプレースホルダは、 ingress.kubernetes.io/rewrite-target アノテーションのパラメータとして使用できます。名前付きキャプチャ グループと名前付きプレースホルダはサポートされていません。次はその例です。
    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/(.*)
            backend:
              serviceName: tea-svc
              servicePort: 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/whitelist-source-range について:
    • 設定すると、送信元 IP アドレスがこの注釈に含まれている場合にのみ、受信要求が受け入れられます。それ以外の場合は、トラフィックがドロップされます。
    • CIDR、IP アドレス、IP 範囲の組み合わせを指定できます。たとえば、1.1.1.1/24, 2.2.2.2, 3.3.3.3-4.4.4.4 と指定できます。
    • YAML の例:
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          ncp/whitelist-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
              backend:
                serviceName: tea-svc
                servicePort: 80
  • アノテーション ncp/ssl-mode について:
    • この注釈は、Ingress のすべてのルールに適用されます。ロード バランサは、これらのルールに対して選択された SSL モードで動作します。

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

  • 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 名を指定します。

エラー

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 パススルーが構成されています。