このページの一部またはすべての情報は、S3NS の Cloud de Confiance に適用されない場合があります。詳細については、Google Cloud との違いをご確認ください。

フリートパッケージをデプロイする

このページでは、Config Sync のフリートパッケージを使用して、フリートに登録されている複数のクラスタに Kubernetes リソースをデプロイする方法について説明します。フリートパッケージを作成してデプロイすると、新しいクラスタをフリートに追加した際に、そのクラスタにも Git リポジトリ内の Kubernetes 構成ファイルが自動的にデプロイされます。

FleetPackage は、Kubernetes の未加工のマニフェストをクラスタのフリートにデプロイするための宣言型 API です。フリートパッケージでデプロイする Kubernetes リソースは、事前にハイドレート（WET）されている必要があります。

始める前に

フリート全体にデプロイする Kubernetes リソースを含む Git リポジトリを作成するか、このリポジトリにアクセスできることを確認します。
Google Cloud CLI をインストールして初期化します。これにより、gcloud コマンドと nomos コマンドが利用できるようになります。Cloud Shell をご利用の場合、Google Cloud CLI はプリインストールされています。以前に Google Cloud CLI をインストール済みである場合は、gcloud components update を実行して最新バージョンに更新してください。

注: 以前に gcloud CLI をインストール済みである場合は、compute/region と compute/zone のプロパティが設定されていることを確認してください。デフォルトのロケーションを設定することで、One of [--zone, --region] must be supplied: Please specify location といった gcloud CLI のエラーの発生を防ぐことができます。

Config Sync（anthosconfigmanagement）API と ConfigDelivery API を有効にします。

gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

デフォルトのロケーションを設定します。
```
gcloud config set config_delivery/location us-central1
```
注: ConfigDelivery API で使用できるロケーションは us-central1 のみです。
デフォルトプロジェクトを設定します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、フリートホストプロジェクトのプロジェクト ID に置き換えます。
クラスタがフリートに登録されていることを確認します。
Cloud Build リポジトリを使用して、GitHub や GitLab などのサポートされているプロバイダへの接続を作成します。フリートパッケージを使用する場合は、同期するリポジトリごとに Cloud Build を 1 回だけ設定する必要があります。

重要: Git 接続と FleetPackage は同じリージョンに存在する必要があるため、Cloud Build 接続は us-central1 に存在する必要があります。ConfigDelivery API は us-central1 でのみ使用できます。

クラスタ要件を確認する

クラスタに Config Sync をインストールする前に、クラスタ構成の推奨事項と要件を確認してください。

環境を準備する

Config Sync フリートパッケージの環境を準備するには、クラスタを登録するユーザーに必要な IAM ロールを付与します。

Config Sync のインストール

Config Sync は、 Cloud de Confiance コンソールまたは Google Cloud CLI を使用してインストールできます。

コンソール

Config Sync をインストールするには、すべてのクラスタをフリートに登録する必要があります。 Cloud de Confiance コンソールで Config Sync をインストールする際、個々のクラスタを選択すると、それらのクラスタがフリートに自動的に登録されます。

Cloud de Confiance コンソールで、[機能] セクションの [構成] ページに移動します。

[構成] に移動

[ Config Sync のインストール] をクリックします。
[インストールオプション] で、[Install Config Sync on entire fleet (recommended)] を選択します。
[Config Sync のインストール] をクリックします。数分後、[設定] タブで、フリート内のクラスタの [ステータス] 列が [有効] になっていることを確認します。

gcloud

ConfigManagement フリート機能を有効にします。

gcloud beta container fleet config-management enable

Config Sync を有効にするには、次の内容の apply-spec.yaml という名前のファイルを作成します。
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
apply-spec.yaml ファイルを適用します。
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml
```
MEMBERSHIP_NAME は、クラスタを登録したときに選択したフリートメンバーシップ名に置き換えます。メンバーシップ名を確認するには、gcloud container fleet memberships list コマンドを実行します。

Cloud Build 用のサービスアカウントを作成する

フリートパッケージは、Cloud Build を使用して Git リポジトリから Kubernetes リソースを取得し、クラスタにデプロイします。Cloud Build には、このジョブを実行する権限を持つサービスアカウントが必要です。サービスアカウントを作成して必要な権限を付与する手順は次のとおりです。

サービスアカウントを作成します。
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
SERVICE_ACCOUNT_NAME をサービスアカウントの名前に置き換えます。名前は 6～30 文字の英数字 ID にする必要があります（例: my-service-account）。作成したサービスアカウントの名前は変更できません。

リソースバンドルパブリッシャーロールの IAM ポリシーバインディングを追加します。

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

メッセージが表示されたら、ポリシーの条件として None を選択します。

ログ書き込みロールの IAM ポリシーバインディングを追加します。

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

メッセージが表示されたら、ポリシーの条件として None を選択します。

ArtifactRegistry 書き込みロールの IAM ポリシーバインディングを追加します。

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

メッセージが表示されたら、ポリシーの条件として None を選択します。

フリートパッケージを作成する

フリートパッケージを作成するには、Cloud Build に接続した Kubernetes リソースを使用して、リポジトリを指す FleetPackage 仕様を定義します。次に、FleetPackage リソースを適用します。これにより、Git からリソースが取得され、フリート全体にデプロイされます。

次の内容で fleetpackage-spec.yaml という名前のファイルを作成します。
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED
```
次のように置き換えます。
- CONNECTION_NAME: Git ホストを Cloud Build に接続したときに選択した名前。プロジェクト内のすべての Cloud Build 接続を表示するには、gcloud builds connections list を実行するか、 Cloud de Confiance コンソールで [リポジトリ] ページを開きます。
  
  [リポジトリ] ページを開く
- REPOSITORY_NAME: リポジトリの名前。Cloud Build 接続の設定時に入力した値と同じものにする必要があります。
- TAG: リポジトリの Git タグ。形式は、メジャー、マイナー、パッチ番号を含む完全なセマンティックバージョンにする必要があります。たとえば、v1.0.0 は有効なタグですが、v1 や v1.0 は無効なタグです。
- CONFIG_FILE_PATH: リポジトリ内の Kubernetes リソースのパス。ファイルがリポジトリのルートにある場合、このフィールドは省略可能です。
- MAX_CLUSTERS: Kubernetes リソースを一度にデプロイするクラスタの最大数。たとえば、これを 1 に設定した場合、リソースバンドルは一度に 1 つのクラスタにデプロイされます。
  
  構成可能なすべてのフィールドの完全なリストについては、FleetPackage リファレンスドキュメントをご覧ください。
フリートパッケージを作成します。
```
gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
FLEET_PACKAGE_NAME は、フリートパッケージのロールアウトの名前に置き換えます。
フリートパッケージが作成されたことを確認します。
```
gcloud container fleet packages list
```
出力には、ビルドトリガーのステータスが一覧表示されます。数秒後、MESSAGE フィールドが更新され、次のような出力が表示されます。
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
表示されたリンクをクリックすると、Cloud Build ジョブのストリーミングログを表示できます。Cloud Build がビルドトリガーを処理するまで数分かかることがあります。

ビルドトリガーが成功すると、フリートパッケージがフリート全体で Kubernetes リソースのロールアウトを開始します。
ビルドトリガーが正常に完了すると、gcloud container fleet packages list の出力は次のようになります。
```
NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621
```
フリートパッケージが、フリート全体で Kubernetes リソースのロールアウトを開始します。

フリートパッケージをデプロイしたので、フリートに新しいクラスタを追加すると、そのフリートパッケージで定義された Kubernetes リソースが自動的に新しいクラスタにデプロイされます。

フリートパッケージを更新する

フリートパッケージを更新して、設定を変更したり、フリートパッケージがデプロイするリソースを変更できます。たとえば、次のようになります。

maxConcurrent フィールドの値を変更して、ロールアウト戦略を変更します。
state: SUSPENDED を設定して、フリートパッケージを一時的に一時停止します。フリートパッケージを一時停止しても、進行中のロールアウトはすべて続行されます。状態を ACTIVE に戻さない限り、新しいロールアウトは作成、スケジュールされません。
tag フィールドを更新して別の Git タグから pull することで、フリートパッケージがデプロイする Kubernetes リソースを更新します。

フリートパッケージを更新する手順は次のとおりです。

自身が加えた変更内容を FleetPackage の仕様に反映して更新します。
フリートパッケージを更新します。
```
gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
変更が反映され、クラスタへのロールアウトが開始されるまでに数分かかることがあります。

フリートパッケージのロールアウトを管理する

フリートパッケージのデプロイの進行状況をモニタリングし、アクティブなロールアウトを管理できます。フリートパッケージが変更されると、新しいロールアウトが自動的に作成されます。次のコマンドを使用すると、ロールアウトに関する詳細情報を取得できます。たとえば、デプロイの問題をデバッグする必要がある場合は、ロールアウトの詳細を調べて、必要に応じてロールアウトを一時停止またはキャンセルできます。

ロールアウトを一覧表示すると、パッケージに関連付けられているすべてのロールアウトのステータス（ロールアウトの失敗の原因となる可能性のあるエラーなど）を確認できます。ロールアウトを一覧表示してステータスを表示するには、次のコマンドを実行します。
```
gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME
```
出力は次のようになります。
```
ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED
```
ロールアウトを記述すると、特定のロールアウトに関する詳細情報（各ターゲットクラスタのステータスやクラスタ固有のエラーなど）を取得できます。ロールアウトの説明を取得するには、次のコマンドを実行します。
```
gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
ROLLOUT_NAME は実際のインスタンス名に置き換えます。ロールアウトのフルネームは、前の手順の list コマンドから取得できます。

出力は次のようになります。
```
CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists
```
次のコマンドを実行して、アクティブなロールアウトを管理できます。
- ロールアウトを一時停止すると、進行中のロールアウトが SUSPENDED 状態になります。進行中のパッケージアップデートは続行され、それ以降のパッケージアップデートはスケジュールされません。ロールアウトを一時停止するには、次のコマンドを実行します。
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- ロールアウトを再開すると、SUSPENDED ロールアウトが IN_PROGRESS 状態に戻ります。パッケージの更新は、計画どおりにターゲットクラスタにデプロイされます。ロールアウトを再開するには、次のコマンドを実行します。
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- 進行中のロールアウトをキャンセルすると、ロールアウトが直ちに終了し、ABORTED 状態になります。ロールアウトの一部として計画されている保留中のパッケージアップデートはすべてキャンセルされます。ロールアウトをキャンセルするには、次のコマンドを実行します。
```
gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```

ラベルを使用して別のクラスタにデプロイする

ラベルは、オブジェクトに付ける Key-Value ペアのことです。ただし、フリートパッケージがサポートしているのはフリートメンバーシップラベルのみで、GKE のクラスタラベルには対応していません。

ラベルを使用することで、フリート内のクラスタのうち特定のクラスタだけを選んで、フリートパッケージをデプロイできます。

メンバーシップラベルを追加する

メンバーシップラベルを追加する手順は次のとおりです。

フリートのメンバーシップのリストを取得します。
```
gcloud container fleet memberships list
```
メンバーシップにラベルを追加します。
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
次のように置き換えます。
- MEMBERSHIP_NAME: フリートに登録されているクラスタの名前。
- KEY と VALUE: メンバーシップに追加するラベル。ラベルが存在する場合はその値が変更され、存在しない場合は新しいラベルが作成されます。キーは小文字で始まり、使用できるのはハイフン（-）、アンダースコア（_）、小文字、数字のみです。値に使用できるのは、ハイフン（-）、アンダースコア（_）、小文字、数字のみです。
ラベルを追加するメンバーシップごとに、このコマンドを繰り返します。

クラスタの一部のみにデプロイする

target.fleet.selector.matchLabels フィールドに Key-Value ペアを指定すると、そのラベルを持つクラスタのみにデプロイできます。たとえば、matchLabels を country: "us" に設定すると、"us" と一致するラベル country を持つクラスタにのみフリートパッケージのリソースがデプロイされます。

クラスタの一部にのみフリートパッケージをデプロイする手順は次のとおりです。

ラベルセレクタを使用して FleetPackage の仕様を作成または更新します。

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

フリートパッケージを作成または更新します。

フリートパッケージを作成する

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

フリートパッケージを更新する

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

バリアントリソースをクラスタにデプロイする

バリアントとは、あるリソースの異なるバージョンのことです。これらのリソースの値は、クラスタのロケーション、プロジェクト、名前によって異なる場合があります。variantsPattern フィールドと variantNameTemplate フィールドを指定することで、バリアントリソースを異なるクラスタにデプロイできます。

メンバーシップラベルや、ロケーション、プロジェクト、名前などの他のメンバーシップメタデータを使用して、バリアントをマッチさせることができます。

バリアントを含むフリートパッケージをデプロイする手順は次のとおりです。

バリアントの詳細情報を使用して FleetPackage 仕様を作成または更新します。
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE
```
次のように置き換えます。
- VARIANT_PATTERN: バリアントのパターン（"variants/*.yaml" や "us-*" など）。
- VARIANT_NAME_TEMPLATE : ターゲットクラスタ向けのバリアント名を決定するためのテンプレート文字列。このテンプレートでは、クラスタのメンバーシップに関するメタデータ（ロケーション、プロジェクト、名前、ラベルなど）を変数として参照できます。他の例については、FleetPackage リファレンスドキュメントをご覧ください。

フリートパッケージを作成または更新します。

フリートパッケージを作成する

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

フリートパッケージを更新する

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

フリートパッケージを削除する

フリートパッケージを削除すると、次のリソースも削除されます。

クラスタにデプロイされた Kubernetes リソース
フリートパッケージのロールアウト履歴

フリートパッケージを削除するには、次のコマンドを実行します。

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

トラブルシューティング

Cloud Build に関連するエラーを診断して解決する方法については、ビルドエラーのトラブルシューティングをご覧ください。

次のステップ

FleetPackage フィールドのリファレンスページを確認する。

フリート パッケージをデプロイする

始める前に

クラスタ要件を確認する

環境を準備する

Config Sync のインストール

コンソール

gcloud

Cloud Build 用のサービス アカウントを作成する

フリート パッケージを作成する

フリート パッケージを更新する

フリート パッケージのロールアウトを管理する

ラベルを使用して別のクラスタにデプロイする

メンバーシップ ラベルを追加する

クラスタの一部のみにデプロイする

フリート パッケージを作成する

フリート パッケージを更新する

バリアント リソースをクラスタにデプロイする

フリート パッケージを作成する

フリート パッケージを更新する

フリート パッケージを削除する

トラブルシューティング

次のステップ

フリートパッケージをデプロイする

Cloud Build 用のサービスアカウントを作成する

フリートパッケージを作成する

フリートパッケージを更新する

フリートパッケージのロールアウトを管理する

メンバーシップラベルを追加する

フリートパッケージを作成する

フリートパッケージを更新する

バリアントリソースをクラスタにデプロイする

フリートパッケージを作成する

フリートパッケージを更新する

フリートパッケージを削除する