Flottenpakete

Auf dieser Seite werden Flottenpakete, die FleetPackage API und ihre Beziehung zu Config Sync erläutert.

Eine FleetPackage ist eine deklarative API, mit der Sie Pakete in einer Flotte verwalten können. Ein Flottenpaket ist eine Sammlung von Kubernetes-YAML-Manifesten, die die Clusterkonfiguration definieren. Mit Flottenpaketen können Sie Pakete über einen sofortigen oder progressiven Roll‑out in Clustern bereitstellen, die in Ihrer Flotte registriert sind.

Sie definieren jedes FleetPackage-Objekt einmal und können das Paket dann mit einer neuen Überarbeitung aktualisieren. Wenn Sie eine neue Revision anwenden, übernimmt der Flottenpaketdienst diese Änderungen und stellt sie in Ihren Clustern bereit.

Vorteile

Mit Flottenpaketen können Sie Kubernetes-Ressourcen in Clustern bereitstellen, die in einer Flotte registriert sind. Nachdem Sie ein Flottenpaket erstellt und angewendet haben, werden die Kubernetes-Konfigurationsdateien im Git-Repository automatisch im neuen Cluster bereitgestellt. Fleet-Pakete bauen auf den Vorteilen von Config Sync wie der automatischen Driftkorrektur auf und bieten die folgenden einzigartigen Vorteile:

  • Ressourcenbereitstellung automatisieren:Nachdem Sie ein Flottenpaket eingerichtet haben, werden die Kubernetes-Ressourcen, auf die es verweist, automatisch vom Flottenpaketdienst in allen Clustern bereitgestellt.

  • Neue Cluster automatisch konfigurieren: Wenn Sie ein Flottenpaket konfigurieren und später einer Flotte neue Cluster hinzufügen, werden alle durch das Flottenpaket definierten Ressourcen automatisch im neuen Cluster bereitgestellt.

  • Kubernetes-Konfigurationen im großen Maßstab verwalten:Anstatt Cluster einzeln zu verwalten, können Sie mit Flottenpaketen Ressourcen in einer ganzen Flotte von Clustern bereitstellen.

  • Auswirkungen falscher Änderungen minimieren:Wählen Sie eine maximale Anzahl von Clustern aus, in denen Ressourcen gleichzeitig bereitgestellt werden sollen. Sie können die Änderungen an den einzelnen Clustern genau beobachten, um sicherzustellen, dass sich falsche Änderungen nicht auf Ihre gesamte Flotte auswirken.

  • Config Sync-Konfiguration vereinfachen:Flottenpakete verwenden Cloud Build zur Authentifizierung bei Git. Das bedeutet, dass Sie sich einmal pro Projekt authentifizieren müssen und nicht einmal pro RootSync- oder RepoSync-Objekt.

Möglicherweise bevorzugen Sie die Verwendung von Config Sync mit RootSync- oder RepoSync-Objekten anstelle von Flottenpaketen, wenn eines oder mehrere der folgenden Szenarien auf Sie zutreffen:

  • Sie verwalten eine kleine Anzahl von Clustern.

  • Sie benötigen mehr Kontrolle darüber, wie Ressourcen in Ihren Clustern bereitgestellt werden, als die Fleet Package API mit Labels und Varianten bietet.

Anforderungen und Einschränkungen

  • Beim Konfigurieren eines Flottenpakets werden nur Git-Repositories als Source of Truth unterstützt.

  • Die in Git gespeicherten Kubernetes-Ressourcen müssen den Endzustand der Ressource darstellen. Zusätzliche Overlays zum Transformieren der in Git gespeicherten Ressource werden nicht unterstützt. Weitere Informationen zu den Unterschieden zwischen diesen Ressourcen finden Sie unter Best Practice: WET-Repositories erstellen.

  • Die FleetPackage API ist nur in der Region us-central1 verfügbar. Sie können weiterhin in Clustern in verschiedenen Regionen bereitstellen, müssen aber Cloud Build einrichten und die gcloud CLI in us-central1 konfigurieren.

  • Die maximale Anzahl von Flottenpaketen beträgt 300 pro Projekt und Region.

Architektur

Mit der FleetPackage API können Sie Kubernetes-Manifeste in einer Flotte von Clustern bereitstellen. Die FleetPackage API verwendet Cloud Build, um Kubernetes-Ressourcen aus Ihrem Git-Repository zu synchronisieren und abzurufen. Der Flottenpaketdienst stellt diese Ressourcen dann in Ihren Clustern bereit.

Diagramm, das den Fluss von Kubernetes-Ressourcen beim Git-Syncing zu einer Flotte von Clustern zeigt

So werden Varianten generiert

Flottenpakete verwenden ein System von Varianten, um verschiedene Kubernetes-Ressourcenkonfigurationen in verschiedenen Clustern oder Clustergruppen in Ihrer Flotte bereitzustellen, aber aus demselben Git-Repository.

Es gibt zwei Felder in der FleetPackage-Spezifikation, die das Verhalten von Varianten steuern:

  1. resourceBundleSelector.cloudBuildRepository.variantsPattern: Ein Glob-Muster, mit dem Dateien und Verzeichnisse in Ihrem Git-Repository gefunden werden (unter dem angegebenen path oder dem Repository-Stammverzeichnis, wenn path weggelassen wird). Mit diesem Muster wird festgelegt, welche Dateien oder Verzeichnisse zu Varianten werden und welche Inhalte sie enthalten.
  2. variantSelector.variantNameTemplate: Ein Ausdruck, der jeden Cluster in Ihrer Flotte einem der von variantsPattern generierten Variantennamen zuordnet. Diese Auswahl basiert auf den Metadaten zur Flottenmitgliedschaft des Clusters.

variantsPattern-Abgleich

Das Feld variantsPattern ist erforderlich, um anzugeben, wie Varianten aus den in Ihrem Repository gespeicherten Konfigurationen generiert werden sollen. Für den Abgleich wird die folgende Logik verwendet:

  • Dateiabgleich:Wenn das Muster mit einer YAML-Datei übereinstimmt, wird eine Variante erstellt.

    • Name der Variante:Der Dateiname ohne die Erweiterung (z. B. wird prod-config.yaml zur Variante prod-config).
    • Inhalt der Variante:Der Inhalt dieser einzelnen Datei.

  • Verzeichnisübereinstimmung:Wenn das Muster mit einem Verzeichnis übereinstimmt, wird eine Variante erstellt.

    • Name der Variante:Der Verzeichnisname (z. B. wird aus dem Verzeichnis dev die Variante dev).
    • Varianteninhalte:Die Kombination aller YAML-Dateien, die rekursiv in diesem Verzeichnis und allen zugehörigen Unterverzeichnissen gefunden werden.

Für Muster zum Abgleichen von Dateien gelten die folgenden Einschränkungen:

  • Keine rekursiven (doppelten) Platzhalter. Das Muster ** wird nicht unterstützt.
  • Wenn ein Muster einen Punkt (.) enthält, muss darauf ein alphanumerisches Zeichen folgen.
  • Muster dürfen keine einfachen Anführungszeichen (') enthalten.
  • Varianten müssen eindeutige Namen haben. Wenn Ihr Muster mit mehreren Dateien mit demselben Namen übereinstimmt (z. B. app1/deploy.yaml und app2/deploy.yaml), wird für beide versucht, eine Variante mit dem Namen deploy zu erstellen, was zu einem Namenskonflikt führt.

Betrachten Sie als Beispiel ein Repository mit der folgenden Struktur:

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

Sie können verschiedene Dateien abgleichen und so mit Ihren Clustern synchronisieren, je nachdem, welche Art von Datei- oder Verzeichnisabgleich Sie in der Flottenpaketspezifikation definieren, z. B.:

  • variantsPattern: "*": Entspricht common-ingress.yaml, us-central1-a und us-central1-b. Varianten generieren:

    • common-ingress (aus Datei)
    • us-central1-a (Kombinieren aller YAML-Dateien in diesem Ordner)
    • us-central1-b (alle YAML-Dateien in diesem Ordner werden kombiniert)

  • variantsPattern: "*.yaml": Entspricht common-ingress.yaml. Generiert Variante:

    • common-ingress

  • variantsPattern: "us-*": Entspricht us-central1-a und us-central1-b. Varianten generieren:

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

  • variantsPattern: "us-central1-b/*.yaml": Entspricht us-central1-b/gke-1.yaml und us-central1-b/blue-green.yaml. Varianten generieren:

    • gke-1
    • blue-green

variantNameTemplate-Abgleich

Nachdem die Varianten definiert wurden, wird im Feld variantNameTemplate im Abschnitt variantSelector festgelegt, welche Variante auf die einzelnen Cluster angewendet wird. In der Vorlage können Variablen verwendet werden, um auf die folgenden Metadaten zur Flottenmitgliedschaft zuzugreifen:

  • ${membership.name}: Der Name der Flottenmitgliedschaft des Clusters.
  • ${membership.location}: Der Standort der Flottenmitgliedschaft.
  • ${membership.project}: Das Projekt für die Flottenmitgliedschaft.
  • ${membership.labels['KEY']}: Der Wert des Labels KEY für die Flottenmitgliedschaft.

Betrachten Sie beispielsweise die folgenden Szenarien, in denen Labels verwendet werden, um Varianten abzugleichen:

  • variantNameTemplate: "${membership.labels['env']}": Ein Cluster mit dem Label env: prod wird mit einer Variante namens prod synchronisiert.
  • variantNameTemplate: "${membership.location}": Cluster werden mit Varianten synchronisiert, die ihrem Standort entsprechen (z. B. us-central1-a).
  • variantNameTemplate: "default": Cluster werden mit einer Variante namens default synchronisiert. Dies ist das Standardverhalten, wenn variantSelector weggelassen wird. Wenn Ihr Repository keine Datei mit dem Namen default.yaml oder kein Verzeichnis mit dem Namen „default“ enthält, wird nichts synchronisiert.

variantsPattern und variantNameTemplate kombinieren

Damit die Bereitstellung erfolgreich ist, müssen die von Ihrem variantsPattern generierten Variantennamen mit den Namen übereinstimmen, die Ihre Cluster synchronisieren können, indem sie dem variantNameTemplate entsprechen.

Wenn Sie beispielsweise in Clustern bereitstellen möchten, die auf einem Umgebungslabels basieren, können Sie Ihr Git-Repository mit Verzeichnissen wie dev, staging und prod strukturieren. Sie würden dann die folgende Spezifikation für das Flottenpaket verwenden:

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

Bei dieser Konfiguration erhält ein Cluster mit dem Label env: staging den Inhalt des Verzeichnisses manifests/staging/.

Bereitstellungsstrategien

Mit Flottenpaketen können Sie Ressourcen aus einem Git-Repository in Ihrer gesamten Clusterflotte bereitstellen. Sie können Ihr Flottenpaket auch so konfigurieren, dass Sie steuern können, wie, wo und welche Art von Ressourcen bereitgestellt werden.

Im folgenden Abschnitt finden Sie Beispiele für verschiedene FleetPackage-Konfigurationen. Weitere Informationen zum Anwenden von Flottenpaketen finden Sie unter Flottenpakete bereitstellen.

Bereitstellung in allen Clustern einer Flotte

Im folgenden FleetPackage wird eine Rolling-Strategie verwendet, um Kubernetes-Ressourcen in jeweils drei Clustern bereitzustellen. Das Ziel sind alle Cluster in einer Flotte:

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

Bereitstellung in einer Teilmenge von Clustern

Im folgenden FleetPackage wird ein Label-Selektor verwendet, um Kubernetes-Ressourcen nur in Clustern mit dem Mitgliedschaftslabel country bereitzustellen, das mit "us" in der Flotte übereinstimmt:

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

Nächste Schritte

Flottenpakete bereitstellen