ホスト・ヘッダーへのサーバー・ポートの追加

リクエストがバックエンドアプリに転送される前にクライアントリクエストにサーバポートを追加するには、 サーバスニペットアノテーションで外部サービスへのプロキシを設定するか、 ibm-k8s-controller-config ConfigMap フィールドとして設定します。

プライベート ALB を使用した着信要求のルーティング

プライベート ALB を使用して着信要求をアプリにルーティングするには、 Ingress リソース で private-iks-k8s-nginx クラス・アノテーションを指定します。 プライベート ALB は、このクラスのリソースを使用するように構成されます。

kubernetes.io/ingress.class: "private-iks-k8s-nginx"

App ID を使用したアプリケーションの認証

でIngressを設定します。 IBM Cloud App ID でIngressを設定し、 Kubernetes Ingressの特定のフィールドを変更することで、アプリの認証を強制します。 詳細については、 アプリに App ID 認証を追加するを 参照してください。

クライアント要求本体の最大サイズの設定

クライアントがリクエストの一部として送信できるボディの最大サイズを設 定するには、以下の Kubernetes Ingress リソースアノテーションを使 用する。

nginx.ingress.kubernetes.io/proxy-body-size: 8m

クライアント応答データ・バッファリングの有効化および無効化

クライアントへのデータ送信中に、ALB での応答データの保存を無効化または有効化することができます。 この設定はデフォルトで無効になります。 有効にするには、以下の Ingress リソース・ アノテーションを設定します。

nginx.ingress.kubernetes.io/proxy-buffering: "on"

接続および読み取りのタイムアウトの設定

バックエンド・アプリが使用不可と見なされるまでに、ALB がバックエンド・アプリへの接続とバックエンド・アプリからの読み取りを待機する時間を設定するには、以下の アノテーションを使用します。

nginx.ingress.kubernetes.io/proxy-connect-timeout: 62

nginx.ingress.kubernetes.io/proxy-read-timeout: 62

エラー・アクションのカスタマイズ

特定の HTTP エラーに対してALBが取ることができるカスタムアクションを示すには、 custom-http-errors フィールドを設定する。

デフォルトの HTTP と HTTPS ポートを変更する

HTTP （ポート 80）と HTTPS （ポート 443）ネットワークトラフィックのデフォルトポートを変更するには、以下の Kubernetes Ingress ibm-ingress-deploy-config ConfigMap フィールドで 各 ALB サービスを変更する。

フィールド設定の例。

httpPort=8080
httpsPort=8443

要求ヘッダーのカスタマイズ

クライアントのリクエストをバックエンドアプリに転送する前に、そのリクエストにヘッダー情報を追加するには、 Kubernetes ibm-k8s-controller-config の configmap フィールドを使用します。

proxy-set-headers: "ingress-nginx/custom-headers"

custom-headers （ ConfigMap ）の要件については、 こちらの例を参照してください。

応答ヘッダーのカスタマイズ

クライアント応答をクライアントに送信する前にヘッダー情報をクライアント応答に追加するには、以下の アノテーションを使用します。

nginx.ingress.kubernetes.io/configuration-snippet: |
    more_set_headers "Request-Id: $req_id";

外部サービスへのパス定義の追加

IBM Cloud でホストされているサービスなど、外部サービスにパス定義を追加するには、 ロケーションスニペットで外部サービスへのプロキシを構成する。 または、プロキシーを 外部サービスへの永続リダイレクトに置き換えます。

非セキュア要求のリダイレクト

デフォルトでは、安全でない HTTP クライアントからのリクエストは HTTPS にリダイレクトされる。 この設定を無効にするには、以下のフィールドとアノテーションを使用します。

• ibm-k8s-controller-config ConfigMap フィールド

  ssl-redirect: "false"
  

• Ingress リソース・ アノテーション:

  nginx.ingress.kubernetes.io/ssl-redirect: "false"
  

有効化と無効化 HTTP Strict Transport Security

ドメインへのアクセスに HTTPS のみ使用するようにブラウザーを設定します。 デフォルトでは、このオプションは有効です。

• 最大有効期間やサブドメイン単位の設定については、 こちらのブログ記事（ NGINX ） をご覧ください。
• 無効にするには、 ibm-k8s-controller-config というconfigmap フィールドを設定してください。

  hsts: false
  

キープアライブ要求の最大数の設定

1つのキープアライブ接続で処理できるリクエストの最大数を設定するには、 以下の Kubernetes ibm-k8s-controller-config configmap フィールドを使う。

keep-alive-requests: 100

Kubernetes のIngressにおける keep-alive-requests のデフォルト値は 100 ですが、これは IBM Cloud Kubernetes Service のIngressにおける 4096 のデフォルト値よりもはるかに小さい値です。 Ingress のセットアップを IBM Cloud Kubernetes Service Ingress から Kubernetes Ingress にマイグレーションした場合は、既存のパフォーマンス・テストに合格するために keep-alive-requests を変更しなければならない場合があります。

キープアライブ要求の最大タイムアウトの設定

クライアントとALBプロキシサーバー間でキープアライブ接続が開いている最大時間を設定するには、次の Kubernetes ibm-k8s-controller-config configmap フィールドを使用する。

keep-alive: 60

ラージ・クライアント・ヘッダー・バッファーの最大数の設定

大きなクライアント・リクエスト・ヘッダーを読み取るバッファーの最大数 とサイズを設定するには、以下の Kubernetes ibm-k8s-controller-config configmap フィールドを使用する。

large-client-header-buffers: 4 8k

ALB が要求 URI と一致する方法の変更

ALBがリクエストURIをアプリパスと照合する方法を変更するには、次の Kubernetes Ingress リソースアノテーションを使用します。

nginx.ingress.kubernetes.io/use-regex: "true"

詳しくは、 このブログを参照してください。

カスタム・ロケーション・ブロック構成の追加

サービスにカスタムロケーションブロック構成を追加するには、以下の Kubernetes Ingress リソースアノテーションを使用します。

nginx.ingress.kubernetes.io/configuration-snippet: |
    more_set_headers "Request-Id: $req_id";

相互認証の構成

ALBに相互認証を設定するには、以下の Kubernetes Ingress リソースアノテーションを使用する。 相互認証はカスタム・ポートに適用できず、HTTPS ポートに適用する必要があることに注意してください。

nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"

プロキシー・バッファー・サイズの構成

応答の最初の部分を読み取るプロキシバッファのサイズを設定するには、以下の Kubernetes Ingress リソースアノテーションを使用する。

nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"

プロキシー・バッファー番号の構成

ALBのプロキシバッファ数を設定するには、以下の Kubernetes Ingress リソースアノテーションを使用します。

nginx.ingress.kubernetes.io/proxy-buffers-number: "4"

ビジー・プロキシー・バッファー・サイズの構成

使用中にできるプロキシー・バッファーのサイズを構成するには、 ロケーション・スニペットを使用します。 詳細については、 NGINX のドキュメントをご覧ください。

ALB が要求を渡すことができる場合の構成

ALBがいつリクエストを次のアップストリームサーバーに渡すことができるかを設定するには、以下の Kubernetes Ingressフィールドを使用する。

• グローバル設定: ibm-k8s-controller-config ConfigMap フィールド:

  retry-non-idempotent: true
  proxy-next-upstream: error timeout http_500
  

• リソースごとの設定: Ingress リソース・ アノテーション:

  nginx.ingress.kubernetes.io/proxy-next-upstream: http_500
  nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: 50
  nginx.ingress.kubernetes.io/proxy-next-upstream-tries: 3
  

速度制限

サービスの定義済みキーごとの要求処理速度と接続数を制限するには、Ingress リソース・ 速度制限のアノテーションを使用します。

応答ヘッダーの削除

クライアントへの応答が送信される前に、バックエンドアプリから、その応答に含まれているヘッダー情報を削除することができます。 レスポンスヘッダの削除を ロケーションスニペットで設定するか、 ibm-k8s-controller-config ConfigMap の 設定スニペットとして proxy_hide_header フィールドを使用する。

パスの再書き込み

ALB ドメイン・パスの受信ネットワーク・トラフィックを、バックエンド・アプリがリッスンする別のパスにルーティングするには、次の Kubernetes Ingress リソース・アノテーションを使用します。

nginx.ingress.kubernetes.io/rewrite-target: /newpath

サーバー・ブロック構成のカスタマイズ

カスタム・サーバー・ブロック構成を追加するには、以下の Kubernetes Ingress リソース・アノテーションを使用します。

nginx.ingress.kubernetes.io/server-snippet: |
    location = /health {
    return 200 'Healthy';
    add_header Content-Type text/plain;
    }

着信ネットワーク・トラフィックのルーティング

スティッキー・クッキーを使用して、着信ネットワーク・トラフィックを常に同じアップストリーム・サーバーにルーティングするには、次の Kubernetes Ingress リソース・アノテーションを使用します。

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookie_name1"
nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
nginx.ingress.kubernetes.io/configuration-snippet: |
  more_set_headers "Set-Cookie: HttpOnly";

Kubernetes Ingress コントローラーは、デフォルトでスティッキー Cookie に Secure 属性と HttpOnly 属性を追加します。これは変更できません。

SSL サービスのサポートによるトラフィックの暗号化を許可する

HTTPS を必要とするアップストリームアプリへのトラフィックを SSL サービスサポートで暗号化できるようにするには、 Kubernetes Ingress リソースバックエンドプロトコルアノテーションと バックエンド証明書認証アノテーションを使用します。

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-ssl-secret: app1-ssl-secret
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: 5
nginx.ingress.kubernetes.io/proxy-ssl-name: proxy-ssl-name=mydomain.com
nginx.ingress.kubernetes.io/proxy-ssl-verify: true

非標準の TCP ポートを使用したアプリへのアクセス

非標準の TCP ポート経由でアプリにアクセスするには、以下の手順に従ってください。

1. tcp-services 構成マップを作成して、以下の例のポートのような TCP ポートを指定します。 tcp-services （ ConfigMap, ）の要件については、 こちらのブログをご覧ください。

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: tcp-services
     namespace: kube-system
   data:
     9000: "<namespace>/<service>:8080"
   

2. kube-system 名前空間に構成マップを作成します。

   kubectl apply -f tcp-services.yaml -n kube-system
   

3. tcp-services 構成マップibm-ingress-deploy-configにフィールドとして 構成マップを指定します。

   "tcpServicesConfig":"kube-system/tcp-services"
   

4. 各 ALB サービスを変更して、ポートを追加します。

アップストリーム・キープアライブ要求の最大数の設定

1つのキープアライブ接続で処理できるリクエストの最大数を設定するには、 以下の Kubernetes ibm-k8s-controller-config ConfigMap フィールドを使用します。

upstream-keepalive-requests: 32

アップストリーム・キープアライブの最大タイムアウトの設定

ALBプロキシサーバとアプリのアップストリームサーバ間でキープアライブ接続がオープンされたままになる最大時間を設定するには、次の Kubernetes ibm-k8s-controller-config configmap フィールドを使用します。

upstream-keepalive-timeout: 32

ALB デプロイメントのカスタマイズ

ibm-ingress-deploy-config 構成マップを作成して、Kubernetes Ingress イメージを実行する ALB のデプロイメントをカスタマイズします。

1. 各 ALB を公開するサービスの名前を取得します。

   • クラシック・クラスター:

       kubectl get svc -n kube-system | grep alb
       ```
   * VPC クラスター: 出力で、`public-crc204dl7w0qf6n6sp7tug` のようなフォーマットのサービス名を探します。
   
   ```sh {: pre}
       kubectl get svc -n kube-system | grep LoadBalancer
       ```
   

Ingress クラスのカスタマイズ

Ingress クラスで、クラス名を Ingress コントローラーのタイプに関連付けます。 IngressClass リソースを使用して、Ingress クラスをカスタマイズします。

アプリへの App ID 認証の追加

Ingress を次のように設定して、アプリへの認証を適用します IBM Cloud App ID。

1. 既存の App ID インスタンスを選択するか、新しいインスタンスを作成します。

   App ID インスタンスは、クラスター内の 1 つの名前空間のみで使用できます。 複数の名前空間で Ingress リソースの App ID を構成する場合は、このセクションのステップを繰り返して、各名前空間の Ingress リソースに対して固有の App ID インスタンスを指定します。

   • 既存のインスタンスを使用するには、サービス・インスタンス名に 小文字 の英数字のみが含まれていること、およびその長さが 25 文字を超えないことを確認してください。 名前を変更するには、サービス・インスタンスの詳細ページの「オプションを増やす 」メニューから**「サービスの名前変更」**を選択します。
   • 新しい App ID インスタンスをプロビジョンするには、以下のようにします。
     1. サービス名を、サービス・インスタンスの独自の固有名で置き換えます。 サービスインスタンス名には、小文字の英数字のみを使用し、25文字以内でなければなりません。
     2. クラスターのデプロイ先と同じリージョンを選択します。
     3. 「作成」 をクリックします。

2. アプリのリダイレクト URL を追加します。 リダイレクト URL は、アプリのコールバック・エンドポイントです。 フィッシング攻撃を防止するために、IBM Cloud App ID は、要求 URL をリダイレクト URL の許可リストと照合します。

   1. App ID 管理コンソールで、**「認証の管理 (Manage Authentication)」**にナビゲートします。
   2. 「ID プロバイダータブで、ID プロバイダーが選択されていることを確認します。 IDプロバイダーが選択されていない場合、ユーザーは認証されませんが、アプリへの匿名アクセス用のアクセストークンが発行されます。
   3. 「認証設定 (Authentication settings)」 タブで、アプリのリダイレクト URL を形式 https://<hostname>/oauth2-<App_ID_service_instance_name>/callback で追加します。 サービス・インスタンス名の文字はすべて小文字で指定する必要があることに注意してください。

   IBM Cloud App ID ログアウト機能を使用する場合は、/sign_out を形式 https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out でドメインに追加し、この URL をリダイレクト URL リストに組み込む必要があります。 カスタムログアウトページを使用したい場合は、 OAuth2-Proxy の ConfigMap で whitelist_domains を設定する必要があります。 rd 照会パラメーターを指定して https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out エンドポイントを呼び出すか、カスタム・ログアウト・ページで X-Auth-Request-Redirect ヘッダーを設定します。 詳しくは、 サインアウトを参照してください。

3. App ID サービス・インスタンスをクラスターにバインドします。 このコマンドは、サービスインスタンス用のサービスキーを作成します。また、 --key オプションを指定することで、既存のサービスキーの認証情報を使用することもできます。 サービス・インスタンスを、Ingress リソースが存在するのと同じ名前空間にバインドするようにしてください。 サービス・インスタンス名の文字はすべて小文字で指定する必要があることに注意してください。

   ibmcloud ks cluster service bind --cluster CLUSTER_NAME_OR_ID --namespace NAMESPACE --service APP_ID_SERVICE_INSTANCE_NAME [--key SERVICE_INSTANCE_KEY]
   

   サービスがクラスターに正常にバインドされると、サービス・インスタンスの資格情報を保持するクラスター・シークレットが作成されます。 CLI 出力例:

   ibmcloud ks cluster service bind --cluster mycluster --namespace mynamespace --service appid1
   Binding service instance to namespace...
   OK
   Namespace:    mynamespace
   Secret name:  binding-<service_instance_name>
   

4. クラスターで ALB OAuth プロキシー・アドオンを有効にします。 このアドオンは、Kubernetes リソース (App ID サービス・インスタンスの OAuth2-Proxy デプロイメント、OAuth2-Proxy デプロイメントの構成を格納するシークレット、App ID インスタンスのために着信要求を OAuth2-Proxy デプロイメントにルーティングするよう ALB を構成する Ingress リソース) を作成および管理します。 それらのリソースの名前はそれぞれ oauth2- で始まります。

   1. alb-oauth-proxyアドオンを有効にします。

       ibmcloud ks cluster addon enable alb-oauth-proxy --cluster CLUSTER_NAME_OR_ID
       ```
   2. ALB OAuth プロキシー・アドオンの状況が `Addon Ready` であることを確認します。
   ```sh {: pre}
       ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID
       ```
   

5. App ID 認証を追加するアプリの Ingress リソースで、リソース名の長さが 25 文字を超えていないことを確認します。 次に、以下のアノテーションを metadata.annotations セクションに追加します。

   1. 以下の auth-url アノテーションを追加します。 このアノテーションは、App ID インスタンスの OAuth2-Proxy の URL を指定します。これは、App ID の OIDC リライング・パーティー (RP) として機能します。 サービス・インスタンス名の文字はすべて小文字で指定する必要があることに注意してください。

       ...
       annotations:
          nginx.ingress.kubernetes.io/auth-url: https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth
       ...
       ```
   2. `OAuth2-Proxy` によって使用される認証 Cookie が 4 KB を超えることがあります。 そのため、2 つの部分に分割されています。 `OAuth2-Proxy` が両方の Cookie を適切に更新できるようにするには、以下のスニペットを追加する必要があります。
   ```yaml {: codeblock}
       ...
       annotations:
           nginx.ingress.kubernetes.io/configuration-snippet: |
           auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
           access_by_lua_block {
               if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
               ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
               end
           }
       ...
       ```
   
   3. アプリに `Authorization` ヘッダーで送信するトークンを選択します。 ID およびアクセストークンに関する詳細については、『 [App ID 』のドキュメント](/docs/appid?topic=appid-tokens){: external}を参照してください。
       * `ID Token` のみを送信するには、次のアノテーションを追加してください：
   
           ```yaml {: codeblock}
           ...
           annotations:
               nginx.ingress.kubernetes.io/auth-response-headers: Authorization
           ...
           ```
       * `Access Token` のみを送信するには、 `configuration-snippet` アノテーションに以下の情報を追加してください。 (これにより、ステップ 5.2のスニペットが拡張されます。)
   
           ```yaml {: codeblock}
           ...
           annotations:
               nginx.ingress.kubernetes.io/configuration-snippet: |
               auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
               auth_request_set $access_token $upstream_http_x_auth_request_access_token;
               access_by_lua_block {
                   if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
                   ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
                   end
                   if ngx.var.access_token ~= "" then
                   ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token)
                   end
               }
           ...
           ```
       * `Access Token` および `ID Token` を送信するには、 `configuration-snippet` アノテーションに以下の情報を追加してください。 (これにより、ステップ 5.2のスニペットが拡張されます。)
           ```yaml {: codeblock}
           ...
            annotations:
               nginx.ingress.kubernetes.io/configuration-snippet: |
               auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
               auth_request_set $access_token $upstream_http_x_auth_request_access_token;
               auth_request_set $id_token $upstream_http_authorization;
               access_by_lua_block {
                   if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
                   ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
                   end
                   if ngx.var.id_token ~= "" and ngx.var.access_token ~= "" then
                   ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token .. " " .. ngx.var.id_token:match("%s*Bearer%s*(.*)"))
                   end
               }
           ...
           ```
   4. オプション: [API ストラテジー](/docs/appid?topic=appid-key-concepts#term-api-strategy)に加えて、または API ストラテジーの代わりにアプリが [Web アプリ・ストラテジー](/docs/appid?topic=appid-key-concepts#term-web-strategy)をサポートする場合は、`nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2-<App_ID_service_instance_name>/start?rd=$escaped_request_uri` アノテーションを追加します。 サービスインスタンス名に含まれるすべての文字は小文字でなければならないことに注意してください。
       * このアノテーションを指定したときにクライアントの認証が失敗すると、クライアントは App ID インスタンスの OAuth2-Proxy の URL にリダイレクトされます。 App ID の OIDC リライング・パーティー (RP) として機能するこの OAuth2-Proxy によって、クライアントが認証のために App ID ログイン・ページにリダイレクトされます。
       * このアノテーションが指定されていないと、クライアントは有効なベアラー・トークンで認証する必要があります。 クライアントの認証が失敗すると、クライアントの要求は `401 Unauthorized` エラー・メッセージで拒否されます。
   
   

6. Ingress リソースを再適用して、App ID 認証を実施します。 適切なアノテーションが設定された Ingress リソースが再適用されると、OAuth2-Proxy デプロイメントのデプロイ、そのデプロイメントのサービスの作成、OAuth2-Proxy デプロイメント・メッセージのルーティングを構成するための別個の Ingress リソースの作成が、ALB OAuth プロキシー・アドオンによって行われます。 これらのアドオン・リソースは削除しないでください。

   kubectl apply -f <app_ingress_resource>.yaml -n namespace
   

7. App ID 認証がアプリに実施されていることを確認します。

   • アプリが Web アプリ戦略をサポートしている場合: Web ブラウザーでアプリの URL にアクセスします。 App ID が正しく適用されている場合は、App ID 認証ログイン・ページにリダイレクトされます。
   • アプリが API 戦略をサポートしている場合: アプリへの要求の許可ヘッダーに Bearer アクセス・トークンを指定します。 アクセス・トークンを取得するには、App ID の資料を参照してください。 App ID が正しく適用されている場合、要求は正常に認証され、アプリに経路指定されます。 許可ヘッダーにアクセス・トークンを指定せずにアプリに要求を送信した場合や App ID によってアクセス・トークンが受け入れられない場合、要求は拒否されます。

8. オプション： クラスタ上でネットワーク・ポリシーまたは別のファイアウォール・ソリューションを使用して送信トラフィックを制限している場合は、クラスタから AppID's パブリック・サービスへのアクセスを許可する必要があります。 このサービスのIPアドレス範囲を取得するには、 カスタマーサポートに リクエストを送信してください。

9. オプション: OAuth2-Proxy のデフォルト動作をカスタマイズするには、Kubernetes 構成マップを作成します。

   1. 変更する OAuth2-Proxy 設定の値を指定する構成マップ YAML ファイルを作成します。

       apiVersion: v1
       kind: ConfigMap
       metadata:
         name: oauth2-<App_ID_service_instance_name>
         namespace: <ingress_resource_namespace>
       data:
         auth_logging: <true|false>
         # Log all authentication attempts.
         auth_logging_format:
         # Format for authentication logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#logging-configuration
         cookie_csrf_expire: "15m"
         # Expiration time for CSRF cookie. Default is "15m".
         cookie_csrf_per_request: <true|false>
         # Enable multiple CSRF cookies per request, making it possible to have parallel requests. Default is "false".
         cookie_domains:
         # A list of optional domains to force cookies to. The longest domain that matches the request’s host is used. If there is no match for the request’s host, the shortest domain is used. Example: sub.domain.com,example.com
         cookie_expire: "168h0m0s"
         # Expiration time for cookies. Default: "168h0m0s".
         cookie_samesite: ""
         # SameSite attribute for cookies. Supported values: "lax", "strict", "none", or "".
         email_domains: ""
         # Authenticate IDs that use the specified email domain. To authenticate IDs that use any email domain, use "*". Default: "". Example: example.com,example2.com
         pass_access_token: <true|false>
         # Pass the OAuth access token to the backend app via the X-Forwarded-Access-Token header.
         request_logging: <true|false>
         # Log all requests to the backend app.
         request_logging_format:
         # Format for request logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#request-log-format
         scope:
         # Scope of the OAuth authentication. For more info, see https://oauth.net/2/scope/
         set_authorization_header: <true|false>
         # Set the Authorization Bearer response header when the app responds to the Ingress ALB, such when using the NGINX auth_request mode.
         set_xauthrequest: <true|false>
         # Set X-Auth-Request-User, X-Auth-Request-Email, and X-Auth-Request-Preferred-Username response headers when the app responds to the Ingress ALB, such as when using the NGINX auth_request mode.
         standard_logging: <true|false>
         # Log standard runtime information.
         standard_logging_format:
         # Format for standard logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#standard-log-format
         tls_secret_name:
         # The name of a secret that contains the server-side TLS certificate and key to enable TLS between the OAuth2-Proxy and the Ingress ALB. By default, the TLS secret defined in your Ingress resources is used.
         whitelist_domains:
         # Allowed domains for redirection after authentication. Default: "". Example: example.com,*.example2.com For more info, see: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#command-line-options
         oidc_extra_audiences:
         # Additional audiences which are allowed to pass verification.
         cookie_refresh:
         # Refresh the cookie after this duration. Example: "15m". To use this feature, you must enable "Refresh token" for the AppID instance. For more info, see: /docs/appid?topic=appid-managing-idp&interface=ui#idp-token-lifetime
       ```
   2. 構成マップ・リソースをアドオンに適用します。 変更が自動的に適用されます。
   ```sh {: pre}
       kubectl apply -f oauth2-<App_ID_service_instance_name>.yaml
       ```
   

各ALB OAuth Proxyアドオンのバージョンごとの変更点のリストについては、「 IBM Cloud ALB OAuth Proxyアドオンの変更履歴 」を参照してください。

ソース IP アドレスの保持

デフォルトでは、クライアント要求のソース IP アドレスは Ingress ALB によって保持されません。 ソース IP アドレスを保持するには、VPC クラスターで PROXY プロトコルを有効にするか、クラシック・クラスターで externalTrafficPolicy を変更します。

HTTP レベルで SSL プロトコルと SSL 暗号を構成する

ibm-k8s-controller-config 構成マップを編集して、グローバル HTTP レベルで SSL プロトコルと暗号を有効にします。

例えば、TLS 1.0 または 1.1 のサポートが必要なレガシー・クライアントをまだ使用する場合は、その TLS バージョンを手動で有効にして、TLS 1.2 と TLS 1.3 だけのデフォルト設定をオーバーライドする必要があります。

すべてのホストで有効なプロトコルを指定する場合、TLSv1.1 および TLSv1.2 パラメーター (1.1.13、1.0.12) は、OpenSSL 1.0.1 以上が使用されている場合にのみ使用できます。 TLSv1.3 パラメーター (1.13.0) は、TLSv1.3 対応版の OpenSSL 1.1.1 が使用されている場合にのみ使用できます。

構成マップを編集して SSL プロトコルおよび暗号を有効にするには、以下のようにします。

1. ibm-k8s-controller-config 構成マップ・リソースに対応する構成ファイルを編集します。

   kubectl edit cm ibm-k8s-controller-config -n kube-system
   

2. SSL プロトコルおよび暗号を追加します。 OpenSSL ライブラリの暗号リスト形式に従って、暗号をフォーマットします。

   apiVersion: v1
   data:
     ssl-protocols: "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
     ssl-ciphers: "HIGH:!aNULL:!MD5:!CAMELLIA:!AESCCM:!ECDH+CHACHA20"
   kind: ConfigMap
   metadata:
     name: ibm-k8s-controller-config
     namespace: kube-system
   

3. 構成ファイルを保存します。

4. 構成マップの変更が適用されたことを確認します。 これらの変更は ALB に自動的に適用されます。

   kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
   

既存のクライアントへのカスタム証明書の送信

Server Name Indication (SNI) をサポートしないレガシー・デバイスがあり、Ingress リソース内のカスタム TLS 証明書を使用する場合は、カスタム TLS 証明書とカスタム TLS シークレットを使用するように ALB のサーバー設定を編集する必要があります。

クラシック・クラスターを作成すると、IBM 提供のデフォルトの Ingress シークレットに関する Let's Encrypt 証明書が生成されます。 クラスター内でカスタム・シークレットを作成し、Ingress リソース内で TLS 終端用にこのカスタム・シークレットを指定すると、Ingress ALB はデフォルトの Let's Encrypt 証明書の代わりにカスタム・シークレットの証明書をクライアントに送信します。 しかし、クライアントが SNI をサポートしていない場合、ALB のデフォルトのサーバー設定にデフォルトのシークレットがリストされるので、Ingress ALB のデフォルトは Let's Encrypt 証明書になります。 SNI をサポートしていないデバイスにカスタム証明書を送信するには、以下の手順に従って、ALB のデフォルト・サーバー設定をカスタム・シークレットに変更します。

デフォルトで生成される「Let 's Encrypt」証明書は、実動で使用するためのものではありません。 実動ワークロードでは、独自のカスタム証明書を持ち込みます。

1. alb-default-server Ingress リソースを編集します。

   kubectl edit ingress alb-default-server -n kube-system
   

2. spec.tls セクションで、hosts.secretName 設定の値を、カスタム証明書を格納するカスタム・シークレットの名前に変更します。 次に例を示します。

   spec:
       rules:
       ...
       tls:
       - hosts:
       - invalid.mycluster-<hash>-0000.us-south.containers.appdomain.cloud
       secretName: <custom_secret_name>
   

3. リソース・ファイルを保存します。

4. リソースがカスタム・シークレット名を指すようになったことを確認します。 これらの変更は ALB に自動的に適用されます。

   kubectl get ingress alb-default-server -n kube-system -o yaml
   

接続処理の微調整

client-header-timeout、 client-body-timeout、 keep-alive の設定は、クライアント、Ingressコントローラー、バックエンドサーバー間の接続がアクティブな状態を維持する時間を決定する重要な設定である。 これらのタイムアウトは、リクエスト処理を最適化する上で重要な役割を果たす。特に、長く続くクライアント接続、バックエンドサーバーからの応答の遅れ、貴重なリソースが不必要に占有されないようにすることなどに対処する。

client-header-timeout は、サーバーが完全なクライアントヘッダーを待つ最大時間を定義する。 同様に、 client-body-timeout は、クライアントがリクエスト本文を送るまでサーバーが待つ時間を示す。 これらのタイムアウトはいずれも、 keep-alive パラメータと一致しなければならない。このパラメータは、サーバーが次の リクエストを待っている間、どれだけの時間コネクションをオープンにしておくかを 規定する。 これらのタイムアウトがキープアライブ設定と一致しない場合、 NGINX は接続を終了する。これは、クライアントの予期せぬ動作やリクエストの失敗につながる可能性がある。

これらのパラメータは、 kube-system 名前空間にある ibm-k8s-controller-config （ ConfigMap ）で設定できます。

apiVersion: v1
kind: ConfigMap
metadata:
  name: ibm-k8s-controller-config
  namespace: kube-system
data:
  ...
  client-body-timeout: "100"
  client-header-timeout: "100"
  keep-alive: "100"

詳細は client-header-timeout, client-body-timeout および keep-aliveNginx オプションを参照のこと。

ALB のパフォーマンスの調整

Ingress ALB のパフォーマンスを最適化するために、必要に応じてデフォルト設定を変更できます。