入力方向 (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 は、エラーと見なされます。詳細については、以下の「エラー」セクションを参照してください。
ルールは以下の順序で適用されます。
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 について：
- Kubernetes 1.19 以降では、pathType は必須です。
- use-regex が設定されている場合、pathType が ImplementationSpecific の場合にのみ有効になります。
- use-regex が設定されていない場合、ImplementationSpecific は Exact と同じように処理されます。pathType は他の NCP アノテーションよりも優先されます。
- pathType が異なる 2 つ一致パスが共存できます。
- Prefix タイプの場合、/foo は /foo/ に一致しますが、/foo/bar は /foo や /foobar に一致しません。/foo と一致させるには、入力方向ルールに Exact パス /foo を追加します。
これは、ポリシーモードを使用する場合に適用されます。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 に設定します。次はその例です。

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 リソースの両方は使用できません。

Endpoints オブジェクトを手動で構成する場合は、必ず targetRef パラメータを設定してください。値は、バックエンドポッドの UID にする必要があります。次はその例です。

kind: Endpoints
metadata:
  name: tea-svc
subsets:
  - addresses:
    - ip: 172.26.0.2
      targetRef:
        uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e
...

機能のアノテーション

次の表に、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 3.1 以前）ncp/whitelist-source-range （NCP 3.1.1 以降）ncp/allowed-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 以降
ncp/connection_multiplexing_enabled	TCP 多重化を有効にします。	true、false	false	3.1.1 以降
ncp/connection_multiplexing_number	TCP 多重化が有効になっている場合、使用可能なアイドル状態の TCP 接続の数を指定します。	0 - 2147483647	6	3.1.1 以降

アノテーションの詳細：

パスの 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/allowed-source-range について（NCP 3.1 以前では 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/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
        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/allowed-source-range 注釈が設定されていない場合、この注釈に passthrough を設定することはできません。（NCP 3.1 以前では、ncp/allowed-source-range の名前は ncp/whitelist-source-range です）。
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 名を指定します。

注釈 ncp/connection_multiplexing_enabled と ncp/connection_multiplexing_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-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 パススルーが構成されています。