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

このページでは、フリート パッケージ、FleetPackage API、およびそれらが Config Sync とどのように関連しているかについて説明します。

FleetPackage は、フリート全体でパッケージを管理できる宣言型 API です。フリート パッケージは、クラスタ構成を定義する Kubernetes YAML マニフェストのセットです。フリート パッケージを使用すると、フリートに登録されているクラスタに、一括ロールアウトまたは段階的なロールアウトでパッケージをデプロイできます。

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

利点

フリート パッケージを使用すると、フリートに登録されているすべてのクラスタに Kubernetes リソースをデプロイできます。フリート パッケージを作成して適用すると、Git リポジトリ内の Kubernetes 構成ファイルが自動的に新しいクラスタにデプロイされます。フリート パッケージは、ドリフトの自動修正などの 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 を構成する必要があります。

  • フリート パッケージの最大数は、プロジェクトごとに 1 リージョンあたり 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 と一致させて同期できる名前であることを確認する必要があります。

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

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

次のステップ

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