Flottenpakete bereitstellen

Auf dieser Seite wird beschrieben, wie Sie mit Config Sync-Flottenpaketen Kubernetes-Ressourcen in Clustern bereitstellen, die in einer Flotte registriert sind. Nachdem Sie ein Flottenpaket erstellt und bereitgestellt haben, werden die Kubernetes-Konfigurationsdateien im Git-Repository automatisch im neuen Cluster bereitgestellt, wenn Sie Ihrer Flotte einen neuen Cluster hinzufügen.

Eine FleetPackage ist eine deklarative API, um Kubernetes-Rohmanifeste in einer Flotte von Clustern bereitzustellen. Alle Kubernetes-Ressourcen, die Sie mit einem Flottenpaket bereitstellen möchten, müssen bereits hydriert (WET) sein.

Hinweise

  1. Erstellen Sie ein Git-Repository mit den Kubernetes-Ressourcen, die Sie in einer Flotte bereitstellen möchten, oder sorgen Sie dafür, dass Sie darauf zugreifen können.

  2. Installieren und initialisieren Sie das Google Cloud CLI, das die Befehle gcloud und nomos enthält. Wenn Sie Cloud Shell verwenden, ist die Google Cloud CLI vorinstalliert. Wenn Sie die Google Cloud CLI bereits installiert haben, rufen Sie die neueste Version mit gcloud components update ab.

  3. Aktivieren Sie die Config Sync API (anthosconfigmanagement) und die ConfigDelivery API:

    gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

  4. Standardstandort festlegen:

    gcloud config set config_delivery/location us-central1

  5. Standardprojekt festlegen:

    gcloud config set project PROJECT_ID

    Ersetzen Sie PROJECT_ID durch die Projekt-ID des Flotten-Hostprojekts.

  6. Prüfen Sie, ob Ihre Cluster in einer Flotte registriert sind.

  7. Mit Cloud Build-Repositories können Sie eine Verbindung zu einem unterstützten Anbieter wie GitHub oder GitLab herstellen. Wenn Sie ein Flottenpaket verwenden, müssen Sie Cloud Build nur einmal pro Repository einrichten, das Sie synchronisieren möchten.

Clusteranforderungen prüfen

Bevor Sie Config Sync in Ihrem Cluster installieren, sollten Sie die Empfehlungen und Anforderungen für die Clusterkonfiguration lesen.

Umgebung vorbereiten

Um Ihre Umgebung für Config Sync-Flottenpakete vorzubereiten, weisen Sie dem Nutzer, der den Cluster registriert, die erforderlichen IAM-Rollen zu.

Config Sync installieren

Sie können Config Sync entweder mit der Google Cloud Console oder der Google Cloud CLI installieren.

Console

Alle Cluster müssen bei einer Flotte registriert sein, um Config Sync zu installieren. Wenn Sie Config Sync in der Google Cloud Konsole installieren, werden die ausgewählten Cluster automatisch in Ihrer Flotte registriert.

  1. Rufen Sie in der Google Cloud Console im Abschnitt Funktionen die Seite Konfiguration auf.

    Zu „Config“

  2. Klicken Sie auf Config Sync installieren.

  3. Wählen Sie unter Installationsoptionen die Option Config Sync in der gesamten Flotte installieren (empfohlen) aus.

  4. Klicken Sie auf Config Sync installieren. Nach einigen Minuten sollte auf dem Tab Einstellungen in der Spalte Status für die Cluster in Ihrer Flotte Aktiviert angezeigt werden.

gcloud

  1. Aktivieren Sie das Flottenfeature ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Um Config Sync zu aktivieren, erstellen Sie eine Datei mit dem Namen apply-spec.yaml mit folgendem Inhalt:

    applySpecVersion: 1
spec:
  configSync:
    enabled: true

  3. Wenden Sie die Datei apply-spec.yaml an:

    gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml

    Ersetzen Sie MEMBERSHIP_NAME durch den Namen der Flottenmitgliedschaft, den Sie bei der Registrierung Ihres Clusters ausgewählt haben. Führen Sie den Befehl gcloud container fleet memberships list aus, um den Namen der Mitgliedschaft zu ermitteln.

Dienstkonto für Cloud Build erstellen

Flottenpakete verwenden Cloud Build, um die Kubernetes-Ressourcen aus Ihrem Git-Repository abzurufen und in Ihren Clustern bereitzustellen. Für Cloud Build ist ein Dienstkonto mit den Berechtigungen zum Ausführen dieses Jobs erforderlich. Führen Sie die folgenden Schritte aus, um das Dienstkonto zu erstellen und die erforderlichen Berechtigungen zu erteilen:

  1. Erstellen Sie das Dienstkonto:

    gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"

    Ersetzen Sie SERVICE_ACCOUNT_NAME durch einen Namen für das Dienstkonto. Der Name muss eine alphanumerische ID mit einer Länge zwischen 6 und 30 Zeichen sein, z. B. my-service-account. Nachdem Sie ein Dienstkonto erstellt haben, können Sie den Namen nicht mehr ändern.

  2. Fügen Sie eine IAM-Richtlinienbindung für die Rolle „Resource Bundle Publisher“ hinzu:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

    Wenn Sie dazu aufgefordert werden, wählen Sie None als Bedingung für die Richtlinie aus.

  3. Fügen Sie eine IAM-Richtlinienbindung für die Rolle Logs Writer hinzu:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

    Wenn Sie dazu aufgefordert werden, wählen Sie None als Bedingung für die Richtlinie aus.

  4. Fügen Sie eine IAM-Richtlinienbindung für die Rolle ArtifactRegistry Writer hinzu:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

    Wenn Sie dazu aufgefordert werden, wählen Sie None als Bedingung für die Richtlinie aus.

Flottenpaket erstellen

Zum Erstellen eines Flottenpakets definieren Sie eine FleetPackage-Spezifikation, die auf das Repository mit Ihren Kubernetes-Ressourcen verweist, die Sie mit Cloud Build verbunden haben. Anschließend wenden Sie die FleetPackage an, die die Ressourcen aus Git abruft und in der gesamten Flotte bereitstellt.

  1. Erstellen Sie eine Datei mit dem Namen fleetpackage-spec.yaml und dem folgendem Inhalt:

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED

    Ersetzen Sie Folgendes:

    • CONNECTION_NAME: Der Name, den Sie beim Verbinden Ihres Git-Hosts mit Cloud Build ausgewählt haben. Sie können alle Cloud Build-Verbindungen in Ihrem Projekt ansehen, indem Sie gcloud builds connections list ausführen oder die Seite Repositories in der Google Cloud Console öffnen:

      Zur Seite „Repositories“

    • REPOSITORY_NAME: der Name Ihres Repositorys. Dieser Wert muss mit dem Wert übereinstimmen, der bei der Einrichtung der Cloud Build-Verbindung eingegeben wurde.

    • TAG: Das Git-Tag Ihres Repositorys. Das Format muss die vollständige semantische Version mit der Haupt-, Neben- und Patchnummer sein. v1.0.0 ist beispielsweise ein gültiges Tag, v1 oder v1.0 hingegen nicht.

    • CONFIG_FILE_PATH: Der Pfad zu Ihren Kubernetes-Ressourcen im Repository. Wenn sich Ihre Dateien im Stammverzeichnis des Repositorys befinden, können Sie dieses Feld weglassen.

    • MAX_CLUSTERS: Die maximale Anzahl von Clustern, in denen Kubernetes-Ressourcen gleichzeitig bereitgestellt werden sollen. Wenn Sie diesen Wert beispielsweise auf 1 festlegen, werden Ressourcenpakete jeweils in einem Cluster bereitgestellt.

      Eine vollständige Liste aller Felder, die Sie konfigurieren können, finden Sie in der Referenzdokumentation zu FleetPackage.

  2. Erstellen Sie das Flottenpaket:

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    Ersetzen Sie FLEET_PACKAGE_NAME durch einen Namen für den Roll-out des Flottenpakets.

  3. Prüfen Sie, ob das Flottenpaket erstellt wurde:

    gcloud container fleet packages list

    In der Ausgabe wird der Status des Build-Triggers aufgelistet. Nach einigen Sekunden wird das Feld MESSAGE mit einer Ausgabe wie dieser aktualisiert:

    MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:

    Sie können auf den bereitgestellten Link klicken, um die Streaming-Logs für den Cloud Build-Job aufzurufen. Es kann einige Minuten dauern, bis Cloud Build den Build-Trigger verarbeitet.

    Wenn der Build-Trigger erfolgreich ist, beginnt das Flottenpaket mit der Einführung der Kubernetes-Ressourcen in Ihrer Flotte.

  4. Wenn der Build-Trigger erfolgreich abgeschlossen wurde, sieht die Ausgabe von gcloud container fleet packages list in etwa so aus:

    NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

    Mit dem Flottenpaket werden die Kubernetes-Ressourcen in Ihrer gesamten Flotte eingeführt.

Nachdem Sie ein Flottenpaket bereitgestellt haben, werden die im Flottenpaket definierten Kubernetes-Ressourcen automatisch im neuen Cluster bereitgestellt, wenn Sie Ihrer Flotte einen neuen Cluster hinzufügen.

Flottenpaket aktualisieren

Sie können ein Flottenpaket aktualisieren, um Einstellungen oder die Ressourcen zu ändern, die durch das Flottenpaket bereitgestellt werden. Hier einige Beispiele:

  • Ändern Sie die Einführungsstrategie, indem Sie den Wert des Felds maxConcurrent ändern.
  • Sie können ein Flottenpaket vorübergehend pausieren, indem Sie state: SUSPENDED festlegen. Wenn ein Flottenpaket gesperrt wird, werden alle laufenden Rollouts fortgesetzt. Es werden keine neuen Roll-outs erstellt oder geplant, bis Sie den Status wieder in ACTIVE ändern.
  • Aktualisieren Sie die Kubernetes-Ressourcen, die vom Flottenpaket bereitgestellt werden, indem Sie das Feld tag aktualisieren, um einen anderen Git-Tag abzurufen.

So aktualisieren Sie ein Flottenpaket:

  1. Aktualisieren Sie die FleetPackage-Spezifikation mit Ihren Änderungen.

  2. Aktualisieren Sie das Flottenpaket:

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    Es kann einige Minuten dauern, bis die Änderung übernommen wird und das Roll-out für Ihre Cluster beginnt.

Roll‑outs von Flottenpaketen verwalten

Sie können den Fortschritt der Bereitstellung von Flottenpaketen überwachen und aktive Rollouts verwalten. Wenn ein Flottenpaket geändert wird, wird automatisch ein neuer Roll-out erstellt. Mit den folgenden Befehlen können Sie detaillierte Informationen zu Rollouts abrufen. Wenn Sie beispielsweise ein Bereitstellungsproblem debuggen müssen, können Sie die Rollout-Details prüfen und einen Rollout bei Bedarf pausieren oder abbrechen.

  1. Wenn Sie eine Einführung auflisten, sehen Sie den Status aller Einführungen, die mit einem Paket verknüpft sind, einschließlich Fehler, die dazu führen können, dass eine Einführung fehlschlägt. Führen Sie den folgenden Befehl aus, um Rollouts aufzulisten und ihren Status aufzurufen:

    gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

    Die Ausgabe sollte so aussehen:

    ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

  2. Wenn Sie einen Roll-out beschreiben, erhalten Sie detaillierte Informationen zu einem bestimmten Roll-out, einschließlich des Status für jeden Zielcluster und aller clusterspezifischen Fehler. Führen Sie den folgenden Befehl aus, um ein Rollout zu beschreiben:

    gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    Ersetzen Sie ROLLOUT_NAME durch den Namen des Rollouts. Sie können den vollständigen Namen des Roll-outs mit dem Befehl list im vorherigen Schritt abrufen.

    Die Ausgabe sollte so aussehen:

    CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

  3. Sie können aktive Rollouts mit den folgenden Befehlen verwalten:

    • Wenn Sie die Einführung anhalten, wird sie in den Status SUSPENDED versetzt. Laufende Paketupdates werden fortgesetzt und es werden keine weiteren Paketupdates geplant. Führen Sie den folgenden Befehl aus, um ein Rollout zu pausieren:

      gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    • Wenn Sie die Einführung fortsetzen, wird der Status der Einführung von SUSPENDED wieder in IN_PROGRESS geändert. Paketupdates werden wie geplant auf Zielclustern bereitgestellt. Führen Sie den folgenden Befehl aus, um ein Rollout fortzusetzen:

      gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    • Wenn Sie ein laufendes Roll-out abbrechen, wird es sofort beendet und in den Status ABORTED versetzt. Alle anstehenden Paketaktualisierungen, die im Rahmen des Roll-outs geplant sind, werden abgebrochen. Führen Sie den folgenden Befehl aus, um ein Rollout abzubrechen:

      gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

Labels verwenden, um in verschiedenen Clustern bereitzustellen

Labels sind Schlüssel/Wert-Paare, die Sie an Objekte anhängen. Flottenpakete unterstützen nur Labels für Flottenmitgliedschaften. GKE-Clusterlabels werden nicht unterstützt.

Sie können Labels verwenden, um ein Flottenpaket in einer Teilmenge von Clustern in Ihrer Flotte bereitzustellen.

Mitgliedschaftslabels hinzufügen

So fügst du ein Mitgliedschaftslabel hinzu:

  1. Liste der Mitgliedschaften in der Flotte abrufen:

    gcloud container fleet memberships list

  2. Fügen Sie der Mitgliedschaft ein Label hinzu:

    gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE

    Ersetzen Sie Folgendes:

    • MEMBERSHIP_NAME: der Name des Clusters, der für die Flotte registriert ist.
    • KEY und VALUE: Das Label, das der Mitgliedschaft hinzugefügt werden soll. Wenn ein Label vorhanden ist, wird sein Wert geändert. Andernfalls wird ein neues Label erstellt. Schlüssel müssen mit einem Kleinbuchstaben beginnen und dürfen nur Bindestriche (-), Unterstriche (_), Kleinbuchstaben und Ziffern enthalten. Werte dürfen nur Bindestriche (-), Unterstriche (_), Kleinbuchstaben und Zahlen enthalten.

    Wiederholen Sie diesen Befehl für jede Mitgliedschaft, der Sie ein Label hinzufügen möchten.

Auf einer Teilmenge von Clustern bereitstellen

Sie können die Bereitstellung auf eine Teilmenge von Clustern beschränken, indem Sie das Feld target.fleet.selector.matchLabels mit Ihrem Schlüssel/Wert-Paar angeben. Wenn Sie beispielsweise matchLabels als country: "us" festlegen, werden Ihre Ressourcen vom Flottenpaketdienst nur in Clustern mit dem Label country bereitgestellt, das mit "us" übereinstimmt.

Führen Sie die folgenden Schritte aus, um ein Flottenpaket auf einer Teilmenge von Clustern bereitzustellen:

  1. Erstellen oder aktualisieren Sie Ihre FleetPackage-Spezifikation mit dem Label-Selektor:

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

  2. Erstellen oder aktualisieren Sie das Flottenpaket:

    Flottenpaket erstellen

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    Flottenpaket aktualisieren

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Variantenressourcen in Clustern bereitstellen

Varianten sind verschiedene Versionen einer Ressource. Diese Ressourcen können je nach Standort, Projekt oder Name des Clusters unterschiedliche Werte haben. Sie können Variant-Ressourcen in verschiedenen Clustern bereitstellen, indem Sie die Felder variantsPattern und variantNameTemplate angeben.

Sie können Mitgliedschafts-Labels oder andere Mitgliedschafts-Metadaten wie Standort, Projekt oder Name verwenden, um Varianten abzugleichen.

So stellen Sie ein Flottenpaket mit Varianten bereit:

  1. Erstellen oder aktualisieren Sie die FleetPackage-Spezifikation mit den Variantendetails:

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE

    Ersetzen Sie Folgendes:

    • VARIANT_PATTERN: Das Muster für die Variante, z. B. "variants/*.yaml" oder "us-*".
    • VARIANT_NAME_TEMPLATE : Ein Vorlagen-String, der auf Variablen verweist, die Metadaten zur Clustermitgliedschaft enthalten, wie z. B. Standort, Projekt, Name oder Label, um den Namen der Variante für einen Zielcluster zu bestimmen. Weitere Beispiele finden Sie in der Referenzdokumentation zu FleetPackage.

  2. Erstellen oder aktualisieren Sie das Flottenpaket:

    Flottenpaket erstellen

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    Flottenpaket aktualisieren

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Flottenpaket löschen

Wenn Sie ein Flottenpaket löschen, werden auch die folgenden Ressourcen gelöscht:

  • Die in Ihren Clustern bereitgestellten Kubernetes-Ressourcen
  • Der Roll‑out-Verlauf des Flottenpakets

Führen Sie den folgenden Befehl aus, um ein Flottenpaket zu löschen:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Fehlerbehebung

Methoden zur Diagnose und Behebung von Fehlern im Zusammenhang mit Cloud Build finden Sie unter Build-Fehler beheben.

Nächste Schritte