マルチクラスタ 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 に基づいて作成、読み取り、更新、削除されます。

  • ファイアウォール ルール: MCS は、フリート内のクラスタ間での Pod の相互通信を可能にするファイアウォール ルールを構成します。ファイアウォール ルールの作成、読み取り、更新、削除は、フリートに追加するクラスタに応じて行われます。これらのルールは、GKE クラスタ内の Pod 間の通信を有効にするために GKE が作成するルールと類似しています。

  • Traffic Director: MCS は、エンドポイントに対してヘルスチェックを実行し、フリート内のクラスタ間でエンドポイントを分散する Traffic Director リソースを構成します。これらのリソースは、複数のクラスタにエクスポートする Service に応じて作成、読み取り、更新、削除されます。

要件

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

  • MCS では、Google Cloud 上の VPC ネイティブ GKE クラスタからの Service のエクスポートのみがサポートされています。詳細については、VPC ネイティブ クラスタの作成をご覧ください。VPC ネイティブ以外のクラスタは使用できません。

  • クラスタ間の接続が可能かどうかは、それらのクラスタが同じ VPC ネットワーク内またはピアリングされた VPC ネットワーク内で稼働しているかどうかに依存します。

始める前に

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

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

    Google Kubernetes Engine API の有効化

  3. 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 に置き換えます。

シナリオ

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 を有効にするには、次の手順を行います。

  1. MCS API を有効にします。

    gcloud services enable multiclusterservicediscovery.googleapis.com \
        --project PROJECT_ID
    

    PROJECT_ID は、クラスタをフリートに登録する予定のプロジェクトのプロジェクト ID に置き換えます。

  2. MCS 機能を有効にします。

    gcloud container hub multi-cluster-services enable \
        --project PROJECT_ID
    

    PROJECT_ID は、クラスタをフリートに登録する予定のプロジェクトのプロジェクト ID に置き換えます。

    このコマンドが機能しない場合は、次のコマンドを実行して、最新バージョンの Cloud SDK を使用していることを確認してください。

    gcloud components update
    
  3. 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)。
  4. 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 に置き換えます。

  5. フリート内の各クラスタに、Service を共有する Namespace があることを確認します。default および kube-system Namespace にある Service をクラスタにエクスポートすることはできません。

    必要に応じて、次のコマンドを使用して Namespace を作成します。

    kubectl create ns NAMESPACE
    

    NAMESPACE は Namespace の名前に置き換えます。

  6. 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 のデフォルトのサービス アカウントまたは独自のノード サービス アカウントを使用できます。

MCS の使用

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

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

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

  1. 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 の名前。
  2. 次のコマンドを実行して 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_NAMENAMESPACE: 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_NAMENAMESPACE: ServiceExport オブジェクトで定義した値。
  • MEMBERSHIP_NAME: Pod が存在するクラスタのフリートのメンバーシップ名。
  • HOSTNAME: Pod のホスト名。

MCS の無効化

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

  1. フリート内の各クラスタから、作成した各 ServiceExport オブジェクトを削除します。

    kubectl delete serviceexport SERVICE_EXPORT_NAME \
        -n NAMESPACE
    

    次のように置き換えます。

    • SERVICE_EXPORT_NAME: ServiceExport オブジェクトの名前。
    • NAMESPACE: ServiceExport オブジェクトの Namespace。
  2. 他の目的で登録する必要がない場合は、フリートからクラスタの登録を解除します。

  3. multiclusterservicediscovery 機能を無効にします。

    gcloud container hub multi-cluster-services disable \
        --project PROJECT_ID
    

    PROJECT_ID は、クラスタを登録したプロジェクトのプロジェクト ID に置き換えます。

  4. 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

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

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: {}

トラブルシューティングに最も役立つフィールドは codedescription です。

featureState 内のコード

コードは、MCS に関するメンバーの全般的な状態を示します。これらのフィールドは state.code フィールドで確認できます。次の 3 つのコードがあります。

  • OK: メンバーシップは MCS に正常に追加され、使用できる状態です。

  • WARNING: MCS は、メンバーシップ設定の調整中です。説明フィールドで、このコードの原因に関する詳細情報を確認できます。

  • FAILED: このメンバーシップは MCS に追加されませんでした。OK コードを使用したフリート内の他のメンバーは、この FAILED メンバーシップの影響を受けません。説明フィールドで、このコードの原因に関する詳細情報を確認できます。

featureState 内の説明

この説明は MCS のメンバーシップの状態に関する詳細情報を提供します。これらの説明は state.description フィールドで確認できます。次の説明が表示されます。

  • Firewall successfully created: このメッセージは、メンバーシップのファイアウォール ルールが正常に作成または更新されたことを示します。メンバーシップのコードは OK です。

  • Firewall creation pending: このメッセージは、メンバーシップのファイアウォール ルールの作成または更新が保留中であることを示します。メンバーシップのコードは WARNING です。このメンバーシップでは、ファイアウォール ルールが保留中の間、新しいマルチクラスタ Service と追加されたメンバーシップへの更新および接続に関する問題が発生する可能性があります。

  • Project that member lives in is missing required permissions and/or has not enabled all required APIs - additional setup steps are required: このメッセージは、内部 StatusForbidden(403)エラーが発生したことを示します。メンバーシップのコードは FAILED です。このエラーは、次のような状況で発生します。

    • メンバーのプロジェクトで必要な API が有効にされていない。

      メンバーのクラスタがフリートとは別のプロジェクトに存在する場合は、プロジェクト間の設定を参照して、必要なすべての手順が完了していることを確認してください。すべての手順が完了したら、次のコマンドを使用して、登録プロジェクトで次の API が有効であることを確認します。

      gcloud services enable multiclusterservicediscovery.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 に置き換えます。

    • mcsd または gkehub のサービス アカウントには、メンバーのプロジェクトで追加の権限が必要です。

      mcsd および gkehub サービス アカウントは登録プロジェクト内に自動的に作成され、必要なすべての権限が付与されているはずです。サービス アカウントが存在することを確認するには、次のコマンドを実行します。

      gcloud projects get-iam-policy PROJECT_ID | grep gcp-sa-mcsd
      gcloud projects get-iam-policy PROJECT_ID | grep gcp-sa-gkehub
      

      PROJECT_ID は、クラスタを登録したプロジェクトのプロジェクト ID に置き換えます。

    これらのコマンドにより、mcsd および gkehub サービス アカウントの完全な名前が表示されます。

  • Multiple VPCs detected in the hub - VPC must be peered with other VPCs for successful connectivity: このメッセージは、複数の異なる VPC でホストされているクラスタが同じフリートに登録されたことを示します。メンバーシップ ステータスは OK です。クラスタの VPC ネットワークは、その NetworkConfig のネットワークにより定義されます。マルチクラスタ Service にはフラット ネットワークが必要であり、マルチクラスタ Service が正常に相互接続するためには、これらの VPC がアクティブにピアリングされる必要があります。詳細については、VPC ネットワーク ピアリングの設定例をご覧ください。

  • Member does not exist in the same project as hub - additional setup steps are required, errors may occur if not completed.: このメッセージは、プロジェクト間クラスタに追加の設定手順が必要であることを示します。メンバーシップ ステータスは OK です。プロジェクト間のメンバーシップが、フリートと同じプロジェクトに存在していない、メンバーのクラスタとして定義されています。詳しくは、プロジェクト間の設定をご覧ください。

  • Non-GKE clusters are currently not supported: このメッセージは、MCS では GKE クラスタのみがサポートされることをお知らせするものです。GKE 以外のクラスタを MCS に追加することはできません。メンバーシップ ステータスは FAILED です。

次のステップ