マルチクラスタ 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 は、Environ クラスタ内のエクスポートされた Service ごとに Cloud DNS ゾーンとレコードを構成します。これにより、他のクラスタで実行されている Service に接続できます。これらのゾーンとレコードは、複数のクラスタにエクスポートする Service に基づいて作成、読み取り、更新、削除されます。

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

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

要件

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

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

始める前に

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

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

    Google Kubernetes Engine API を有効にする

  3. GKE Environ(ハブ)、MCS、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 は、Environ にクラスタを登録するプロジェクトのプロジェクト ID に置き換えます。

  4. 使用可能な VPC ネイティブ クラスタが存在することを確認します。必要に応じて、VPC ネイティブな GKE クラスタを作成します

MCS の有効化

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

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

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

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

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

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

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

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

    gcloud components update
    
  3. GKE クラスタを Environ に登録します。クラスタの登録は Workload Identity を有効にした状態で行うことを強くおすすめします。Workload Identity を使用しない場合は、サービス アカウントの認証セクションで追加の手順を行う必要があります。

    クラスタを登録するには、次のコマンドを実行します。

    gcloud container hub memberships register MEMBERSHIP_NAME \
       --gke-cluster GKE_CLUSTER \
       --enable-workload-identity
    

    以下を置き換えます。

    • 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 は、クラスタを Environ に登録したプロジェクトのプロジェクト ID に置き換えます。

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

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

    kubectl create ns NAMESPACE
    

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

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

    gcloud alpha container hub multi-cluster-services describe
    

    次の例に示すように、featureState の出力に lifecycleState: ENABLED と示されていることを確認します。

    featureState:
     detailsByMembership:
       projects/PROJECT_ID/locations/global/memberships/CLUSTER1:
         code: OK
         description: Firewall successfully created.
         updateTime: '2020-09-24T05:16:27.675313587Z'
       projects/PROJECT_ID/locations/global/memberships/CLUSTER2:
         code: OK
         description: Firewall successfully created.
         updateTime: '2020-09-24T05:15:26.665213577Z'
    lifecycleState: ENABLED 
    

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

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

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

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

プロジェクト間の設定

Environ に登録されていないプロジェクトに属するクラスタで MCS を使用する場合は、追加手順を行う必要があります。

前提事項

プロジェクト間での使用を構成する前に、次の手順を行います。

プロジェクトの構成

プロジェクトを構成するには、次の手順を行います。

  1. クラスタを作成したプロジェクト(クラスタ プロジェクト)で GKE クラスタを別のプロジェクトに登録するで説明している手順を行い、GKE Environ サービス アカウントを作成します。

  2. クラスタ プロジェクトで、Cloud DNS、Traffic Director、Resource Manager API を有効にします。

    gcloud services enable dns.googleapis.com \
        --project CLUSTER_PROJECT_ID
    
    gcloud services enable trafficdirector.googleapis.com \
        --project CLUSTER_PROJECT_ID
    
    gcloud services enable cloudresourcemanager.googleapis.com \
        --project CLUSTER_PROJECT_ID
    

    CLUSTER_PROJECT_ID は、クラスタが属するプロジェクトのプロジェクト ID に置き換えます。

  3. クラスタ プロジェクト内で MCS エージェントの IAM ロールを作成します。

    gcloud projects add-iam-policy-binding "CLUSTER_PROJECT_ID" \
        --member "serviceAccount:service-REGISTRATION_PROJECT_NUMBER@gcp-sa-mcsd.iam.gserviceaccount.com" \
        --role roles/multiclusterservicediscovery.serviceAgent
    

    以下を置き換えます。

    • CLUSTER_PROJECT_ID: クラスタが属するプロジェクトのプロジェクト ID
    • REGISTRATION_PROJECT_NUMBER: Environ に登録したプロジェクトのプロジェクト番号

プロジェクトの登録

プロジェクトを登録するには、次の手順を行います。

  1. クラスタ プロジェクト内のクラスタを登録プロジェクトに登録します。

    gcloud container hub memberships register MEMBERSHIP_NAME \
       --gke-uri GKE_URI \
       --enable-workload-identity \
       --project REGISTRATION_PROJECT_ID
    

    以下を置き換えます。

    • MEMBERSHIP_NAME: Environ に登録されたクラスタを一意に表すために使用するメンバーシップ名。
    • GKE_URI: クラスタの URI。登録プロジェクトとは別にクラスタ プロジェクトを指定するには、--gke-uri フラグを使用する必要があります。
    • REGISTRATION_PROJECT_ID: Environ に登録したプロジェクトのプロジェクト ID。
  2. MCS インポータを使用するために必要な Identity and Access Management(IAM)権限を付与します。

    gcloud projects add-iam-policy-binding CLUSTER_PROJECT_ID \
        --member "serviceAccount:CLUSTER_PROJECT_ID.svc.id.goog[gke-mcs/gke-mcs-importer]" \
        --role "roles/compute.networkViewer"
    

    CLUSTER_PROJECT_ID は、クラスタが属するプロジェクトのプロジェクト ID に置き換えます。

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

MCS の使用

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

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

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

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

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

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

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

ServiceExport オブジェクトを作成すると、次のドメイン名は、Environ クラスタ内の任意の 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 アドレスリストに解決されます。

MCS の無効化

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

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

    kubectl delete serviceexport SERVICE_EXPORT_NAME \
        -n NAMESPACE
    

    以下を置き換えます。

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

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

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

制限事項

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

  • エクスポート側クラスタの数: 最大 5 つのクラスタから同時に、Namespace 名で識別される特定の Service を安全にエクスポートできます。この上限を超えると、使用するクラスタにエンドポイントのサブセットのみがインポートされる可能性があります。クラスタの異なるサブセットから、それぞれ異なる Service をエクスポートできます。

  • 単一の Service の背後の Pod 数: 単一の Service の背後の Pod 数を 250 未満に抑えていれば安全です。これは、単一のクラスタ Service の上限と同じです。比較的静的なワークロードと少数のマルチクラスタ Service では、この数を大幅に上回って Service ごとのエンドポイント数が何千にもなる可能性があります。単一クラスタ Service と同様に、すべてのエンドポイントは各ノードの kube-proxy で監視されます。特に複数のクラスタから同時にエクスポートする場合、この上限を超えると、より大きいノードが必要になる場合があります。

  • 同時にエクスポートするマルチクラスタ Service の数: 同時にエクスポートする Service は 15 個までにすることをおすすめします。各マルチクラスタ Service は バックエンド サービスの割り当てに計上され、各エクスポート側クラスタまたはゾーンがネットワーク エンドポイント グループ(NEG)を作成します。

トラブルシューティング

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

featureState の表示

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

gcloud alpha container hub multi-cluster-services describe

featureState の出力例:

featureState:
detailsByMembership:
  projects/PROJECT/locations/global/memberships/CLUSTER1:
    code: OK
    description: Firewall successfully created.
    updateTime: '2020-09-24T05:16:27.675313587Z'
  projects/PROJECT/locations/global/memberships/CLUSTER2:
    code: OK
    description: Firewall successfully created.
    updateTime: '2020-09-24T05:15:26.665213577Z'
lifecycleState: ENABLED

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

featureState 内のコード

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

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

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

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

featureState 内の説明

この説明は MCS のメンバーシップの状態に関する詳細情報を提供します。これらの説明は detailsByMembership.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 が有効にされていない。

      メンバーのクラスタが Environ とは別のプロジェクトに存在する場合は、プロジェクト間の設定を参照して、必要なすべての手順が完了していることを確認してください。すべての手順が完了したら、次のコマンドを使用して、登録プロジェクトで次の 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 です。プロジェクト間のメンバーシップが、Environ と同じプロジェクトに存在していない、メンバーのクラスタとして定義されています。詳しくは、プロジェクト間の設定をご覧ください。

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

次のステップ