OCI Native Ingress Controllerの構成

ホストに基づくリクエストのルーティング

リクエストのホスト・ヘッダー(リクエストが最初に送信されたホスト)のドメイン名に基づいて受信リクエストをルーティングするように、OCIネイティブ・イングレス・コントローラを構成できます。

ホストに基づいて特定のバックエンド・サービスおよびポートにリクエストをルーティングするには、Ingressマニフェストにルート・ルールを作成します。ホストがルート・ルールと一致する場合、OCIネイティブ・イングレス・コントローラは、関連付けられたバックエンド・サービスおよびポートにリクエストをルーティングします。

たとえば、http://foo.bar.comに最初に送信されたリクエストを、ポート80のServiceAという名前のバックエンド・サービスにルーティングする次のルールを定義できます。最初にhttp://foo.bar.comに送信されたすべての受信トラフィックは、ポート80でServiceAにルーティングされます。

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /
          backend:
            serviceName: ServiceA
            servicePort: 80

パスに基づいてリクエストを異なるバックエンド・サービスにルーティングします

リクエストが最初に送信されたパス内の要素に基づいて、受信リクエストを異なるバックエンド・サービスにルーティングするようにOCIネイティブ・イングレス・コントローラを構成できます。

パスに基づいて特定のバックエンド・サービスおよびポートにリクエストをルーティングするには、Ingressマニフェストにルート・ルールを作成します。パスがルート・ルールと一致する場合、OCIネイティブ・イングレス・コントローラは、関連付けられたバックエンド・サービスおよびポートにリクエストをルーティングします。同じルールに複数のパスを指定して、リクエストを異なるバックエンドにルーティングできます。

たとえば、リクエストの元の送信先パスに基づいてリクエストをルーティングする次のルールを定義できます。

• パスが/app1で始まる場合、OCIネイティブ・イングレス・コントローラは、リクエストをポート80のServiceAという名前のバックエンド・サービスにルーティングします。
• パスが/app2で始まる場合、OCIネイティブ・イングレス・コントローラは、リクエストをポート443のServiceBという名前のバックエンド・サービスにルーティングします。

ルールはホストを指定しないため、ルールはすべての受信トラフィックに適用されます。

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443

ホストおよびパスに基づくリクエストのルーティング

OCIネイティブ・イングレス・コントローラを構成して、リクエストのホスト・ヘッダーのドメイン名(リクエストが最初に送信されたホスト)と元のリクエストが送信されたパスの要素の両方に基づいて、受信リクエストをルーティングできます。

ホストおよびパスに基づいてリクエストを特定のバックエンド・サービスおよびポートにルーティングするには、Ingressマニフェストにルート・ルールを作成します。ホストとパスがルート・ルールと一致する場合、OCIネイティブ・イングレス・コントローラは、リクエストを関連するバックエンド・サービスおよびポートにルーティングします。

たとえば、http://foo.bar.com/app1に最初に送信されたリクエストを、ポート80のfooという名前のバックエンド・サービスにルーティングする次のルールを定義できます。

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: foo
            servicePort: 80

デフォルト・バックエンドへのリクエストのルーティング

OCIネイティブ・イングレス・コントローラを構成して、受信リクエストをデフォルト・バックエンドにルーティングできます。どのルート・ルールにも一致しないリクエストを処理するようにデフォルト・バックエンドを構成できます。

たとえば、次のdefaultBackendを定義して、Ingressマニフェストの他のルールと一致しないリクエストを、ポート8080のServiceCという名前のバックエンド・サービスにルーティングできます。

Ingressマニフェストで他のルールを指定しない場合は、defaultBackendを指定する必要があります。

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443
  defaultBackend:
    service:
      name: ServiceC
      port:
        number: 8080

注釈を使用した一般的な動作のカスタマイズ

IngressClassまたはIngressリソース・マニフェストに注釈を追加して、OCIネイティブ・イングレス・コントローラの一般的な動作をカスタマイズできます。

注釈を使用したヘルス・チェック動作のカスタマイズ

Ingressリソース・マニフェストに注釈を追加して、OCIネイティブ・イングレス・コントローラによって作成されたロード・バランサによって実行されるヘルス・チェックをカスタマイズできます。ロード・バランサのヘルス・チェックの詳細は、ロード・バランサのヘルス・チェックを参照してください。

オプション1: OCIネイティブ・イングレス・コントローラは、Kubernetesシークレットを使用して証明書サービスから証明書を取得します

OCI証明書サービスから証明書を取得するようにOCIネイティブ・イングレス・コントローラを構成するには:

1. TLSの公開キーと秘密キーのペア、および証明書を取得します。

   本番環境では、証明書署名リクエストを送信することで、選択した認証局からTLS証明書を取得します。証明書リクエスト・プロセス中に、公開キーおよび対応する秘密キーが生成されます。

   開発およびテスト環境では、自己署名証明書を作成し、OpenSSLなどのツールを使用して秘密キーを自分で生成できます。たとえば(OpenSSL 3.0以降を使用):

   1. 次のコマンドを入力して、公開キーと秘密キーのペアを生成します。

      openssl genrsa -out rootCA.key 4096

      openssl req -x509 -addext basicConstraints=critical,CA:TRUE -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt -subj /CN=RootCA

   2. 次のコマンドを入力して証明書を生成します。

      openssl genrsa -out server.key 4096

      openssl req -new -sha256 -key server.key -subj /C=US/ST=CA/O=MyOrg,Inc./CN=my.example.com -out server.csr

      openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256

   この例では:

   • rootCA.keyには、ルートCAのキー・ペアが含まれます。
   • rootCA.crtには、ルートCA証明書が含まれます。
   • server.keyには、サーバー証明書を生成するためのキー・ペアが含まれます。
   • server.csrには、サーバー証明書の証明書署名リクエストが含まれます。
   • server.crtには、生成されたサーバー証明書が含まれます。
2. 次のいずれかの方法でKubernetesシークレット・リソースを作成します:

   • kubectl create secret genericコマンドを使用して、次のように入力します。

     kubectl create secret generic <k8s-secret-name> --type=kubernetes.io/tls --from-file=ca.crt=<path-and-filename>.crt --from-file=tls.crt=<path-and-filename>.crt --from-file=tls.key=<path-and-filename>.key

     ここでは:

     • <k8s-secret-name>は、Kubernetesシークレットの名前を選択します
     • --from-file=ca.crt=<path-and-filename>.crtは、ルートCA証明書を含むファイルへのパスを指定します。たとえば、--from-file=ca.crt=rootCA.crtです。
     • --from-file=tls.crt=<path-and-filename>.crtは、生成されたサーバー証明書を含むファイルへのパスを指定します。たとえば、--from-file=tls.crt=server.crtです。
     • --from-file=tls.key=<path-and-filename>.keyは、生成された秘密キーを含むファイルへのパスを指定します。たとえば、--from-file=tls.key=server.keyです。

     例:

     kubectl create secret generic example-tls-secret --type=kubernetes.io/tls --from-file=ca.crt=rootCA.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   • Secretリソース・マニフェスト・ファイルの使用:

     1. Kubernetesシークレットを.yamlファイルで次の形式で定義します:

        apiVersion: v1
        kind: Secret
        metadata:
          name: <k8s-secret-name>
        type: kubernetes.io/tls
        data:
          ca.crt: <base64-encoded-certificate-chain>
          tls.crt: <base64-encoded-server-certificate>
          tls.key: <base64-encoded-private-key>

        ここでは:

        • name: <k8s-secret-name>は、Kubernetesシークレット・リソースの名前を選択します。
        • ca.crt: <base64-encoded-certificate-chain>は、リーフ証明書から認証局に戻る証明書チェーンを形成する中間証明書を含むファイル(またはファイル)の内容です。ca.certは省略できます。ただし、証明書チェーン全体をtls.certの値として含める場合(この場合、生成されたサーバー証明書を含むファイルの内容で証明書チェーンを起動し、残りの証明書が続きます)。
        • tls.crt: <base64-encoded-server-certificate>は、生成されたサーバー証明書を含むファイルの内容です。
        • tls.key: <base64-encoded-private-key>は、生成された秘密キーを含むファイルの内容です。

        例:

        apiVersion: v1
        kind: Secret
        metadata:
          name: example-tls-secret
        type: kubernetes.io/tls
        data:
          ca.crt : MIIFGERTegcDFRTuSDGfghREdE______Jre
          tls.crt: MIIC2DCCAcCgAwIBAgIBATANBg______kqh
          tls.key: MIIEpgIBAAKCAQEA7yn3bRHQ5F______HMQ

     2. kubectl create -f <filename>.yamlを入力してシークレット・リソースを作成します

3. KubernetesシークレットをIngressリソース・マニフェストに追加します:
   1. .yamlファイルに新しいイングレス・リソースを定義します。イングレス・リソースの作成を参照してください。
   2. マニフェストのspec:セクションで、HTTPSトラフィックを受信するホストとKubernetesシークレットの名前の両方を次の形式で指定するtls:要素を追加します:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - <host-name>
          secretName: <k8s-secret-name>

      例:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret

   3. マニフェストの rules:セクションで、HTTPSトラフィックを受信するホストのルールを追加し、HTTPSトラフィックを待機するポートとして443を指定します。

      例:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-secret-ingress
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. kubectl create -f <filename>.yamlを入力してリソースを作成します

イングレス・リソースを作成すると、OCIネイティブ・イングレス・コントローラは、Kubernetesシークレットを使用してインポート済タイプの証明書と、OCI証明書サービスからCAバンドル(認証局バンドル)を取得します。OCIネイティブ・イングレス・コントローラは、証明書をリスナーに関連付け、CAバンドルをバックエンド・セットに関連付けます。

ポート443でリスニングしているリスナーが、指定されたホストへのHTTPSリクエストを受信すると、リスナーはTLS終了の証明書を使用します。次に、リスナーはルーティング・ルールを使用して、リクエストをバックエンド・セットに転送します。バックエンド・セットは、クラスタで実行されているバックエンドとの新しいTLS接続を作成します(CAバンドルを新しい接続の信頼権限として使用します)。

オプション2: 証明書サービスから証明書を取得します

OCI証明書サービスから取得した証明書を使用するようにOCIネイティブ・イングレス・コントローラを構成するには:

1. 次のいずれかの方法で、OCI証明書サービスに証明書を作成します:
   • サード・パーティCAによって発行された証明書をインポートする(証明書のタイプは「インポート済」)
   • 証明書サービスのCAから内部的に証明書を発行することによって(証明書のタイプは Issued by internal CAになります)

   外部で管理する証明書を作成しないでください(タイプ「内部CAによって発行され、外部で管理されます」)。詳細は、証明書の作成を参照してください。

2. 証明書のOCIDを書き留めます。
3. 証明書のOCIDをIngressリソース・マニフェストに追加します:
   1. .yamlファイルに新しいイングレス・リソースを定義します。イングレス・リソースの作成を参照してください。
   2. metadata:セクションで、OCI証明書サービスで作成した証明書のOCIDを次の形式で指定するannotations:要素を追加します:

      kind: Ingress
      metadata:
        name: <i-name>
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>
      spec:
      ...

      ここでは:

      • name: <i-name>は、イングレス・リソースの名前を選択します。
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>は、OCI証明書サービスで作成した証明書のOCIDです

      例:

      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
      ...

   3. Ingressリソース・マニフェストのrules:セクションで、HTTPSトラフィックを受信するホストのルールを追加し、HTTPSトラフィックをリスニングするポートとして443を指定します。

      例:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. kubectl create -f <filename>.yamlを入力してリソースを作成します

イングレス・リソースを作成するとどうなるかは、OCI証明書サービスで証明書を作成した方法によって異なります:

• サード・パーティのCAによって発行された証明書をインポートして証明書を作成した場合、証明書のタイプは「インポート済」です。OCIネイティブ・イングレス・コントローラは、証明書をリスナーに関連付け、証明書チェーンからCAバンドルを作成し、CAバンドルをバックエンド・セットに関連付けます。「インポート済」タイプの証明書を自動的にローテーションするように構成することはできません。
• 証明書サービスCAから証明書を内部的に発行して証明書を作成した場合、その証明書のタイプは Issued by internal CAです。OCIネイティブ・イングレス・コントローラは、証明書をリスナーに関連付け、CAのOCIDを取得し、そのOCIDをバックエンド・セットに関連付けます。「内部CAによって発行」タイプの証明書を自動的にローテーションするように構成できます。

ポート443でリスニングしているリスナーが、指定されたホストへのHTTPSリクエストを受信すると、リスナーはTLS終了の証明書を使用します。次に、リスナーはルーティング・ルールを使用して、リクエストをバックエンド・セットに転送します。バックエンド・セットは、クラスタで実行されているバックエンド(CAバンドルまたはそのOCIDで識別されるCAを新しい接続の信頼権限として使用)を使用して、新しいTLS接続を作成します。

定義済タグのロード・バランサへの適用

定義済タグは、タグ管理者によって設定および管理されます。定義されたタグは、タグ・ネームスペース、キーおよび値で構成されます。タグ・ネームスペースとタグ・キー定義は、定義されたタグをリソースに適用する前に、テナンシで設定する必要があります。

OCIネイティブ・イングレス・コントローラが定義済タグをロード・バランサに適用することを指定するには、IngressClassマニフェストのoci-native-ingress.oraclecloud.com/defined-tags注釈を次の形式で使用します:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'
spec:
  ...

ここでは:

• <tag-namespace>は、タグが属するタグ・ネームスペースです。
• <tag-key>は、ロード・バランサに適用する定義済タグの名前です。
• <tag-value>は、事前定義された値リストからのタグの値、または新しい値、または空白(定義されたタグの設定方法によって異なります)のいずれかです。

oci-native-ingress.oraclecloud.com/defined-tags注釈の値はJSON文字列で、JSON形式で複数のタグ・ネームスペース、タグ・キーおよびタグ値を指定できます。

例:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"Operations": {"CostCenter": "42", "Department": "001"}, "Sales": {"Region": "US"}}'
spec:
  ...

IngressClassマニフェストのoci-native-ingress.oraclecloud.com/defined-tags注釈のいずれかのタグを変更すると、OCIネイティブ・イングレス・コントローラは、注釈で指定されたすべての定義済タグをロード・バランサに再適用します。ただし、定義済タグにタグ変数が含まれている場合、OCIネイティブ・イングレス・コントローラは、タグがまだ存在しない場合のみ、定義済タグをロード・バランサに再適用します。

OCIネイティブ・イングレス・コントローラが定義済タグをロード・バランサに適用できるようにするには、OCIネイティブ・イングレス・コントローラで適切なタグ・ネームスペースを使用できるように、適切なIAMポリシーが存在する必要があります。詳細は、次を参照してください:

• スタンドアロン・プログラムとしてのOCIネイティブ・イングレス・コントローラへの権限の付与
• OCIネイティブ・イングレス・コントローラ・クラスタ・アドオンへの権限の付与

ロード・バランサへのフリーフォーム・タグの適用

フリーフォーム・タグは、タグ管理者によって管理されません。フリーフォーム・タグは、キーと値で構成されます。定義済タグとは異なり、フリーフォーム・タグはタグ・ネームスペースに属していません。

OCIネイティブ・イングレス・コントローラがフリーフォーム・タグをロード・バランサに適用することを指定するには、IngressClassマニフェストのoci-native-ingress.oraclecloud.com/freeform-tags注釈を次の形式で使用します。

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"<tag-key>": "<tag-value>"}'
spec:
  ...

ここでは:

• <tag-key>は、ロード・バランサに適用するフリーフォーム・タグの名前です。
• <tag-value>は、ロード・バランサに適用するフリーフォーム・タグの値です。

oci-native-ingress.oraclecloud.com/freeform-tags注釈の値はJSON文字列で、複数のタグ・キーおよびタグ値をJSON形式で指定できます。

例:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"Project": "Red", "Version": "Alpha"}'
spec:
  ...

IngressClassマニフェストのoci-native-ingress.oraclecloud.com/freeform-tags注釈のいずれかのタグを変更すると、OCIネイティブ・イングレス・コントローラは、注釈で指定されたすべてのフリーフォーム・タグをロード・バランサに再適用します。

ロード・バランサへのタグのデフォルトの適用

タグのデフォルトは、特定のコンパートメントに対して設定されます。タグのデフォルトは、コンパートメント固有です。タグのデフォルトでは、作成時に特定のコンパートメントに作成されたすべてのリソースに自動的に適用される定義済タグを指定します。

OCIネイティブ・イングレス・コントローラ・バージョン1.4.0 (以降)を使用する場合、OCIネイティブ・イングレス・コントローラが作成するロード・バランサにタグのデフォルトが自動的に適用されます。その後、OCIネイティブ・イングレス・コントローラは、次のいずれかの条件が満たされないかぎり、ロード・バランサに適用されるタグのデフォルトを保持します。

• ロード・バランサに自動的に適用されたタグのデフォルトを手動で削除します。
• oci-native-ingress.oraclecloud.com/defined-tags注釈を使用して、タグのデフォルトを定義済タグとして指定します(その場合、OCIネイティブ・イングレス・コントローラはタグのデフォルトを他の定義済タグとして扱います)。

ユーザーが適用した値を持つタグのデフォルトはサポートされていません。OCIネイティブ・イングレス・コントローラがロード・バランサを作成または管理するコンパートメントに、ユーザーが適用した値を持つタグのデフォルトが設定されている場合は、oci-native-ingress.oraclecloud.com/defined-tags注釈を使用して、定義済タグとしてタグのデフォルトを指定する必要があります。

バージョン1.4.0より前のOCIネイティブ・イングレス・コントローラ・バージョンを使用して作成されたロード・バランサの場合、またはoci-native-ingress.oraclecloud.com/id注釈を使用して、OCIネイティブ・イングレス・コントローラが既存のロード・バランサを管理することを指定する場合、タグのデフォルトはサポートされていないことに注意してください。どちらの場合も、タグのデフォルトを適用または保持するには、oci-native-ingress.oraclecloud.com/defined-tags注釈を使用して、かわりにタグのデフォルトを定義済タグとして指定します。