Container Service for Kubernetes:NGINX Ingress設定ディクショナリ

目次

デフォルトのConfigMap設定

NGINX Ingressによって使用されるConfigMapの設定を変更するには、kubectl edit cm -n kube-system nginx-configurationコマンドを実行します。 次のサンプルコードブロックは、ConfigMapのデフォルト設定を示しています。 詳細については、「公式ドキュメント」をご参照ください。

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-configuration
 namespace: <Namespace>  # Default value: kube-system.
 labels:
   app: ingress-nginx
data:
   log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
   proxy-body-size: 20m
   proxy-connect-timeout: "10"
   max-worker-connections: "65536"
   enable-underscores-in-headers: "true"
   reuse-port: "true"
   worker-cpu-affinity: "auto"
   server-tokens: "false"
   ssl-redirect: "false"
   allow-backend-server-header: "true"
   ignore-invalid-headers: "true"
   generate-request-id: "true"
   upstream-keepalive-timeout: "900"

次の表に、上記のコードブロックのフィールドを示します。

Ingressの注釈

NGINX Ingressコントローラーを使用する場合、ビジネス要件を満たすようにコントローラーの設定を変更できます。 NGINXの動作を制御するには、NGINX Ingressにアノテーションを追加します。 次の表は、一般的なNGINX Ingressアノテーションを示しています。 詳細については、「NGINX Ingress annotations」をご参照ください。

負荷分散アルゴリズム

NGINX Ingressは、バックエンドサービス間のトラフィック分散を最適化するためのさまざまな負荷分散アルゴリズムを提供します。 アプリケーションの機能と要件に基づいて、負荷分散アルゴリズムを選択できます。

次のサンプルYAMLファイルは、負荷分散のためにコンシステントハッシングを設定する方法の例を示しています。

apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Use the Uniform Resource Identifier (URI) of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Use the URI and domain name of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Use the URI of the request and a custom text value for hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              service:
                name: <YOUR_SERVICE_NAME>  # Replace the value with the actual Service name.
                port:
                  number: <YOUR_SERVICE_PORT>  # Replace the value with the actual Service port.
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Use the URI of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Use the URI and domain name of the request for hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Use the URI of the request and a custom text value for hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              serviceName: <YOUR_SERVICE_NAME>  # Replace the value with the actual Service name.
              servicePort: <YOUR_SERVICE_PORT>  # Replace the value with the actual Service port.

クッキー親和性

次の表に、cookieベースのセッションアフィニティの設定に使用できるアノテーションを示します。

次のサンプルYAMLファイルは、cookieベースのアフィニティを設定する方法の例を示しています。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
spec:
  ingressClassName: nginx
  rules:
  - host: stickyingress.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port: 
              number: 80

リダイレクト

次の表に、NGINX Ingressのリダイレクトの設定に使用できるアノテーションを示します。

次のサンプルIngress設定では、永続的なリダイレクトの宛先URLを指定する方法を示します。 Ingressルールを実装すると、foo.comへのリクエストはbar.comにリダイレクトされます。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
  - host: foo.com
    http:
      paths:
      - path: "/"
        pathType: ImplementationSpecific
        backend:
         service:
            name: httpbin
            port:
              number: 8000

書き換え

次の表に、NGINX Ingressの書き換えの設定に使用できるアノテーションを示します。

次のサンプルIngress設定は、ホストの書き換えを設定する方法を示しています。 Ingressルールを実装すると、システムはリクエストのホスト名をs test.com/test. o example.com/test書き換えます。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: ImplementationSpecific

スロットリング

サービスの安定性を確保するために、各クライアントIPアドレスから送信されるリクエストの頻度と同時実行性を制御するように調整ポリシーを設定できます。 次の表に、スロットリングの設定に使用できるアノテーションを示します。

次のサンプルIngress設定では、スロットリングの設定方法を示します。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: 100K
    nginx.ingress.kubernetes.io/limit-whitelist: 10.1.10.100
    nginx.ingress.kubernetes.io/limit-rps: 1
    nginx.ingress.kubernetes.io/limit-rpm: 30
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-backend-svc
          servicePort: 80

フォールバック

サービスの高可用性と安定性を確保するために、NGINX Ingressはディザスタリカバリ (フォールバック) 設定を提供しており、ノードの使用不能や特定のエラーなどの問題を解決できます。 次の表に、ディザスタリカバリの設定に使用できるアノテーションを示します。

カナリアリリース

カナリアリリースと青緑色展開は、アプリケーションのシームレスなアップグレードと高可用性を確保するために広く使用されています。 次の表に、サービスリリースのさまざまな要件を満たすように柔軟なトラフィック制御を構成するために使用できる注釈を示します。 詳細については、「NGINX Ingressコントローラーを使用したカナリアリリースとブルーグリーンリリースの実装」をご参照ください。

タイムアウト

次の表では、NGINX Ingressのタイムアウトを設定するために使用できるアノテーションについて説明します。これには、特定のリソースのグローバル設定とカスタムタイムアウト設定が含まれます。 適切なタイムアウト設定により、接続パフォーマンスと信頼性を最適化できます。

• グローバルタイムアウトの設定

  kubectl edit cm -n kube-system nginx-configurationコマンドを実行して、グローバルタイムアウト設定の次のフィールドを設定します。

  設定オプション	説明	デフォルト値
  proxy-connect-timeout	プロキシサーバーとの接続を確立するためのタイムアウト時間を設定します。 一般に、この値は75sを超えることはできない。	5s
  proxy-read-timeout	プロキシサーバーから応答を読み取るためのタイムアウト時間を設定します。 このタイムアウト期間は、応答全体の送信ではなく、2つの連続する読み出し動作の間に適用される。	60s
  proxy-send-timeout	プロキシサーバーにリクエストを送信するためのタイムアウト時間を設定します。 このタイムアウト期間は、要求全体の送信ではなく、2つの連続する書き込み動作の間に適用される。	60s
  proxy-stream-next-upstream-timeout	次のサーバーに接続を渡すために許可される時間を制限します。 値を0に設定した場合、制限は課されません。	600s
  proxy-stream-timeout	クライアントまたはプロキシサーバー接続での2つの連続した読み取りまたは書き込み操作間のタイムアウト期間を設定します。 その期間内にデータが送信されない場合、接続は閉じられる。	600s
  upstream-keepalive-timeout	上流サーバーとのアイドル接続を開いたままにするためのタイムアウト期間を設定します。	オープンソース版: 60s ACKエディション: 900s
  worker-shutdown-timeout	グレースフルシャットダウンのタイムアウト期間を設定します。	240s
  proxy-protocol-header-timeout	プロキシプロトコルヘッダーを受信するためのタイムアウト期間を設定します。 デフォルト値は、トランスポート層セキュリティ (TLS) パススルーハンドラが接続の切断を無期限に待機するのを防ぎます。	5s
  ssl-session-timeout	セッションキャッシュのSSLセッションパラメーターの有効期間を設定します。 有効期限は作成時刻に左右されます。 各セッションキャッシュは約0.25 MBのスペースを占有します。	10m
  client-body-timeout	クライアント要求本文を読み取るためのタイムアウト期間を設定します。	60s
  client-header-timeout	クライアント要求ヘッダーを読み取るためのタイムアウト期間を設定します。	60s

• 特定のリソースのカスタムタイムアウト設定

  次の表に、特定のリソースのタイムアウト設定を構成するために使用できるアノテーションを示します。

  注釈	説明
  nginx.ingress.kubernetes.io/proxy-connect-timeout	プロキシサーバーとの接続を確立するためのタイムアウト時間を設定します。
  nginx.ingress.kubernetes.io/proxy-send-timeout	プロキシサーバーにデータを送信するためのタイムアウト期間を設定します。
  nginx.ingress.kubernetes.io/proxy-read-timeout	プロキシサーバーからデータを読み取るためのタイムアウト時間を設定します。
  nginx.ingress.kubernetes.io/proxy-request-buffering	リクエストバッファリング機能を有効にするかどうかを指定します。 有効な値： on: リクエストのバッファリングを有効にします。 リクエストバッファリングが有効になった後、リクエストデータは完全に受信された後にのみバックエンドワークロードに転送されます。 HTTP/1.1チャンク化されたリクエストは、この設定の対象ではなく、常にバッファリングされます。 off: リクエストのバッファリングを無効にします。 リクエストバッファリングが無効になった後、データ送信中にエラーが発生した場合、ワークロードは再試行のために選択されません。

CORS

NGINX Ingressコントローラーにクロスオリジンリソース共有 (CORS) を設定した後、指定したリソースにオリジン間でアクセスできるようにすることができます。 詳細については、「NGINX IngressでのCORSの設定」をご参照ください。

再試行ポリシー

次の表に、再試行ポリシーの構成に使用できる注釈を示します。 再試行により、アプリケーションの可用性と耐障害性が向上します。

IPアドレスベースのアクセス制御

次の表に、NGINX IngressのIPホワイトリストとブラックリストの設定に使用できるアノテーションを示します。

次のサンプルIngress設定は、IPホワイトリストを設定する方法を示しています。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: 10.1.10.2
spec:
  rules:
  - host: iphone.exmaple.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-example-svc
          servicePort: 80

グローバル設定を設定するには、kubectl edit cm -n kube-system nginx-configurationコマンドを実行し、whitelist-source-rangeフィールドを変更します。

トラフィックミラーリング

次の表に、トラフィックミラーリングの設定に使用できるアノテーションを示します。 トラフィックミラーリングは、本番環境のサービスを中断することなく潜在的なリスクを検出し、アプリケーションの安定性を向上させます。 詳細については、「Ingressコントローラーを使用したネットワークトラフィックのミラーリング」をご参照ください。

セキュリティ保護

セキュリティ保護を設定して、クライアントとゲートウェイ間の通信を保護できます。 次の表に、通信の暗号化に使用できるアノテーションを示します。 詳細については、「NGINX Ingressコントローラーの暗号化」をご参照ください。

• クライアントとゲートウェイ間の暗号化通信

  次の表に、クライアントとゲートウェイ間の通信の暗号化に使用できるアノテーションを示します。

  注釈	スコープ	説明
  nginx.ingress.kubernetes.io/ssl-cipher	ドメイン名	TLS暗号スイートを指定します。 カンマ (,) で区切られた複数のTLS暗号スイートを指定できます。 このパラメーターは、TLSハンドシェイク中に1.0から1.2までのTLSバージョンが使用されている場合にのみ有効です。 デフォルトの暗号スイート: ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
  nginx.ingress.kubernetes.io/auth-tls-secret	ドメイン名	相互TLS (mTLS) ハンドシェイク中にクライアントが提供する証明書を検証するためにゲートウェイが使用する認証局 (CA) 証明書を指定します。 この注釈は、ゲートウェイがクライアントのIDを検証する必要があるシナリオに適しています。 対応するシークレットには、ca.crtという名前のファイルを含める必要があります。 ca.crtファイルには完全なCAチェーンが含まれています。

• ゲートウェイとバックエンドサービス間の暗号化通信

  次の表に、バックエンドサービスとゲートウェイ間の通信の暗号化に使用できるアノテーションを示します。

  注釈	スコープ	説明
  nginx.ingress.kubernetes.io/proxy-ssl-secret	サービス	ゲートウェイで使用されるクライアント証明書を指定します。 クライアント証明書は、ゲートウェイを認証するためにバックエンドサービスによって使用されます。 指定された証明書は、プライバシー強化メール (PEM) 形式である必要があります。 シークレットには、次のファイルを含める必要があります。 tls.crt: クライアント証明書。 tls.key: クライアント証明書の秘密鍵。 ca.crt: プロキシHTTPSサーバーの認証に使用される信頼できるCA証明書。 値は "namespace/secretName" 形式でなければなりません。
  nginx.ingress.kubernetes.io/proxy-ssl-name	サービス	TLSハンドシェイク中に使用されるサーバー名表示 (SNI) を指定します。
  nginx.ingress.kubernetes.io/proxy-ssl-server-name	サービス	TLSハンドシェイク中に使用されるSNIを有効にするか無効にするかを指定します。

セキュリティ認証

次の表に、許可されたユーザーのみがアプリケーションにアクセスできるように基本認証を構成するために使用できる注釈を示します。

手順：

1. htpasswdコマンドラインツールを使用して、パスワードファイルを生成します。

   htpasswd -c auth joker

   パスワードファイルを表示します。

   cat auth 
   # Expected output: joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

2. パスワードファイルに基づいてシークレットを作成します。

   kubectl create secret generic basic-auth --from-file=auth 

3. Ingress設定で基本認証を有効にします。 例：

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-nginx
     annotations:
       kubernetes.io/ingress.class: "nginx"
       nginx.ingress.kubernetes.io/auth-type: basic
       nginx.ingress.kubernetes.io/auth-secret: basic-auth
   spec:
     rules:
     - host: iphone.example.com 
       http:
         paths:
         - path: 
           backend:
             serviceName: iphone-backend-svc
             servicePort: 80