入力方向 (Ingress)

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 にはエラーのアノテーションが追加されます。たとえば、同じ
    host
    path
    を使用して 2 つの Ingress を作成し、一方の Ingress が TLS でもう一方が TLS でなく、
    kubernetes.io/ingress.allow-http
    false
    の場合、2 つのルールが別々の仮想サーバ上に作成され、互いに競合することはありません。しかし、
    kubernetes.io/ingress.allow-http
    true
    の場合、後で適用される Ingress にはエラーのアノテーションが追加されます。詳細については、以下の「エラー」セクションを参照してください。
  • 1 つのクラスタでサポートされるのは、デフォルトのバックエンドを持つ単一の Ingress のみです。どの Ingress ルールとも一致しないトラフィックは、デフォルトのバックエンドに転送されます。
  • デフォルトのバックエンドを持つ Ingress が複数ある場合は、最初の 1 つのみが設定されます。その他の Ingress は、エラーと見なされます。詳細については、以下の「エラー」セクションを参照してください。
  • (NCP 3.0.0 および 3.0.1)ルールは次の順序で適用されます。
    1. host
      path
      の両方が指定され、正規表現に一致しないルール。
    2. host
      path
      の両方が指定され、正規表現に一致するルール(最長の Ingress
      path
      から順に)。
    3. host
      または
      path
      のいずれかが指定され、正規表現に一致しないルール。
    4. host
      または
      path
      のいずれかが指定され、正規表現に一致するルール(最長の Ingress
      path
      から順に)。
  • (NCP 3.0.2 以降)ルールは次の順序で適用されます。
    1. host
      path
      の両方が指定されたルール。
      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 要求を送信します。
  • (NCP 3.0.0 および 3.0.1)
    IngressClass
    リソースはサポートされません。
  • (NCP 3.0.2 以降)
    IngressClass
    リソースがサポートされます。
  • (NCP 3.0.0 および 3.0.1)
    pathType
    属性はサポートされません。
  • (NCP 3.0.2 以降)
    pathType
    属性がサポートされます。
  • (NCP 3.0.2 以降)JWT (JSON Web Token) クライアント認証がサポートされます。この機能を利用するには 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
      path
      host
      ではない)パラメータの正規表現一致を有効または無効にできます。
      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-mode
      reencrypt
      または
      passthrough
      に設定されている場合は、
      kubernetes.io/ingress.allow-http
      False
      に設定する必要があります。
      ingress.kubernetes.io/rewrite-target
      ncp/use-regex
      、または
      ncp/whitelist-source-range
      注釈が設定されていない場合、この注釈に
      passthrough
      を設定することはできません。
  • JWT クライアント認証について:
    • 入力方向のすべてのルールで JWT クライアント認証を有効にするには、
      ncp/jwt-alg
      ncp/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-alg
    ncp/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-alg
        ncp/jwt-secret
        に HTTP を有効にする他の注釈が構成されているか、SSL パススルーが構成されています。