マルチクラスタ Service の構成

このページでは、マルチクラスタ Service（MCS）を有効にして使用する方法を説明します。MCS の仕組みとその利点の詳細については、マルチクラスタ Service をご覧ください。

Google Kubernetes Engine（GKE）MCS 機能は、クラスタ境界を超えて Kubernetes Service の範囲を拡張し、複数の GKE クラスタ間で Service を検出して呼び出せるようにします。既存の Service のサブセットまたは新しい Service をエクスポートできます。

MCS によって管理される Google Cloud リソース

MCS は、Google Cloud の次のコンポーネントを管理します。

Cloud DNS: MCS は、フリートクラスタ内のエクスポートされた Service ごとに Cloud DNS ゾーンとレコードを構成します。これにより、他のクラスタで実行されている Service に接続できます。これらのゾーンとレコードは、複数のクラスタにエクスポートする Service に基づいて作成、読み取り、更新、削除されます。

注: Cloud DNS を使用すると、追加料金が発生します。Cloud DNS の料金に従って課金されます。
ファイアウォールルール: MCS は、フリート内のクラスタ間での Pod の相互通信を可能にするファイアウォールルールを構成します。ファイアウォールルールの作成、読み取り、更新、削除は、フリートに追加するクラスタに応じて行われます。これらのルールは、GKE クラスタ内の Pod 間の通信を有効にするために GKE が作成するルールと類似しています。
Traffic Director: MCS は、エンドポイントに対してヘルスチェックを実行し、フリート内のクラスタ間でエンドポイントを分散する Traffic Director リソースを構成します。これらのリソースは、複数のクラスタにエクスポートする Service に応じて作成、読み取り、更新、削除されます。

要件

MCS の要件は次のとおりです。

MCS では、Google Cloud 上の VPC ネイティブ GKE クラスタからの Service のエクスポートのみがサポートされています。詳細については、VPC ネイティブクラスタの作成をご覧ください。VPC ネイティブ以外のクラスタは使用できません。
クラスタ間の接続が可能かどうかは、それらのクラスタが同じ VPC ネットワーク内またはピアリングされた VPC ネットワーク内で稼働しているかどうかに依存します。

始める前に

手順を始める前に、次の作業を完了してください。

Cloud SDK をインストールします。
Google Kubernetes Engine API を有効にします。

Google Kubernetes Engine API の有効化
GKE フリート（ハブ）、Cloud DNS、Traffic Director、Resource Manager API を有効にします。
```
gcloud services enable gkehub.googleapis.com --project PROJECT_ID
gcloud services enable dns.googleapis.com --project PROJECT_ID
gcloud services enable trafficdirector.googleapis.com --project PROJECT_ID
gcloud services enable cloudresourcemanager.googleapis.com --project PROJECT_ID
```
PROJECT_ID は、クラスタをフリートに登録する予定のプロジェクトのプロジェクト ID に置き換えます。
注: プロジェクトオーナー以外のユーザーが API を有効にするには、対象ユーザーに serviceusage.services.enable の権限が付与されている必要があります。

シナリオ

MCS は次のシナリオをサポートしています。

シナリオ	ネットワークの設定	ハブプロジェクトと登録済みクラスタの例
同じプロジェクトと VPC ネットワーク内の 2 つのクラスタ。	1 つの VPC ネットワーク（共有 VPC またはスタンドアロン）。	ハブプロジェクトと同じプロジェクトにある 2 つのクラスタ。
共有 VPC 設定、2 つのプロジェクト、2 つのクラスタが含まれます。	ホストプロジェクトにある共有 VPC ネットワーク。	ネットワークホストプロジェクトにあるハブプロジェクトと、サービスプロジェクトにある登録済みクラスタ。
共有 VPC 設定、3 つのプロジェクト、2 つのクラスタが含まれます。	ホストプロジェクトにある共有 VPC ネットワーク。	1 つのサービスプロジェクトにあるハブプロジェクトと、別のサービスプロジェクトにある登録済みクラスタ。
2 つのスタンドアロン VPC ネットワーク、2 つのプロジェクト、2 つのクラスタが含まれます。	各クラスタでそれぞれ異なる VPC ネットワークを使用します。この VPC ネットワークは、VPC ネットワークピアリングを使用して接続する必要があります。	1 つのプロジェクトにあるハブプロジェクトと、別のプロジェクトにある登録済みクラスタ。

MCS の有効化

同じプロジェクトと VPC ネットワーク内の 2 つのクラスタで MCS を有効にするか、共有 VPC 設定でハブプロジェクトで MCS を有効にするには、次の手順を行います。

MCS API を有効にします。
```
gcloud services enable multiclusterservicediscovery.googleapis.com \
    --project PROJECT_ID
```
PROJECT_ID は、クラスタをフリートに登録する予定のプロジェクトのプロジェクト ID に置き換えます。
MCS 機能を有効にします。
```
gcloud container hub multi-cluster-services enable \
    --project PROJECT_ID
```
PROJECT_ID は、クラスタをフリートに登録する予定のプロジェクトのプロジェクト ID に置き換えます。

このコマンドが機能しない場合は、次のコマンドを実行して、最新バージョンの Cloud SDK を使用していることを確認してください。
```
gcloud components update
```
GKE クラスタをフリートに登録します。クラスタの登録は Workload Identity を有効にした状態で行うことを強くおすすめします。Workload Identity を使用しない場合は、サービスアカウントの認証で追加の手順を行う必要があります。

クラスタを登録するには、次のコマンドを実行します。
```
gcloud container hub memberships register MEMBERSHIP_NAME \
   --gke-cluster GKE_CLUSTER \
   --enable-workload-identity \
   --project PROJECT_ID
```
以下を置き換えます。
- MEMBERSHIP_NAME: ハブに登録されているクラスタを一意に表すために使用するメンバーシップ名。
- GKE_CLUSTER: 現在のプロジェクトの GKE クラスタの location/name。ロケーションは、ゾーンまたはリージョンのいずれかです（例: us-central1-a/my-gke-cluster）。
MCS インポータを使用するために必要な Identity and Access Management（IAM）権限を付与します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
    --role "roles/compute.networkViewer"
```
PROJECT_ID は、クラスタをフリートに登録したプロジェクトのプロジェクト ID に置き換えます。
フリート内の各クラスタに、Service を共有する Namespace があることを確認します。default および kube-system Namespace にある Service をクラスタにエクスポートすることはできません。

必要に応じて、次のコマンドを使用して Namespace を作成します。
```
kubectl create ns NAMESPACE
```
NAMESPACE は Namespace の名前に置き換えます。

注: エクスポート対象の Namespace が存在しないクラスタには、Service はインポートされません。したがって、Service を使用するクラスタ内に Service の Namespace を作成します。Namespace がない場合は、いつでも Namespace を追加できますが、以前にエクスポートした Service が新しく作成した Namespace にインポートされるまでに、最大で 5 分間を要する場合があります。

MCS が有効になっていることを確認するには、次のコマンドを実行します。

gcloud container hub multi-cluster-services describe

出力は次のようになります。

createTime: '2021-08-10T13:05:23.512044937Z'
membershipStates:
  projects/PROJECT_ID/locations/global/memberships/MCS_NAME:
    state:
      code: OK
      description: Firewall successfully updated
      updateTime: '2021-08-10T13:14:45.173444870Z'
name: projects/PROJECT_NAME/locations/global/features/multiclusterservicediscovery
resourceState:
  state: ACTIVE
spec: {}

state の値が ACTIVE でない場合は、トラブルシューティングセクションをご覧ください。

サービスアカウントの認証

サービスアカウントを使用して GKE クラスタをフリートに登録した場合は、サービスアカウントを認証するための追加手順を行う必要があります。MCS は、gke-mcs-importer というコンポーネントをデプロイします。このコンポーネントは Traffic Director からエンドポイントの更新を受信するため、MCS の有効化の一環として、サービスアカウントに Traffic Director から情報を読み取るための権限を付与する必要があります。

サービスアカウントを使用する場合、Compute Engine のデフォルトのサービスアカウントまたは独自のノードサービスアカウントを使用できます。

Compute Engine のデフォルトのサービスアカウントを使用する場合は、次のスコープを有効にします。
- https://www.googleapis.com/auth/compute.readonly
- https://www.googleapis.com/auth/cloud-platform
スコープの有効にする方法について詳しくは、インスタンスのサービスアカウントとアクセススコープを変更するをご覧ください。
独自のノードサービスアカウントを使用する場合は、roles/compute.networkViewer ロールをサービスアカウントに割り当てます。

MCS の使用

以下のセクションでは、MCS の使用方法を説明します。MCS は Kubernetes マルチクラスタサービス API を使用します。

エクスポートする Service の登録

エクスポートする Service をフリート内の他のクラスタに登録するには、次の手順を行います。

export.yaml という名前の ServiceExport オブジェクトを作成します。
```
# export.yaml
kind: ServiceExport
apiVersion: net.gke.io/v1
metadata:
 namespace: NAMESPACE
 name: SERVICE_EXPORT_NAME
```
以下を置き換えます。
- NAMESPACE: ServiceExport オブジェクトの Namespace。この Namespace は、エクスポートする Service の Namespace と一致する必要があります。default および kube-system Namespace にある Service は、クラスタにエクスポートされません。
- SERVICE_EXPORT_NAME: クラスタで、フリート内の他のクラスタにエクスポートする Service の名前。
次のコマンドを実行して ServiceExport リソースを作成します。
```
kubectl apply -f export.yaml
```

Service の最初のエクスポートでは、フリートに登録されているクラスタと同期するまでに約 5 分を要します。Service がエクスポートされると、それに続いてエンドポイントの同期が直ちに行われます。

複数のクラスタから同じ Service をエクスポートできます。同じ Namespace と同じ名前が設定された Service は同じものとして扱われます。この場合、同じ Service について、最大 5 つのクラスタのエンドポイントがクラスタ間で完全に同期されます。同じ Service をエクスポートするクラスタが 5 つを超えて存在する場合、エンドポイントのサブセットのみがインポートされます。使用するすべてのクラスタで均等に Service エンドポイントが分散されます。

クラスタ間の Service を使用する

MCS は ClusterSetIP とヘッドレス Service をサポートしています。DNS「A」レコードのみを使用できます。

ServiceExport オブジェクトを作成すると、次のドメイン名は、フリートクラスタ内の任意の Pod からエクスポートされた Service に解決されます。

 SERVICE_EXPORT_NAME.NAMESPACE.svc.clusterset.local

出力には次の値が含まれます。

SERVICE_EXPORT_NAME、NAMESPACE: ServiceExport オブジェクトで定義した値。

ClusterSetIP Service では、ドメインが ClusterSetIP に解決されます。この値は、ServiceExport オブジェクトが作成された Namespace 内のクラスタに含まれる ServiceImport オブジェクトで確認できます。ServiceImport オブジェクトは自動的に作成されます。

次に例を示します。

kind: ServiceImport
apiVersion: net.gke.io/v1
metadata:
 namespace: EXPORTED-SERVICE-NAMESPACE
 name: external-svc-SERVICE-EXPORT-TARGET
status:
 ports:
 - name: https
   port: 443
   protocol: TCP
   targetPort: 443
 ips: CLUSTER_SET_IP

ヘッドレス Service の場合、ドメインはエクスポート側クラスタ内のエンドポイントの IP アドレスリストに解決されます。ホスト名を持つ各バックエンド Pod は、次の形式のドメイン名を使用して個別にアドレス指定することもできます。

 HOSTNAME.MEMBERSHIP_NAME.SERVICE_EXPORT_NAME.NAMESPACE.svc.clusterset.local

出力には次の値が含まれます。

SERVICE_EXPORT_NAME、NAMESPACE: ServiceExport オブジェクトで定義した値。
MEMBERSHIP_NAME: Pod が存在するクラスタのフリートのメンバーシップ名。
HOSTNAME: Pod のホスト名。

MCS の無効化

MCS を無効にするには、次の手順を行います。

フリート内の各クラスタから、作成した各 ServiceExport オブジェクトを削除します。
```
kubectl delete serviceexport SERVICE_EXPORT_NAME \
    -n NAMESPACE
```
次のように置き換えます。
- SERVICE_EXPORT_NAME: ServiceExport オブジェクトの名前。
- NAMESPACE: ServiceExport オブジェクトの Namespace。
他の目的で登録する必要がない場合は、フリートからクラスタの登録を解除します。
multiclusterservicediscovery 機能を無効にします。
```
gcloud container hub multi-cluster-services disable \
    --project PROJECT_ID
```
PROJECT_ID は、クラスタを登録したプロジェクトのプロジェクト ID に置き換えます。
MCS の API を無効にします。
```
gcloud services disable multiclusterservicediscovery.googleapis.com \
    --project PROJECT_ID
```
PROJECT_ID は、クラスタを登録したプロジェクトのプロジェクト ID に置き換えます。

制限事項

以下の上限は適用されません。クラスタやプロジェクトの負荷およびエンドポイントのチャーンレートによっては、これらの上限を超える場合もあります。ただし、これらの上限を超えると、パフォーマンスの問題が発生する可能性があります。

クラスタのエクスポート: 名前空間名で識別される単一の Service を最大 5 つのクラスタから同時に安全にエクスポートできます。この上限を超えると、使用するクラスタにエンドポイントのサブセットのみがインポートされる可能性があります。クラスタの異なるサブセットから、それぞれ異なる Service をエクスポートできます。
単一の Service の背後の Pod 数: 単一の Service の背後の Pod 数を 250 未満に抑えていれば安全です。これは、単一のクラスタ Service の上限と同じです。比較的静的なワークロードと少数のマルチクラスタ Service では、この数を大幅に上回って Service ごとのエンドポイント数が何千にもなる可能性があります。単一クラスタ Service と同様に、すべてのエンドポイントは各ノードの kube-proxy で監視されます。特に複数のクラスタから同時にエクスポートする場合、この上限を超えると、より大きいノードが必要になる場合があります。
同時にエクスポートするマルチクラスタ Service の数: Service を同時にエクスポートする場合、一意の Service ポートが 50 個を超えないようにすることをおすすめします。一意の Service ポートは Service の名前空間名と宣言されたポートによって識別されます。たとえば、ポート 80 と 443 を公開する Service をエクスポートすると、50 個の一意の Service ポート上限のうちの 2 つとカウントされます。複数のクラスタからエクスポートされた同じ名前空間名の Service は、単一の一意の Service としてカウントされます。前述の 2 ポートのサービスは、5 つのクラスタから同時にエクスポートされた場合のみ、2 つのポートとしてカウントされます。各マルチクラスタ Service はバックエンドサービスの割り当てに計上され、各エクスポート側クラスタまたはゾーンがネットワークエンドポイントグループ（NEG）を作成します。

トラブルシューティング

以降のセクションでは、MCS のトラブルシューティングのヒントを紹介します。

featureState の表示

機能の状態を表示すると、MCS が正常に構成されているかどうかを確認するのに役立ちます。MCS 機能の状態を表示するには、次のコマンドを使用します。

gcloud container hub multi-cluster-services describe