フリート パッケージについて

Config Sync の FleetPackage 宣言型 API を使用すると、フリートに登録されているクラスタにフリート パッケージをデプロイして管理できます。パッケージは、クラスタ構成を定義する Kubernetes YAML マニフェストのセットです。フリート パッケージを使用すると、構成の更新をフリートに一括でデプロイすることも、段階的にデプロイすることもできます。これにより、広範囲にわたる停止のリスクを軽減できます。

各 FleetPackage オブジェクトを 1 回定義したら、構成の変更に応じてそのパッケージを新しいリビジョンで更新します。新しいリビジョンを適用すると、フリート パッケージ サービスがそれらの変更を自動的に検出して、ターゲット クラスタにデプロイします。

利点

フリート パッケージは、ドリフトの自動修正などの Config Sync の機能を基盤として、次のような利点を提供します。

  • リソースのロールアウトを自動化する: フリート パッケージを設定すると、そのフリート パッケージが参照する Kubernetes リソースがフリート パッケージ サービスによって自動的にすべてのクラスタにデプロイされます。

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

  • Kubernetes 構成を大規模に管理する: クラスタを 1 つずつ管理するのではなく、フリート パッケージを使用してクラスタのフリート全体にリソースをデプロイできます。

  • 誤った変更の影響を最小限に抑える: リソースを一度にデプロイするクラスタの最大数を選択できます。誤った変更がフリート全体に影響しないように、各クラスタの変更を綿密にモニタリングできます。

  • Config Sync の構成を簡素化する: フリート パッケージは Cloud Build を使用して Git の認証を行うため、認証が RootSync オブジェクトまたは RepoSync オブジェクトごとに 1 回ではなくプロジェクトごとに 1 回になります。

次のいずれかのシナリオに該当する場合は、フリート パッケージではなく、RootSync オブジェクトまたは RepoSync オブジェクトで Config Sync を使用することをおすすめします。

  • 管理するクラスタが少ない。

  • リソースをクラスタにデプロイする方法をより細かく制御する必要がある（FleetPackage API のラベルとバリアントによる制御では足りない）。

要件と制限事項

  • フリート パッケージを構成する場合、信頼できる情報源としてサポートされるのは Git リポジトリのみです。

  • Git に保存されている Kubernetes リソースは、リソースの最終状態を表す必要があります。Git に保存されているリソースを変換する追加のオーバーレイはサポートされていません。これらのリソースの違いの詳細については、ベスト プラクティス: WET リポジトリを作成するをご覧ください。

  • FleetPackage API は us-central1 リージョンでのみ使用できます。異なるリージョンのクラスタにデプロイすることはできますが、us-central1 で Cloud Build を設定し、gcloud CLI を構成する必要があります。

  • フリート パッケージの最大数は、プロジェクトあたりリージョンごとに 300 個です。

アーキテクチャ

FleetPackage API を使用して、Kubernetes マニフェストをクラスタのフリート全体にデプロイできます。FleetPackage API は、Cloud Build を使用して Git リポジトリから Kubernetes リソースを同期して取得します。その後、フリート パッケージ サービスがそれらのリソースをクラスタにデプロイします。

Git の Kubernetes リソースがクラスタのフリートに同期されるフローを示した図

パターンの生成方法

フリート パッケージは、バリアントのシステムを使用して、同じ Git リポジトリからフリート内の異なるクラスタまたはクラスタ グループに異なる Kubernetes リソース構成をデプロイします。

FleetPackage 仕様には、バリアントの動作を制御する 2 つのフィールドがあります。

  1. resourceBundleSelector.cloudBuildRepository.variantsPattern: Git リポジトリ内のファイルとディレクトリを検索するために使用される glob パターン（指定された path の下、または path が省略されている場合はリポジトリのルート）。このパターンによって、どのファイルまたはディレクトリがバリアントになり、どのようなコンテンツが含まれるかが決まります。
  2. variantSelector.variantNameTemplate: フリート内の各クラスタを variantsPattern によって生成されたバリアント名のいずれかにマッピングする式。この選択は、クラスタのフリート メンバーシップ メタデータに基づいています。

variantsPattern 一致

variantsPattern フィールドは、リポジトリに保存されている構成からバリアントを生成する方法を指定するために必須です。照合には次のロジックが使用されます。

  • ファイルの一致: パターンが YAML ファイルと一致すると、バリアントが作成されます。

    • バリアント名: 拡張子なしのファイル名（例: prod-config.yaml はバリアント prod-config になります）。
    • バリアント コンテンツ: この単一ファイルのコンテンツ。

  • ディレクトリの一致: パターンがディレクトリと一致する場合、バリアントが作成されます。

    • バリアント名: ディレクトリ名（たとえば、ディレクトリ dev はバリアント dev になります）。
    • バリアント コンテンツ: このディレクトリとそのすべてのサブディレクトリ内にあるすべての YAML ファイルの組み合わせ（再帰的）。

ファイル一致パターンには次の制限があります。

  • 再帰（二重）ワイルドカードは使用できません。** パターンはサポートされていません。
  • パターンにドット（.）文字が含まれている場合は、その後に英数字を続ける必要があります。
  • パターンに一重引用符（'）を含めることはできません。
  • バリアント名は一意である必要があります。パターンが同じ名前の複数のファイル（app1/deploy.yaml と app2/deploy.yaml など）に一致する場合、両方とも deploy という名前のバリアントを作成しようとするため、名前の競合が発生します。

例として、次の構造を持つリポジトリについて考えてみましょう。

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

フリート パッケージ仕様で定義するファイルまたはディレクトリの一致タイプに応じて、異なるファイルを一致させてクラスタに同期できます。次に例を示します。

  • variantsPattern: "*": common-ingress.yaml、us-central1-a、us-central1-b と一致します。バリアントを生成します。

    • common-ingress（ファイルから）
    • us-central1-a（そのフォルダ内のすべての YAML ファイルを結合）
    • us-central1-b（そのフォルダ内のすべての YAML を結合）

  • variantsPattern: "*.yaml": common-ingress.yaml と一致します。バリアントを生成します。

    • common-ingress

  • variantsPattern: "us-*": us-central1-a と us-central1-b に一致します。バリアントを生成します。

    • us-central1-a
    • us-central1-b

  • variantsPattern: "us-central1-b/*.yaml": us-central1-b/gke-1.yaml と us-central1-b/blue-green.yaml に一致します。バリアントを生成します。

    • gke-1
    • blue-green

variantNameTemplate 一致

バリアントが定義されると、variantSelector セクションの variantNameTemplate フィールドによって、各クラスタに適用されるバリアントが決定されます。テンプレートでは、変数を使用して次のフリート メンバーシップ メタデータにアクセスできます。

  • ${membership.name}: クラスタのフリート メンバーシップ名。
  • ${membership.location}: フリート メンバーシップのロケーション。
  • ${membership.project}: フリート メンバーシップ プロジェクト。
  • ${membership.labels['KEY']}: フリート メンバーシップのラベル KEY の値。

たとえば、ラベルを使用してバリアントを照合する次のシナリオについて考えてみましょう。

  • variantNameTemplate: "${membership.labels['env']}": ラベル env: prod が付いたクラスタは、prod という名前のバリアントに同期されます。
  • variantNameTemplate: "${membership.location}": クラスタは、ロケーションに一致するバリアントに同期します（例: us-central1-a）。
  • variantNameTemplate: "default": クラスタは default という名前のバリアントに同期されます。variantSelector を省略した場合、これがデフォルトの動作です。リポジトリに default.yaml という名前のファイルまたは default という名前のディレクトリが含まれていない場合、何も同期されません。

variantsPattern と variantNameTemplate の組み合わせ

デプロイを成功させるには、variantsPattern によって生成されたバリアント名が、variantNameTemplate と一致することでクラスタが同期できる名前であることを確認する必要があります。

たとえば、環境ラベルに基づいてクラスタにデプロイするには、dev、staging、prod などのディレクトリを使用して Git リポジトリを構成します。この場合、次のフリート パッケージ仕様を使用します。

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

この構成では、env: staging というラベルの付いたクラスタが manifests/staging/ ディレクトリの内容を受け取ります。

デプロイ戦略

フリート パッケージを使用すると、Git リポジトリからクラスタのフリート全体にリソースをデプロイできます。フリート パッケージを構成して、デプロイするリソースの種類、方法、場所を制御することもできます。

次のセクションでは、さまざまな FleetPackage 構成の例を示します。フリート パッケージの適用の詳細については、フリート パッケージをデプロイするをご覧ください。

フリート内のすべてのクラスタへのデプロイ

次の FleetPackage は、ローリング戦略を使用して Kubernetes リソースを一度に 3 つのクラスタにデプロイし、フリート内のすべてのクラスタをターゲットにします。

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

クラスタのサブセットへのデプロイ

次の FleetPackage は、ラベルセレクタを使用して、フリート内のクラスタのうち、"us" と一致するメンバーシップ ラベル country を持つクラスタにのみ Kubernetes リソースをデプロイします。

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

次のステップ

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