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 は、エラーと見なされます。詳細については、以下の「エラー」セクションを参照してください。
- ルールは以下の順序で適用されます。
- host と path の両方が指定されたルール。
- Exact pathType が指定されたルール。
- Prefix pathType が指定されたルール。
- Regex pathType が指定されたルール。
- host または path が指定されたルール。
- Exact pathType が指定されたルール。
- Prefix pathType が指定されたルール。
- 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 を追加します。
- host と path の両方が指定されたルール。
- ホスト名のワイルドカード
ホスト名を指定する場合は、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 3.0.0 以降が必要です。
Kubernetes 1.18 以降では、
kubernetes.io/ingress.class アノテーションが廃止され、IngressClass リソースに置き換えられています。IngressClass リソースで Ingress コントローラとして
NSX を指定するには、コントローラのパラメータを
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 | 受信した要求のパスを書き換えます |
|
デフォルト値はありません |
| 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 path（host ではない）パラメータの正規表現一致を有効または無効にできます。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 が文字「.」および「*」を使用するすべてのサブパス一致を必要とする場合にのみ必要です。
- アノテーション ncp/use-regex: true を含めるように Ingress を更新します。
- すべてのサブパス一致では、/coffee/* や /* などのパスがある場合はそれらのパスを /coffee/.* および /.* に変更します。
/coffee/.* は /coffee/、/coffee/a、/coffee/b、/coffee/a/b などと一致します。/.* は /coffee、/tea、/coffee/a などと一致します。パスを省略すると、path: /.* と同じ動作が生成されます。
- アノテーション ncp/use-regex を使用して、Ingress path（host ではない）パラメータの正規表現一致を有効または無効にできます。false に設定されている場合は、equals 一致を使用してパスの完全一致が実行されます。true に設定した場合、文字列開始文字 (^) と文字列終了文字 ($) をパスに追加することによって、正規表現の一致が実行されます。これにより、要求 URI 全体がパターンに一致するようになります。OR 演算子 (|) を使用する場合は、常に括弧で範囲を指定して、^ と $ がすべてのオペランドに適用されるようにします。例：
- 以下の 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-mode が reencrypt または passthrough に設定されている場合は、kubernetes.io/ingress.allow-http を False に設定する必要があります。ingress.kubernetes.io/rewrite-target、ncp/use-regex、または ncp/allowed-source-range 注釈が設定されていない場合、この注釈に passthrough を設定することはできません。
ncp/ssl-mode が passthrough に設定されている場合、rules 仕様の属性 path はサポートされません。
- 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_multiplxing_enabled と ncp/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-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 パススルーが構成されています。
