このページでは、Google Distributed Cloud コネクテッド バージョン 1.12.0 環境で Config Sync フリート パッケージを使用する方法について説明します。フリート パッケージは、Git リポジトリをクラスタ構成の信頼できる唯一の情報源として使用するツールです。
Distributed Cloud Connected のフリート パッケージは、標準の Google Kubernetes Engine クラスタと同じ基盤となるテクノロジーとコマンドを使用します。GKE ドキュメントのフリート パッケージをデプロイするページでは、フリート パッケージを作成して管理する方法について説明しています。このページでは、Distributed Cloud 接続環境に合わせてこのガイドを調整する方法について説明します。
以降のセクションでは、Distributed Cloud Connected で異なる操作が必要な点と、変更せずに GKE ドキュメントの手順に沿って操作できる点について説明します。
要件
Distributed Cloud Connected で Config Sync フリート パッケージを使用するには、次の要件があります。
- ロールアウト コントローラはクラウドに存在するため、Git リポジトリに公共のインターネット経由でアクセスできる必要があります。一般公開されていない内部またはオンプレミスの Git サーバーはサポートされていません。
- Distributed Cloud connected は、フリート Workload Identity 連携を使用して Google Cloud サービスで認証を行うことのみをサポートしています。SSH 認証鍵や Cookie など、他の Config Sync 認証方法は、クラスタとバージョン付きバンドル リポジトリ間の接続ではサポートされていません。詳細については、Workload Identity クラスタ認証をご覧ください。
- フリート内のすべてのクラスタは同じプロジェクトに存在する必要があります。Distributed Cloud Connected は、複数のプロジェクトにまたがるクラスタをフリート管理用の単一の中央プロジェクトに登録することをサポートしていません。
- Kubernetes マニフェストは、Distributed Cloud 接続ワークロードの制限事項に準拠している必要があります。これらの制限に違反するマニフェストは、クラスタ アドミッション コントローラによってブロックされます。
- フリート パッケージには Config Sync バージョン 1.16.0 以降が必要です。
システムの動作
Distributed Cloud コネクテッドのフリート パッケージには次の動作があります。
- フリート パッケージは、Kubernetes マニフェストをバージョン管理された OCI イメージに変換します。これらのイメージは、プロジェクトに自動的に作成される
fleet-packagesという名前のマネージド Artifact Registry リポジトリに保存されます。クラスタはこれらのイメージをリポジトリから直接 pull して、一貫性のある信頼性の高い配信を保証します。 - フリート パッケージは、Config Sync のブレ補正動作を継承します。クラスタのリソースに手動で行った変更は、バージョン管理された OCI バンドルと一致するように自動的に上書きされます。
- Distributed Cloud 接続クラスタが存続モードに入ると、Config Sync エージェントは最後に正常に同期された構成をローカルで適用し続けます。ただし、クラウド接続が復元されるまで、新しいロールアウトやフリート パッケージの更新は一時停止されます。
- フリート パッケージは、Config Sync の自動リソース プルーニング動作を継承します。Git リポジトリに新しいタグを作成し、新しいタグでフリート パッケージ構成を更新して同期を開始すると、Git リポジトリからマニフェストを削除した場合、Config Sync エージェントはクラスタから対応するリソースを削除します。
- 複数のフリート パッケージが同じリソースを管理している場合、所有権に関する対立が発生します。所有権の競合が発生しているときにフリート パッケージを削除しようとすると、削除が停止することがあります。この問題を解決するには、競合するフリート パッケージのいずれかを変更して、パッケージを削除する前に競合するリソースを削除します。
Distributed Cloud コネクテッドの前提条件
フリート パッケージをデプロイするの手順を行う前に、Distributed Cloud 接続環境とユーザー権限が正しく構成されていることを確認してください。
ネットワークとセキュリティ
ネットワーク環境は次の要件を満たしている必要があります。
- VPC Service Controls。 プロジェクトが VPC サービス境界で保護されている場合は、Cloud Build と Config Delivery のサービス エージェント（
service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.comなど）が境界を越えて Artifact Registry からイメージを pull する権限を持っていることを確認します。詳細については、VPC Service Controls の統合を構成するをご覧ください。 - 下り（外向き）アクセス。Distributed Cloud 接続クラスタには、
us-central1-docker.pkg.devへの下り（外向き）アクセス権が必要です。フリート パッケージは、マニフェスト バンドルを OCI イメージとして Artifact Registry に保存します。クラスタは、これらのイメージを Artifact Registry から直接 pull できる必要があります。
リポジトリの設定
マニフェスト バンドルを含む Artifact Registry リポジトリは、フリート パッケージと同じプロジェクトに存在し、us-central1 に配置されている必要があります。
必要な権限
Distributed Cloud 接続環境で手順を完了するには、プロジェクトに次の IAM ロールが必要です。
- Config Delivery 管理者（
roles/configdelivery.admin）: フリート パッケージとロールアウトの作成と管理に必要 - Developer Connect 管理者（
roles/developerconnect.admin）: リポジトリ接続の作成と管理に必要 - プロジェクト IAM 管理者（
roles/resourcemanager.projectIamAdmin）: サービス アカウントに必要なロールを付与するために必要
ロールの付与の詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。
必要な API
リポジトリ接続と、Distributed Cloud 接続クラスタとの安全な通信用に API を有効にする必要があります。必要な API を有効にするには、次の gcloud services enable コマンドを実行します。
gcloud services enable anthosconfigmanagement.googleapis.com \
configdelivery.googleapis.com \
cloudbuild.googleapis.com \
connectgateway.googleapis.com \
developerconnect.googleapis.com \
artifactregistry.googleapis.com
これらの API は、次のコンポーネントに必要です。
anthosconfigmanagement.googleapis.com: クラスタの Config Sync エージェントを管理しますconfigdelivery.googleapis.com: クラスタのフリート全体で Kubernetes リソースのロールアウトを調整しますcloudbuild.googleapis.com: Git から Kubernetes マニフェストを取得し、バージョン管理されたバンドルにパッケージ化します。connectgateway.googleapis.com: Config Delivery サービスと Distributed Cloud 接続クラスタ間の安全な接続を提供します。developerconnect.googleapis.com: 外部 Git リポジトリ ホストへの安全な接続を有効にしますartifactregistry.googleapis.com: バージョン管理されたパッケージ バンドルをプロジェクトの OCI イメージとして保存します。
デフォルトの環境設定
フリート パッケージの Config Delivery API は us-central1 でのみサポートされています。コマンドが正しく転送されるようにするには、gcloud config set コマンドを使用して、デフォルトのプロジェクトとロケーションを設定します。
デフォルト プロジェクトを設定します。
gcloud config set project PROJECT_ID
PROJECT_IDは、実際の Google Cloud プロジェクト ID に置き換えます。フリート パッケージのデフォルトのロケーションを設定します。フリート パッケージで使用されるすべての Cloud Build リポジトリ接続は、
us-central1リージョンに存在する必要があります。gcloud config set config_delivery/location us-central1
手続きの違い
次の表を使用して、フリート パッケージをデプロイするの手順を Distributed Cloud 接続環境に適用する方法を確認してください。
| 標準ステップ | Distributed Cloud コネクテッドの調整 |
|---|---|
| クラスタをフリートに登録する | このステップをスキップします。Distributed Cloud 接続クラスタは、作成時にプロジェクトのフリートに自動的に登録されます。 |
| Config Sync をインストールする | 標準の手順に沿って操作しますが、[フリート全体にインストールする（フリートのデフォルト）] の方法を使用することをおすすめします。このメソッドは、 Google Cloud コンソールの Hub または Fleet の設定で構成します。この実装により、ゾーン内の既存の Distributed Cloud 接続ノードと将来の Distributed Cloud 接続ノードは、Config Sync エージェントを自動的に受信します。 認証メンバー タイプには、Workload Identity を選択する必要があります。 Workload Identity に使用するサービス アカウントには、プロジェクトに対する roles/artifactregistry.reader ロールが必要です。これにより、Config Sync エージェントはマネージド fleet-packages リポジトリからマニフェスト バンドルを pull できます。 |
| サービス アカウントの作成 | 手順に沿って、Cloud Build のサービス アカウントを作成し、必要な権限を付与します。サービス アカウントは、フリート パッケージと同じプロジェクトに存在する必要があります。次のコマンドを使用することをおすすめします。
|
| メンバーシップ名を特定する | コマンドで MEMBERSHIP_NAME が要求された場合は、Distributed Cloud 接続クラスタの名前を使用します。クラスタ名は、gcloud container fleet memberships list コマンドを実行して確認できます。 |
| クラスタを特定する | フリート パッケージでクラスタをターゲットにする前に、ワークロードに HugePages や SR-IOV などのホストレベルのネットワーキング構成が必要な場合は、クラスタ内のすべてのノードに NodeSystemConfigUpdate リソースを適用して検証します。 |
| Git タグを特定する | ロールアウト コントローラでは、Git タグが完全なセマンティック バージョン形式（major.minor.patch）である必要があります。たとえば、v1.0.0 は有効ですが、v1 は無効です。 |
| 特定のクラスタをターゲットにする | クラスタは自動的に登録されますが、ラベル セレクタを使用してクラスタのサブセットをターゲットにする場合は、クラスタ メンバーシップに手動でラベルを追加する必要があります。 |
| デプロイ戦略 | ラベルとバリアントを使用して、特定のクラスタをターゲットにします。Distributed Cloud Connected の場合、バリアント テンプレートで使用されるメンバーシップ メタデータ変数（プロジェクトやロケーションなど）は、Distributed Cloud Connected クラスタに関連付けられたクラウドサイド リソースを参照します。 次の Distributed Cloud 固有のメンバーシップ メタデータは、バリアント テンプレートで使用できます。
|
共有プロシージャ
次の運用タスクでは、Distributed Cloud 接続と標準の GKE でコマンド構文とサービス動作が同じです。これらの手順に沿って操作する場合は、このドキュメントの手順の違いセクションの表で定義されている設定と値を使用してください。
- フリート パッケージを作成する:
FleetPackageリソースを定義して、構成を取得してデプロイします。 - フリート パッケージを更新する: パッケージを変更して、変更をロールアウトするか、設定を更新します。
- フリート パッケージのロールアウトを管理する: アクティブなロールアウトを一時停止、再開、中止します。
- リソース バンドルとリリースを検査する: バリアントの生成とバージョニングをデバッグします。リソース バンドルは構成のコンテナであり、リリースはそれらのバンドルのバージョン付きインスタンスです。Distributed Cloud コネクテッド ハードウェアへの配信が成功したことを確認するには、
gcloud container fleet memberships get-credentialsコマンドを使用してクラスタへのアクセス権を取得し、kubectlを使用してクラスタのRootSyncステータスを検査します。 - フリート パッケージを削除する: フリート パッケージとそのマネージド リソースを削除します。完全に削除するには、フリート パッケージに関連付けられているマネージド
RootSyncオブジェクトがクラスタから削除されていることを確認します。
モニタリングとトラブルシューティング
デプロイをより効果的にモニタリングするには、gcloud コマンドで --format フラグを使用して、ロールアウト中に詳細なステータス メッセージを取得します。
たとえば、次の gcloud container fleet packages rollouts describe コマンドを実行すると、フリート内のすべてのクラスタの詳細なステータス メッセージが表示されます。
gcloud container fleet packages rollouts describe ROLLOUT_NAME \
--fleet-package=FLEET_PACKAGE_NAME \
--format=json
次の値を置き換えます。
ROLLOUT_NAME: ロールアウトの名前。FLEET_PACKAGE_NAME: フリート パッケージの名前。
ビルドが失敗または停止した場合は、gcloud container fleet packages list コマンドの出力で Cloud Build ジョブのストリーミング ログへのリンクを確認できます。ロールアウトが PENDING 状態または STALLED 状態のままの場合は、Distributed Cloud コネクテッドのトラブルシューティングの説明に沿って、Distributed Cloud コネクテッド ハードウェアの接続を確認します。
Cloud Build に関連するエラーの診断の詳細については、ビルドエラーのトラブルシューティングをご覧ください。
クラスタ内の同期ステータスを確認する
クラスタがフリート パッケージと正常に同期していることを確認するには、クラスタの RootSync リソースを調べます。クラスタ上の RootSync オブジェクトの名前は、パッケージに選択した FLEET_PACKAGE_NAME と同じです。
ステータスを確認するには、次のコマンドを実行します。
kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system
同期が成功すると、ステータスが SYNCED になります。Error ステータスが表示された場合は、次のコマンドを実行して詳細を取得します。
kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system
詳細については、GKE ドキュメントの RootSync オブジェクトと RepoSync オブジェクトをモニタリングするをご覧ください。
出力内の特定のエラーコードのデコードについては、Config Sync エラーのリファレンスをご覧ください。