Distributed Cloud コネクテッドでフリート パッケージを使用する

このページでは、Google Distributed Cloud コネクテッド環境で Config Sync のフリート パッケージを使用する方法について説明します。フリート パッケージは、Git リポジトリをクラスタ構成の信頼できる唯一の情報源として使用するツールです。

Distributed Cloud コネクテッドのフリート パッケージは、標準の Google Kubernetes Engine クラスタと同じ基盤となるテクノロジーとコマンドを使用します。GKE ドキュメントのフリート パッケージをデプロイするページでは、フリート パッケージを作成して管理する方法について説明しています。 このページでは、そのガイドを Distributed Cloud コネクテッド環境に合わせて調整する方法について説明します。

以降のセクションでは、Distributed Cloud コネクテッドで異なる操作が必要な点と、GKE ドキュメントの手順をそのまま使用できる点について説明します。

要件

Distributed Cloud コネクテッドで Config Sync のフリート パッケージを使用するには、次の要件を満たす必要があります。

• ロールアウト コントローラはクラウドに存在するため、Git リポジトリは公共のインターネット経由でアクセスできる必要があります。一般公開されていない内部またはオンプレミスの Git サーバーはサポートされていません。
• Distributed Cloud コネクテッドでは、 サービスとの認証にフリート Workload Identity 連携を使用することのみがサポートされています。 Google Cloud クラスタとバージョン管理されたバンドル リポジトリ間の接続では、SSH 認証鍵や Cookie などの他の Config Sync 認証方法はサポートされていません。詳細については、 Workload Identity クラスタ認証をご覧ください。
• フリート内のすべてのクラスタは同じプロジェクトに存在する必要があります。 Distributed Cloud コネクテッドでは、複数のプロジェクトのクラスタをフリート管理用の単一の中央プロジェクトに登録することはできません。
• 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 サービス エージェント（[e-mail] など）が境界を越えて 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 コマンドを使用して、デフォルトのプロジェクトとロケーションを設定します。

1. デフォルト プロジェクトを設定します。

   gcloud config set project PROJECT_ID
   

   PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

2. フリート パッケージのデフォルトのロケーションを設定します。フリート パッケージで使用されるすべての Cloud Build リポジトリ接続は、us-central1 リージョンに存在する必要があります。

   gcloud config set config_delivery/location us-central1
   

手順の違い

次の表を使用して、 フリート パッケージをデプロイする の手順を Distributed Cloud コネクテッド環境に適用する方法を確認してください。

標準的な手順	Distributed Cloud コネクテッドの調整
クラスタをフリートに登録する	このステップをスキップします。Distributed Cloud コネクテッド クラスタは、作成時にプロジェクトのフリートに自動的に 登録されます。
Config Sync をインストールする	標準的な手順に沿って操作しますが、 フリート全体にインストール（フリートのデフォルト） の方法を使用することをおすすめします。この方法は、コンソールの [ハブ] または [フリート] の設定で構成します。 Google Cloud この実装により、ゾーン内の既存または将来の Distributed Cloud コネクテッド ノードは、Config Sync エージェントを自動的に 受信します。 認証メンバー タイプには、 Workload Identity を選択する必要があります。 Workload Identity に使用するサービス アカウントには、プロジェクトに対する roles/artifactregistry.reader ロールが必要です。 これにより、Config Sync エージェントは マネージド fleet-packages リポジトリからマニフェスト バンドルを pull できます。
サービス アカウントを作成する	手順に沿って、Cloud Build のサービス アカウントを作成し、必要な権限を付与します。サービス アカウントは、フリート パッケージと同じプロジェクトに存在する必要があります。次のコマンドを使用することをおすすめします。 gcloud iam service-accounts create コマンドを実行してサービス アカウントを作成します。 gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME" SERVICE_ACCOUNT_NAME をサービス アカウントの名前に置き換えます。 次の各ロールに対して gcloud projects add-iam-policy-binding コマンドを実行して、必須の Identity and Access Management ロールを追加します。IAM の詳細については、 IAM の概要をご覧ください。 roles/configdelivery.resourceBundlePublisher: サービス アカウントがリソース バンドルとリリースを作成して管理できるようにします。 roles/cloudbuild.connectionUser: サービス アカウントが Cloud Build リポジトリ接続を使用できるようにします。 roles/logging.logWriter: サービス アカウント がビルドログを書き込めるようにします。 roles/artifactregistry.writer: サービス アカウントがバージョン管理されたパッケージ バンドルを Artifact Registry に push できるようにします。 roles/developerconnect.connectionUser: サービス アカウントが Developer Connect 接続を使用できるようにします。 サービス アカウントには、Git プロバイダの接続された Git リポジトリから読み取る権限も必要です。接続を認可する方法については、リポジトリに接続するをご覧ください。
メンバーシップ名を特定する	コマンドで MEMBERSHIP_NAME を求められたら、Distributed Cloud コネクテッド クラスタの名前を使用します。クラスタ名は、 gcloud container fleet memberships list コマンドを実行して確認できます。
クラスタを特定する	フリート パッケージでクラスタをターゲットにする前に、ワークロードに HugePages や SR-IOV などのホストレベルのネットワーク構成が必要な場合は、クラスタ内のすべてのノードに NodeSystemConfigUpdate リソースを適用して確認します。
Git タグを特定する	ロールアウト コントローラでは、Git タグが完全なセマンティック バージョン形式（major.minor.patch）である必要があります。たとえば、v1.0.0 は有効ですが、v1 は無効です。
特定のクラスタをターゲットにする	クラスタは自動的に登録されますが、ラベルセレクタを使用してクラスタのサブセットをターゲットにする場合は、クラスタ メンバーシップにラベルを 手動で追加 する必要があります。
デプロイ戦略	ラベルとバリアントを使用して、特定のクラスタをターゲットにします。Distributed Cloud コネクテッドの場合、バリアント テンプレートで使用されるプロジェクトやロケーションなどのメンバーシップ メタデータ変数は、Distributed Cloud コネクテッド クラスタに関連付けられたクラウド側のリソースを参照します。 次の Distributed Cloud 固有のメンバーシップ メタデータは、 バリアント テンプレートで使用できます。 cluster_name: Distributed Cloud コネクテッド クラスタの名前 location: クラスタに関連付けられた リージョン Google Cloud project: クラスタが登録されているプロジェクト ID labels: クラスタ メンバーシップに適用したラベル

共通の手順

次のオペレーション タスクでは、コマンド構文とサービス動作は、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: フリート パッケージの名前。

ビルドが失敗した場合や停止した場合は、Cloud Build ジョブのストリーミング ログへのリンクを gcloud container fleet packages list コマンドの出力で確認できます。ロールアウトが 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 エラーのリファレンスをご覧ください。