このページでは、Google Cloud で Kubernetes Ingress を通じてサポートされ、構成可能な機能について包括的な概要を示します。Google Kubernetes Engine（GKE）と Anthos の Ingress では、Google Cloud VPC ネットワークとの緊密な統合によりエンタープライズクラス向けの負荷分散を行うことができます。
機能の比較
Google Cloud でサポートされている Ingress の機能の一覧については、次の表をご覧ください。機能の可用性（一般提供（GA）、ベータ版）も示されています。
| Ingress クラス | 外部 Ingress | 内部 Ingress | マルチクラスタ Ingress |
|---|---|---|---|
| Ingress コントローラ | Google がホストする Ingress コントローラ | ||
| Google Cloud ロードバランサのタイプ | 外部 HTTP(S) 負荷分散 | 内部 HTTP(S) 負荷分散 | 外部 HTTP(S) 負荷分散 |
| クラスタのスコープ | 単一クラスタ | 単一クラスタ | マルチクラスタ |
| ロードバランサのスコープ | グローバル | リージョン | グローバル |
| バージョン サポート | すべて | GKE 1.16.5 以降 | GKE 1.14 以降 |
| 環境サポート | GKE | GKE | GKE |
| 共有 VPC のサポート | 一般提供 | 一般提供 | 一般提供 |
| Service アノテーション | |||
| コンテナ ネイティブの負荷分散（NEG） | 一般提供 | 一般提供 | 一般提供 |
| ロードバランサからバックエンドへの HTTPS | 一般提供 | 一般提供 | 一般提供 |
| HTTP/2 | 一般提供 | 一般提供 TLS のみ |
一般提供 |
| Ingress アノテーション | |||
| 静的 IP アドレス | 一般提供 | 一般提供 | 一般提供 |
| Kubernetes Secret ベースの証明書 | 一般提供 | 一般提供 | 一般提供 |
| セルフマネージド SSL 証明書 | 一般提供 | 一般提供 | 一般提供 |
| Google マネージド SSL 証明書 | 一般提供 | 一般提供 | |
| FrontendConfig | |||
| SSL ポリシー | 一般提供 | 一般提供 | |
| HTTP から HTTPS へのリダイレクト | 一般提供 1.17.13-gke.2600+一般提供 |
一般提供 | |
| BackendConfig | |||
| バックエンド サービスのタイムアウト | 一般提供 | 一般提供 | 一般提供 |
| Cloud CDN | 一般提供 | 一般提供 | |
| コネクション ドレインのタイムアウト | 一般提供 | 一般提供 | 一般提供 |
| カスタムのロードバランサのヘルスチェック構成 | 一般提供 | 一般提供 | 一般提供 |
| Google Cloud Armor セキュリティ ポリシー | 一般提供
1.19.10-gke.700G |
一般提供 | |
| HTTP アクセス ロギングの構成 | 一般提供 | 一般提供 | 一般提供 |
| Identity-Aware Proxy（IAP） | 一般提供 | 一般提供 | 一般提供 |
| セッション アフィニティ | 一般提供 | 一般提供 | 一般提供 |
| ユーザー定義のリクエスト ヘッダー | 一般提供 | 一般提供 | |
B この機能は、指定したバージョン以降のベータ版で利用できます。バージョンが表示されていない機能は、利用可能なすべての GKE と Anthos のバージョンでサポートされています。
G この機能は、指定したバージョン以降の一般提供リリースとしてサポートされます。
Ingress 機能の構成
Google Cloud SDK や Google Cloud コンソールを使用して LoadBalancer 機能を手動で構成することはできません。BackendConfig または FrontendConfig Kubernetes リソースを使用する必要があります。
デフォルトのコントローラを使用して Ingress を作成する場合、Ingress オブジェクトのアノテーションを使用して、ロードバランサのタイプ（外部 HTTP(S) ロードバランサまたは内部 HTTP(S) ロードバランサ）を選択できます。GKE でゾーン NEG を作成するか、各 Service オブジェクトでアノテーションを使用してインスタンス グループを使用するかを選択できます。
FrontendConfig と BackendConfig のカスタム リソース定義（CRD）を使用することで、ロードバランサをさらにカスタマイズできます。これらの CRD を使用すると、アノテーションよりも構造化された方法で、追加のロードバランサ機能を階層的に定義できます。Ingress とこれらの CRD を使用するには、HTTP 負荷分散アドオンが有効になっている必要があります。GKE クラスタの HTTP 負荷分散はデフォルトで有効になっています。無効にしないでください。
FrontendConfig 構成は Ingress オブジェクトで参照され、BackendConfig 構成は Service オブジェクトによって参照されます。構成の整合性を保つために、複数の Service オブジェクトまたは Ingress オブジェクトで同じ CRD を参照できます。FrontendConfig と BackendConfig CRD は、対応する Ingress リソースと Service リソースと同じライフサイクルを共有し、多くの場合一緒にデプロイされます。
次の図は、その方法を示しています。
Ingress または MultiClusterIngress オブジェクトのアノテーションは、FrontendConfig CRD を参照します。FrontendConfig CRD は Google Cloud SSL ポリシーを参照します。
Service または MultiClusterService オブジェクトのアノテーションは、BackendConfig CRD を参照します。BackendConfig CRD は、対応するバックエンド サービスのヘルスチェックのカスタム設定を指定します。
FrontendConfig の Ingress への関連付け
FrontendConfig は Ingress または MultiClusterIngress に関連付けることができます。
Ingress
networking.gke.io/v1beta1.FrontendConfig アノテーションを使用します。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
networking.gke.io/v1beta1.FrontendConfig: "FRONTENDCONFIG_NAME"
...
FRONTENDCONFIG_NAME は実際の FrontendConfig 名で置き換えます。
マルチクラスタ Ingress
networking.gke.io/frontend-config アノテーションを使用します。
apiVersion: networking.gke.io/v1
kind: MultiClusterIngress
metadata:
annotations:
networking.gke.io/frontend-config: "FRONTENDCONFIG_NAME"
...
FRONTENDCONFIG_NAME は実際の FrontendConfig 名で置き換えます。
BackendConfig の Ingress への関連付け
Service または MultiClusterService は、cloud.google.com/backend-config または beta.cloud.google.com/backend-config アノテーションを使用して BackendConfig の名前を指定できます。Service または MultiClusterService に関連付けられている場合、BackendConfig リソースは Google Cloud にバックエンド サービスの設定を作成または変更するように要求します。
以下はその例です。
GKE バージョン 1.16-gke.3 以降を使用している場合は、beta.cloud.google.com/backend-config アノテーションも使用できますが、cloud.google.com/backend-config アノテーションを使用してください。それ以前のバージョンでは、beta.cloud.google.com/backend-config アノテーションを使用する必要があります。
すべての Service ポートで同じ BackendConfig
Service または MultiClusterService のすべてのポートで同じ BackendConfig を使用するには、アノテーションで default キーを使用します。Ingress コントローラは、ロードバランサのバックエンド サービスを作成するたびに同じ BackendConfig を使用して、Service のポートの 1 つを参照します。
1.16-gke.3 以降
apiVersion: v1
kind: Service
metadata:
annotations:
cloud.google.com/backend-config: '{"default": "my-backendconfig"}'
...
サポートされているすべてのバージョン
apiVersion: v1
kind: Service
metadata:
annotations:
beta.cloud.google.com/backend-config: '{"default": "my-backendconfig"}'
...
Service ポートごとの一意の BackendConfig
ポートの名前またはポートの番号と一致するキーを使用して、Service または MultiClusterService の特定のポートにカスタム BackendConfig を指定できます。Ingress コントローラは、参照される Service ポートのロードバランサ バックエンド サービスを作成するときに、特定の BackendConfig を使用します。
1.16-gke.3 以降
apiVersion: v1
kind: Service
metadata:
annotations:
cloud.google.com/backend-config: '{"ports": {
"SERVICE_REFERENCE_A":"BACKENDCONFIG_REFERENCE_A",
"SERVICE_REFERENCE_B":"BACKENDCONFIG_REFERENCE_B"
}}'
spec:
ports:
- name: PORT_NAME_1
port: PORT_NUMBER_1
protocol: TCP
targetPort: 50000
- name: PORT_NAME_2
port: PORT_NUMBER_2
protocol: TCP
targetPort: 8080
...
サポートされているすべてのバージョン
apiVersion: v1
kind: Service
metadata:
annotations:
beta.cloud.google.com/backend-config: '{"ports": {
"SERVICE_REFERENCE_A":"BACKENDCONFIG_REFERENCE_A",
"SERVICE_REFERENCE_B":"BACKENDCONFIG_REFERENCE_B"
}}'
spec:
ports:
- name: PORT_NAME_1
port: PORT_NUMBER_1
protocol: TCP
targetPort: 50000
- name: PORT_NAME_2
port: PORT_NUMBER_2
protocol: TCP
targetPort: 8080
...
次のように置き換えます。
BACKENDCONFIG_REFERENCE_A: 既存の BackendConfig の名前。BACKENDCONFIG_REFERENCE_B: 既存の BackendConfig の名前。SERVICE_REFERENCE_A:PORT_NUMBER_1またはPORT_NAME_1の値を使用します。これは、Service の BackendConfig アノテーションがポートの名前（spec.ports[].name）またはポートの番号（spec.ports[].port）を参照できるためです。SERVICE_REFERENCE_B:PORT_NUMBER_2またはPORT_NAME_2の値を使用します。これは、Service の BackendConfig アノテーションがポートの名前（spec.ports[].name）またはポートの番号（spec.ports[].port）を参照できるためです。
Service のポートを数値で参照する場合は、targetPort 値ではなく port 値を使用する必要があります。ここで使用されるポート番号は、BackendConfig のバインドにのみ使用されます。ロードバランサがトラフィックまたはヘルスチェック プローブを送信するポートは制御されません。
コンテナ ネイティブのロード バランシングを使用する場合、ロードバランサは参照される Service ポート
targetPort（サービスを提供する Pod のcontainerPortと一致する必要があります）のネットワーク エンドポイント グループ（Pod IP アドレスと一致）のエンドポイントにトラフィックを送信します。それ以外の場合、ロードバランサは参照される Service ポートのnodePortでノードの IP アドレスにトラフィックを送信します。BackendConfig を使用してカスタム ロードバランサのヘルスチェックを提供する場合、ロードバランサのヘルスチェックに使用するポート番号は、Service の
spec.ports[].port番号と異なる場合があります。ヘルスチェックのポート番号の詳細については、カスタム ヘルスチェック構成をご覧ください。
FrontendConfig パラメータによる Ingress 機能の構成
次のセクションでは、特定の Ingress 機能を有効にするように FrontendConfig を設定する方法について説明します。
SSL ポリシー
SSL ポリシーを使用すると、ロードバランサがクライアントからの HTTPS トラフィックを終了するために使用する一連の TLS バージョンと暗号を指定できます。まず、GKE の外部で SSL ポリシーを作成する必要があります。作成すると、FrontendConfig CRD で参照できます。
FrontendConfig の sslPolicy フィールドは、GKE クラスタと同じ Google Cloud プロジェクト内の SSL ポリシーの名前を参照します。Ingress によって外部 HTTP(S) ロードバランサ用に作成されたターゲット HTTPS プロキシに SSL ポリシーが追加されます。複数の Ingress リソースで同じ FrontendConfig リソースと SSL ポリシーを参照できます。参照された SSL ポリシーが変更されると、Ingress によって作成された外部 HTTP(S) ロードバランサを実装する Google Front End（GFE）に変更が反映されます。
次の FrontendConfig マニフェストは、gke-ingress-ssl-policy という名前の SSL ポリシーを有効にします。
apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
name: my-frontend-config
spec:
sslPolicy: gke-ingress-ssl-policy
HTTP から HTTPS へのリダイレクト
外部 HTTP ロードバランサは、同じ IP アドレスを使用する HTTPS ロードバランサに、暗号化されていない HTTP リクエストをリダイレクトできます。HTTP から HTTPS へのリダイレクトを有効にして Ingress を作成すると、これらの両方のロードバランサが自動的に作成されます。ポート 80 の Ingress の外部 IP アドレスへのリクエストは、ポート 443 の同じ外部 IP アドレスに自動的にリダイレクトされます。この機能は、Cloud Load Balancing の HTTP から HTTPS へのリダイレクトをベースとしています。
HTTP から HTTPS へのリダイレクトをサポートするには、HTTP と HTTPS の両方のトラフィックを処理するように Ingress を構成する必要があります。HTTP と HTTPS のいずれかが無効になっていると、リダイレクトは機能しません。
HTTP から HTTPS へのリダイレクトは、FrontendConfig カスタム リソースの redirectToHttps フィールドを使用して構成されます。Ingress リソース全体に対してリダイレクトが有効になるため、Ingress が参照するすべてのサービスで HTTPS リダイレクトが有効になります。
次の FrontendConfig マニフェストを使用すると、HTTP から HTTPS へのリダイレクトが有効になります。HTTPS リダイレクトを有効にするには、spec.redirectToHttps.enabled フィールドを true に設定します。spec.responseCodeName フィールドは省略可能です。省略されている場合は、301 Moved
Permanently リダイレクトが使用されます。
apiVersion: networking.gke.io/v1beta1
kind: FrontendConfig
metadata:
name: my-frontend-config
spec:
redirectToHttps:
enabled: true
responseCodeName: RESPONSE_CODE
RESPONSE_CODE を次のいずれかに置き換えます。
MOVED_PERMANENTLY_DEFAULTは 301 リダイレクト レスポンス コードを返します（responseCodeNameが指定されていない場合のデフォルト）。FOUNDは 302 リダイレクト レスポンス コードを返します。SEE_OTHERは 303 リダイレクト レスポンス コードを返します。TEMPORARY_REDIRECTは 307 リダイレクト レスポンス コードを返します。PERMANENT_REDIRECTは 308 リダイレクト レスポンス コードを返します。
リダイレクトを有効にすると、Ingress コントローラは、次の図に示すようにロードバランサを作成します。
リダイレクトが機能しているか確認するには、curl コマンドを使用します。
curl http://IP_ADDRESS
IP_ADDRESS は、Ingress の IP アドレスに置き換えます。
構成したリダイレクト レスポンス コードがレスポンスに表示されます。たとえば、301: MovedPermanently リダイレクトで構成された FrontendConfig は次のようになります。
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://35.244.160.59/">here</A>.</BODY></HTML>
BackendConfig パラメータによる Ingress 機能の構成
次のセクションでは、特定の Ingress 機能を有効にするように BackendConfig を設定する方法について説明します。BackendConfig リソースへの変更は常に調整されるため、Ingress を削除して再作成しなくても BackendConfig の変更が反映されていることを確認できます。
BackendConfig の制限事項については、制限事項のセクションをご覧ください。
バックエンド サービスのタイムアウト
BackendConfig を使用して、バックエンド サービスのタイムアウト期間を秒単位で設定できます。値を指定しない場合、デフォルト値は 30 秒です。
次の BackendConfig マニフェストは、40 秒のタイムアウトを指定します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
timeoutSec: 40
Cloud CDN
BackendConfig を使用して、Cloud CDN を有効にできます。
次の BackendConfig マニフェストには、Cloud CDN を有効にするときに使用できるすべてのフィールドが表示されます。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
cdn:
enabled: CDN_ENABLED
cachePolicy:
includeHost: INCLUDE_HOST
includeProtocol: INCLUDE_PROTOCOL
includeQueryString: INCLUDE_QUERY_STRING
queryStringBlacklist: QUERY_STRING_DENYLIST
queryStringWhitelist: QUERY_STRING_ALLOWLIST
cacheMode: CACHE_MODE
clientTtl: CLIENT_TTL
defaultTtl: DEFAULT_TTL
maxTtl: MAX_TTL
negativeCaching: NEGATIVE_CACHING
negativeCachingPolicy:
code: NEGATIVE_CACHING_CODE
ttl: NEGATIVE_CACHING_TTL
requestCoalescing: REQ_COALESCING
serveWhileStale: SERVE_WHILE_STALE
signedUrlCacheMaxAgeSec: SIGNED_MAX_AGE
signedUrlKeys:
keyName: KEY_NAME
keyValue: KEY_VALUE
secretName: SECRET_NAME
次のように置き換えます。
CDN_ENABLED:trueに設定すると、この Ingress バックエンドの Cloud CDN が有効になります。INCLUDE_HOST:trueに設定すると、異なるホストへのリクエストは個別にキャッシュされます。INCLUDE_PROTOCOL:trueに設定すると、HTTP リクエストと HTTPS リクエストは個別にキャッシュされます。INCLUDE_QUERY_STRING:trueに設定すると、queryStringBlacklistまたはqueryStringWhitelistに従ってクエリ文字列パラメータがキャッシュキーに含まれます。どちらも設定されていない場合は、クエリ文字列全体が含まれます。falseに設定すると、クエリ文字列全体がキャッシュキーから除外されます。QUERY_STRING_DENYLIST: キャッシュキーから除外するクエリ文字列パラメータの名前を含む文字列配列を指定します。これ以外のパラメータはすべて含まれます。queryStringBlacklistまたはqueryStringWhitelistを指定できますが、両方は指定できません。QUERY_STRING_ALLOWLIST: キャッシュキーに含めるクエリ文字列パラメータの名前を含む文字列配列を指定します。これ以外のパラメータはすべて除外されます。queryStringBlacklistまたはqueryStringWhitelistを使用できますが、両方は使用できません。
次のフィールドは、GKE Ingress を使用する GKE バージョン 1.23.3-gke.900 以降でのみサポートされています。マルチクラスタ Ingress の使用はサポートされていません。
CACHE_MODE: キャッシュ モード。CLIENT_TTL、DEFAULT_TTL、MAX_TTL: TTL の構成。詳細については、TTL の設定とオーバーライドを使用するをご覧ください。NEGATIVE_CACHING:trueに設定すると、ネガティブ キャッシュが有効になります。詳しくは、ネガティブ キャッシュの使用をご覧ください。NEGATIVE_CACHING_CODE、NEGATIVE_CACHING_TTL: ネガティブ キャッシュの構成。詳しくは、ネガティブ キャッシュの使用をご覧ください。REQ_COALESCING:trueに設定すると、コラプシングが有効になります。詳細については、リクエスト コラプシング（コーレッシング）をご覧ください。SERVE_WHILE_STALE: レスポンスの有効期限が切れてから Cloud CDN が古いバージョンの配信を継続できる時間（秒）。詳しくは、古いコンテンツの配信をご覧ください。SIGNED_MAX_AGE: レスポンスをキャッシュに保存できる最大期間（秒）。詳しくは、最大キャッシュ時間をカスタマイズするをご覧ください。KEY_NAME、KEY_VALUE、SECRET_NAME: 署名付き URL 鍵の構成。詳細については、署名付きリクエスト鍵の作成をご覧ください。
Ingress によって Cloud CDN をデプロイし、アプリケーション コンテンツがキャッシュに保存されていることを確認する例を見るには、次のセクションを展開してください。
コネクション ドレインのタイムアウト
コネクション ドレインのタイムアウトは、BackendConfig を使用して構成できます。コネクション ドレインのタイムアウトは、接続がドレインするまで待機する時間（秒）です。指定されたタイムアウト期間の間、除外されたバックエンドに対する既存のリクエストに、完了するまでの時間が与えられます。ロードバランサは、削除されたバックエンドに新しいリクエストを送信しません。タイムアウト時間に達すると、バックエンドに対する残りの接続がすべて閉じます。タイムアウト時間は 0～3,600 秒に設定できます。デフォルト値は 0 で、この場合、コネクション ドレインも無効になります。
次の BackendConfig マニフェストは、コネクション ドレインのタイムアウトを 60 秒に指定します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
connectionDraining:
drainingTimeoutSec: 60
カスタム ヘルスチェックの構成
Ingress によってデプロイされるときに、GKE で Google Cloud ロードバランサのヘルスチェックを構成する方法は多岐におよびます。GKE Ingress によるヘルスチェックのデプロイ方法の詳細については、Ingress ヘルスチェックをご覧ください。
BackendConfig を使用すると、ロードバランサのヘルスチェック設定を正確に制御できます。
再利用可能なテンプレートとして同じ BackendConfig を参照するように複数の GKE Service を構成できます。healthCheck パラメータについては、各 GKE Service に対応するバックエンド サービスごとに一意の Google Cloud ヘルスチェックが作成されます。
次の BackendConfig マニフェストは、BackendConfig ヘルスチェックの構成時に使用可能なすべてのフィールドを示します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
healthCheck:
checkIntervalSec: INTERVAL
timeoutSec: TIMEOUT
healthyThreshold: HEALTH_THRESHOLD
unhealthyThreshold: UNHEALTHY_THRESHOLD
type: PROTOCOL
requestPath: PATH
port: PORT
次のように置き換えます。
INTERVAL: 各ヘルスチェック プローバーのcheck-intervalを秒単位で指定します。これは、プローバーのチェックを開始してから次のチェックを開始するまでの時間です。このパラメータを省略すると、Google Cloud のデフォルトの 5 秒が使用されます。実装の詳細については、複数のプローブと頻度をご覧ください。TIMEOUT: Google Cloud でプローブへのレスポンスを待機する時間を指定します。TIMEOUTの値は、INTERVAL以下にする必要があります。単位は秒です。各プローブでは、タイムアウトの前にHTTP 200 (OK)レスポンス コードが配信される必要があります。HEALTH_THRESHOLDとUNHEALTHY_THRESHOLD: 正常から異常、または異常から正常に健全性を変更するために、少なくとも 1 つのプローバーについて、プローブの成功または失敗の連続回数を示します。これらのパラメータのいずれかを省略した場合、Google Cloud ではデフォルト値の 2 が使用されます。PROTOCOL: ヘルスチェックのためにプローブ システムで使用されるプロトコルを指定します。BackendConfigは、HTTP、HTTPS、または HTTP2 プロトコルを使用したヘルスチェックの作成のみをサポートします。詳細については、HTTP、HTTPS、HTTP/2 での成功基準をご覧ください。このパラメータは省略できません。PATH: HTTP、HTTPS、または HTTP2 のヘルスチェックの場合は、プローブ システムが接続するrequest-pathを指定します。このパラメータを省略した場合、Google Cloud ではデフォルトの/が使用されます。PORT: BackendConfig では、ポート番号を使用したロードバランサのヘルスチェック ポートの指定のみがサポートされています。このパラメータを省略した場合、Google Cloud ではデフォルト値の80が使用されます。コンテナ ネイティブのロード バランシングを使用する場合は、
containerPortが Service のtargetPortによって参照されているかどうかに関係なく、サービスを提供する Pod のcontainerPortに一致するポートを選択する必要があります。ロードバランサは、Pod の IP アドレスにプローブを直接送信するため、Service のtargetPortによって参照されるcontainerPortは制限されません。ヘルスチェック プローブ システムは、指定したポートでサービスを提供する Pod の IP アドレスに接続します。インスタンス グループのバックエンドでは、Service によって公開される
nodePortに一致するポートを選択する必要があります。その後、ヘルスチェック プローブ システムがそのポートの各ノードに接続します。
Google Cloud Armor Ingress セキュリティ ポリシー
Google Cloud Armor セキュリティ ポリシーは、負荷分散されたアプリケーションをウェブベースの攻撃から保護するのに役立ちます。Google Cloud Armor セキュリティ ポリシーを構成すると、BackendConfig を使用して参照できます。
セキュリティ ポリシーの名前を BackendConfig に追加します。次の BackendConfig マニフェストでは、example-security-policy という名前のセキュリティ ポリシーを指定しています。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
namespace: cloud-armor-how-to
name: my-backendconfig
spec:
securityPolicy:
name: "example-security-policy"
HTTP アクセス ロギング
Ingress は、クライアントからのすべての HTTP リクエストを Cloud Logging に記録できます。アクセス ロギングを有効または無効にするには、BackendConfig とアクセス ロギングのサンプリング レートの設定を使用します。
アクセス ロギングを構成するには、BackendConfig の logging フィールドを使用します。logging を省略すると、アクセス ロギングはデフォルトの動作を実行します。これは GKE のバージョンによって異なります。
次のフィールドを構成できます。
enable:trueに設定した場合、この Ingress のアクセス ロギングが有効になり、ログが Cloud Logging で使用できるようになります。それ以外の場合、この Ingress のアクセス ロギングは無効になります。sampleRate: 0.0 から 1.0 までの値を指定します。0.0 の場合、パケットをまったくログに記録されません。1.0 の場合、すべてのパケットがログに記録されます。このフィールドは、enableがtrueに設定されている場合にのみ機能します。sampleRateはオプションのフィールドですが、構成されている場合はenable: trueも設定する必要があります。設定しなければ、enable: falseと解釈されます。
次の BackendConfig マニフェストは、アクセス ロギングを有効にし、特定の Ingress リソースに対する HTTP リクエストのサンプルレートを 50% に設定します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
logging:
enable: true
sampleRate: 0.5
Identity-Aware Proxy
Identity-Aware Proxy IAP の BackendConfig を構成するには、BackendConfig の iap ブロックに enabled と secretName の値を指定する必要があります。これらの値を指定するには、compute.backendServices.update 権限が必要です。
次の BackendConfig マニフェストは、Identity-Aware Proxy を有効にします。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
iap:
enabled: true
oauthclientCredentials:
secretName: my-secret
詳細な手順については、IAP のドキュメントの GKE での IAP の有効化をご覧ください。
内部 Ingress を持つ Identity-Aware Proxy
IAP の内部 Ingress を構成するには、プレミアム ティアを使用する必要があります。プレミアム ティアを使用しない場合は、Identity-Aware Proxy を使用して内部 HTTP(S) ロードバランサの表示や作成を行うことはできません。IAP の内部 Ingress を使用するには、BeyondCorp Enterprise サブスクリプションも必要です。
セッション アフィニティ
BackendConfig を使用して、セッション アフィニティをクライアント IP または生成された Cookie に設定できます。
クライアント IP アフィニティ
BackendConfig を使用してクライアント IP アフィニティを設定するには、次の例のように affinityType を "CLIENT_IP" に設定します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
sessionAffinity:
affinityType: "CLIENT_IP"
生成された Cookie アフィニティ
BackendConfig を使用して生成された Cookie アフィニティを設定するには、BackendConfig マニフェストで affinityType を GENERATED_COOKIE に設定します。また、affinityCookieTtlSec を使用して、Cookie を有効のままにしておく期間を設定することもできます。
次のマニフェストでは、アフィニティ タイプを生成された Cookie に設定し、Cookie の TTL を 50 秒に設定します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
sessionAffinity:
affinityType: "GENERATED_COOKIE"
affinityCookieTtlSec: 50
ユーザー定義のリクエスト ヘッダー
BackendConfig を使用して、ユーザー定義のリクエスト ヘッダーを構成できます。ロードバランサは、指定したヘッダーをバックエンドに転送するリクエストに追加します。
ユーザー定義のリクエスト ヘッダーを有効にするには、BackendConfig リソースの customRequestHeaders プロパティにヘッダーのリストを指定します。各ヘッダーを header-name:header-value 文字列として指定します。
次の BackendConfig マニフェストは、3 つのリクエスト ヘッダーを追加します。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
customRequestHeaders:
headers:
- "X-Client-Region:{client_region}"
- "X-Client-City:{client_city}"
- "X-Client-CityLatLong:{client_city_lat_long}"
演習: バックエンド サービスを使用した Ingress タイムアウトの設定
次の演習では、BackendConfig リソースを使用して Ingress でタイムアウトとコネクション ドレインを構成するために必要な手順を示します。
Ingress のバックエンド プロパティを構成するには、次の操作を行います。
- Deployment を作成します。
- BackendConfig を作成します。
- Service を作成し、そのポートの 1 つを BackendConfig に関連付けます。
- Ingress を作成して、その Ingress を（Service、ポート）ペアに関連付けます。
- バックエンド サービスのプロパティを検証します。
- クリーンアップします。
Deployment を作成する
BackendConfig と Service を作成する前に、Deployment を作成する必要があります。
次のマニフェストの例では、my-deployment.yaml という Deployment になります。
# my-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
spec:
selector:
matchLabels:
purpose: bsc-config-demo
replicas: 2
template:
metadata:
labels:
purpose: bsc-config-demo
spec:
containers:
- name: hello-app-container
image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
次のコマンドを実行して Deployment を作成します。
kubectl apply -f my-deployment.yaml
BackendConfig を作成する
BackendConfig を使用して、使用する Ingress 機能を指定します。
この my-backendconfig.yaml という名前の BackendConfig マニフェストでは、以下を指定しています。
- タイムアウトを 40 秒に設定しています。
- コネクション ドレイン タイムアウトを 60 秒に設定しています。
# my-backendconfig.yaml
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
timeoutSec: 40
connectionDraining:
drainingTimeoutSec: 60
BackendConfig を使用して設定できる機能の一覧については、機能表の BackendConfig のセクションを参照してください。
次のコマンドを実行して BackendConfig を作成します。
kubectl apply -f my-backendconfig.yaml
Service の作成
BackendConfig は、Service に複数のポートがある場合でも、単一の Service と Port の組み合わせに対応します。各ポートは、1 つの BackendConfig CRD に関連付けることができます。Ingress が Service ポートを参照し、その Service ポートが BackendConfig に関連付けられている場合、HTTP(S) 負荷分散バックエンド サービスは BackendConfig による構成に影響を与えます。
my-service.yaml という名前の Service マニフェストの例を次に示します。
# my-service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-service
labels:
purpose: bsc-config-demo
annotations:
cloud.google.com/backend-config: '{"ports": {"80":"my-backendconfig"}}'
cloud.google.com/neg: '{"ingress": true}'
spec:
type: ClusterIP
selector:
purpose: bsc-config-demo
ports:
- port: 80
protocol: TCP
targetPort: 8080
cloud.google.com/backend-config アノテーションでは、ポートと BackendConfig オブジェクトの間のマッピングが指定されます。my-service.yaml で:
purpose: bsc-config-demoというラベルを持つすべての Pod は Service のメンバーです。- Service の TCP ポート 80 が
my-backendconfigという名前の BackendConfig に関連付けられています。これは、cloud.google.com/backend-configアノテーションで指定されています。 - Service のポート 80 に送信されたリクエストは、いずれかのメンバー Pod（ポート 8080）に転送されます。
Service を作成するには、次のコマンドを実行します。
kubectl apply -f my-service.yaml
Ingress を作成する
次の my-ingress.yaml. という名前の Ingress マニフェストの例では、my-service という名前の Service のポート 80 に受信リクエストがルーティングされています。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-ingress
spec:
rules:
- http:
paths:
- path: /*
pathType: ImplementationSpecific
backend:
service:
name: my-service
port:
number: 80
Ingress を作成するには、次のコマンドを実行します。
kubectl apply -f my-ingress.yaml
Ingress コントローラが HTTP(S) 負荷分散と関連するバックエンド サービスを構成するまで数分待ちます。上記の手順が完了すると、Ingress が 40 秒のタイムアウトと 60 秒のコネクション ドレインのタイムアウトを使用するように構成されます。
バックエンド サービスのプロパティを確認する
BackendConfig を使用して、正しいロードバランサの設定が適用されていることを確認できます。これを行うには、Ingress がデプロイしたバックエンド サービスを特定し、その設定を調べて Deployment マニフェストと一致していることを確認します。
まず、my-ingress リソースを記述し、Ingress に関連付けられたバックエンド サービスを一覧表示するアノテーションをフィルタリングします。例:
kubectl describe ingress my-ingress | grep ingress.kubernetes.io/backends
出力は次のようになります。
ingress.kubernetes.io/backends: '{"k8s1-27fde173-default-my-service-80-8d4ca500":"HEALTHY","k8s1-27fde173-kube-system-default-http-backend-80-18dfe76c":"HEALTHY"}
出力には、バックエンド サービスに関する情報が表示されます。たとえば、このアノテーションには 2 つのバックエンド サービスが含まれています。
"k8s1-27fde173-default-my-service-80-8d4ca500":"HEALTHY"は、my-serviceKubernetes Service に関連したバックエンド サービスに関する情報を示しています。k8s1-27fde173は、クラスタの説明に使用されるハッシュです。defaultは Kubernetes 名前空間です。HEALTHYは、バックエンドが正常であることを示します。
"k8s1-27fde173-kube-system-default-http-backend-80-18dfe76c":"HEALTHY"は、デフォルトのバックエンド（404 サーバー）に関連したバックエンド サービスに関する情報を示しています。k8s1-27fde173は、クラスタの説明に使用されるハッシュです。kube-systemは名前空間です。default-http-backendKubernetes Service の名前です。80はホストのポートです。HEALTHYは、バックエンドが正常であることを示します。
次に、gcloud を使用して、my-service に関連付けられているバックエンド サービスを検査します。"drainingTimeoutSec" と "timeoutSec" をフィルタリングして、Google Cloud ロードバランサのコントロール プレーンで設定されていることを確認します。例:
# Optionally, set a variable
export BES=k8s1-27fde173-default-my-service-80-8d4ca500
# Filter for drainingTimeoutSec and timeoutSec
gcloud compute backend-services describe ${BES} --global | grep -e "drainingTimeoutSec" -e "timeoutSec"
出力:
drainingTimeoutSec: 60
timeoutSec: 40
出力に drainingTimeoutSec と timeoutSec が表示されていることで、BackendConfig で値が正しく設定されていることを確認できます。
クリーンアップ
アカウントで不要な料金が発生しないように、この演習用に作成した Kubernetes オブジェクトを削除します。
kubectl delete ingress my-ingress
kubectl delete service my-service
kubectl delete backendconfig my-backendconfig
kubectl delete deployment my-deployment
BackendConfig の制限事項
BackendConfig には次の制限があります。
複数の Ingress オブジェクトが（Service、ポート）を参照する場合でも、1 つの（Service、ポート）ペアが使用できるのは 1 つの BackendConfig だけです。つまり、同じ（Service、ポート）を参照するすべての Ingress オブジェクトで、Google Cloud Armor、IAP、Cloud CDN に対する構成を同一にする必要があります。
IAP と Cloud CDN を同じ HTTP(S) 負荷分散バックエンド サービスで有効にすることはできません。つまり、同じ BackendConfig に IAP と Cloud CDN の両方を構成することはできません。
BackendConfig を使用して操作する場合、
kubectl1.7 以降を使用する必要があります。
FrontendConfig または BackendConfig で指定された構成の削除
Ingress 機能を取り消すには、FrontendConfig または BackendConfig CRD で機能構成を明示的に無効にする必要があります。Ingress コントローラは、これらの CRD で指定された構成のみを調整します。
以前に有効にした構成を消去または無効にするには、フィールド タイプに応じてフィールドの値を空の文字列（""）または false のブール値に設定します。
次の BackendConfig マニフェストは、Google Cloud Armor セキュリティ ポリシーと Cloud CDN を無効にします。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backendconfig
spec:
cdn:
enabled: false
securityPolicy:
name: ""
FrontendConfig または BackendConfig の削除
FrontendConfig
FrontendConfig を削除するには、次の手順に従います。
Ingress マニフェストの
networking.gke.io/v1beta1.FrontendConfigアノテーションから FrontendConfig の名前を削除します。変更した Ingress マニフェストをクラスタに適用します。たとえば、
kubectl applyを使用します。FrontendConfig を削除します。たとえば、
kubectl delete frontendconfig config my-frontendconfigを使用します。
BackendConfig
BackedConfig を削除するには、次の手順に従います。
Service マニフェストの
cloud.google.com/backend-configアノテーションから BackendConfig の名前を削除します。変更された Service マニフェストをクラスタに適用します。たとえば、
kubectl applyを使用します。BackendConfig を削除します。たとえば、
kubectl delete backendconfig my-backendconfigを使用します。
トラブルシューティング
BackendConfig が見つかりません
このエラーは、Service のアノテーションで Service ポートの BackendConfig が指定されているにもかかわらず BackendConfig リソースが見つからなかった場合に発生します。これが発生するのは、BackendConfig リソースが作成されていなかった場合、誤った名前空間に作成された場合、または Service アノテーションの参照にスペルミスがあった場合です。
Kubernetes イベントを評価するには、次のコマンドを実行します。
kubectl get event
次のタイプの出力は、BackendConfig が見つからなかったことを示します。
KIND ... SOURCE
Ingress ... loadbalancer-controller
MESSAGE
Error during sync: error getting BackendConfig for port 80 on service "default/my-service":
no BackendConfig for service port exists
Ingress セキュリティ ポリシーが見つかりません
Ingress オブジェクトが作成された後で、セキュリティ ポリシーがロードバランサ サービスと適切に関連付けられていない場合は、Kubernetes イベントを検査して構成ミスがないか調べてください。BackendConfig が存在しないポリシーを指定している場合は、警告イベントが定期的に発生します。この問題を修正するには、BackendConfig で正しいセキュリティ ポリシーを、名前で指定してください。
Kubernetes イベントを評価するには、次のコマンドを実行します。
kubectl get event
次のタイプの出力は、セキュリティ ポリシーが見つからなかったことを示します。
KIND ... SOURCE
Ingress ... loadbalancer-controller
MESSAGE
Error during sync: The given security policy "my-policy" does not exist.
内部 Ingress リソースの作成時に NEG が見つからない
GKE で内部 Ingress を作成すると、次のエラーが発生することがあります。
Error syncing to GCP: error running backend syncing routine: googleapi: Error 404: The resource 'projects/PROJECT_ID/zones/ZONE/networkEndpointGroups/NEG' was not found, notFound
このエラーは、内部 HTTP(S) ロード バランシングの Ingress がバックエンドとしてネットワーク エンドポイント グループ（NEG）を必要とするためです。
共有 VPC 環境またはネットワーク ポリシーが有効なクラスタでは、アノテーション cloud.google.com/neg: '{"ingress": true}' を Service マニフェストに追加する必要があります。
504 Gateway Timeout: アップストリーム リクエストのタイムアウト
GKE の内部 Ingress から Service にアクセスすると、次のエラーが発生することがあります。
HTTP/1.1 504 Gateway Timeout
content-length: 24
content-type: text/plain
upsteam request timeout
このエラーは、内部 HTTP(S) ロードバランサに送信されたトラフィックが、プロキシ限定サブネットの範囲内の Envoy プロキシによってプロキシされるために発生します。
Service の targetPort で、ファイアウォール ルールを作成して、プロキシ専用サブネット範囲からのトラフィックを許可する必要があります。
エラー 400: フィールド「resource.target」の値が無効
GKE の内部 Ingress から Service にアクセスすると、次のエラーが発生することがあります。
Error syncing to GCP:LB_NAME does not exist: googleapi: Error 400: Invalid value for field 'resource.target': 'https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/regions/REGION_NAME/targetHttpProxies/LB_NAME. A reserved and active subnetwork is required in the same region and VPC as the forwarding rule.
このエラーは、内部 HTTP(S) ロード バランシングの Ingress がプロキシ専用サブネットを必要とするためです。
同期中のエラー: ロードバランサ同期ルーチンの実行中のエラー: ロードバランサが存在しません
GKE コントロール プレーンをアップグレードする、または Ingress オブジェクトを変更すると、次のいずれかのエラーが発生する可能性があります。
"Error during sync: error running load balancer syncing routine: loadbalancer
INGRESS_NAME does not exist: invalid ingress frontend configuration, please
check your usage of the 'kubernetes.io/ingress.allow-http' annotation."
Error during sync: error running load balancer syncing routine: loadbalancer LOAD_BALANCER_NAME does not exist:
googleapi: Error 400: Invalid value for field 'resource.IPAddress':'INGRESS_VIP'. Specified IP address is in-use and would result in a conflict., invalid
これらの問題を解決するには、次の手順を試してください。
- Ingress マニフェストの
tlsセクションにhostsフィールドを追加してから、Ingress を削除します。未使用の Ingress リソースが GKE によって削除されるまで 5 分待ってから、Ingress を再作成します。詳細については、Ingress オブジェクトの hosts フィールドをご覧ください。 - Ingress に加えた変更を元に戻します。次に、アノテーションまたは Kubernetes Secret を使用して証明書を追加します。
既知の問題
V1 Ingress 命名規則では HTTPS リダイレクトを有効にできません
GKE バージョン 1.16.8-gke.12 以前で作成された GKE Ingress リソースで HTTPS リダイレクトを有効にすることはできません。HTTPS リダイレクトを有効にする前に、Ingress を再作成する必要があります。再作成しないと、エラーイベントが作成され、Ingress は同期されません。
エラーイベント メッセージは次のようになります。
Error syncing to GCP: error running load balancer syncing routine: loadbalancer lb-name does not exist: ensureRedirectUrlMap() = error: cannot enable HTTPS Redirects with the V1 Ingress naming scheme. Please recreate your ingress to use the newest naming scheme.
Google Cloud Armor セキュリティ ポリシー フィールドが BackendConfig から削除されました
v1beta1 API を使用して BackendConfig リソースを更新すると、Service からアクティブな Google Cloud Armor セキュリティ ポリシーが削除されるという既知の問題があります。この問題は、次の GKE バージョンに影響します。
- 1.18.19-gke.1400～1.18.20-gke.5099
- 1.19.10-gke.700～1.19.14-gke.299
- 1.20.6-gke.700～1.20.9-gke.899
BackendConfig を使用して Ingress リソースに Google Cloud Armor を構成していない場合、クラスタへの影響はありません。
BackendConfig を使用して Google Cloud Armor を構成する GKE クラスタの場合、v1 API のみを使用して BackendConfig リソースを更新することを強くおすすめします。v1beta1 BackendConfig リソースを使用してクラスタに BackendConfig を適用すると、参照先の Service から Google Cloud Armor セキュリティ ポリシーが削除されます。
この問題を軽減するには、BackendConfig の更新を v1 BackendConfig API のみで行います。v1 BackendConfig は v1beta1 と同じフィールドをすべてサポートしています。互換性を破る変更がないため、API フィールドを透過的に更新できます。アクティブな BackendConfig マニフェストの apiVersion フィールドを cloud.google.com/v1 に置き換え、cloud.google.com/v1beta1 は使用しません。次のサンプル マニフェストは、v1 API を使用する BackendConfig リソースを記述しています。
apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
name: my-backend-config
spec:
securityPolicy:
name: "ca-how-to-security-policy"
BackendConfig リソースを定期的に更新する CI / CD システムまたはツールがある場合は、これらのシステムで cloud.google.com/v1 API グループを使用していることを確認してください。
BackendConfig が v1beta1 API ですでに更新されている場合、Google Cloud Armor セキュリティ ポリシーが削除されている可能性があります。この状態になっているかどうかを確認するには、次のコマンドを実行します。
kubectl get backendconfigs -A -o json | jq -r '.items[] | select(.spec.securityPolicy == {}) | .metadata | "\(.namespace)/\(.name)"'
レスポンスが出力を返す場合、クラスタはこの問題の影響を受けています。このコマンドは、問題の影響を受ける BackendConfig リソース（<namespace>/<name>）のリストを返します。出力が空の場合、問題が発生してから v1beta1 API で BackendConfig が更新されていません。BackendConfig の今後の更新では、v1 のみを使用する必要があります。
Google Cloud Armor セキュリティ ポリシーが削除された場合は、次の Logging クエリを使用して削除のタイミングを確認できます。
resource.type="gce_backend_service"
protoPayload.methodName="v1.compute.backendServices.setSecurityPolicy"
protoPayload.authenticationInfo.principalEmail:"container-engine-robot.iam.gserviceaccount.com"
protoPayload.response.status = "RUNNING"
NOT protoPayload.authorizationInfo.permission:"compute.securityPolicies.use"
影響を受けるクラスタがある場合は、v1 API を使用する BackendConfig リソースに更新を push することで修正できます。
この問題にパッチを適用して v1beta1 BackendConfig リソースを安全に使用できるようにする、次のいずれかの更新バージョンに GKE コントロール プレーンをアップグレードします。
- 1.18.20-gke.5100 以降
- 1.19.14-gke.300 以降
- 1.20.9-gke.900 以降
次のステップ
- 単一クラスタ負荷分散の GKE Ingress。
- GKE アプリの HTTP(S) ルーティングをデプロイするための Ingress のチュートリアル。
- カスタム HTTP ヘルスチェックを使用して GKE Ingress を実装する。
- IAP 対応の Ingress を実装する。
- Google Cloud Armor を有効化した Ingress を実装する。