Déployer des packages de parc

Cette page explique comment utiliser les packages de parc Config Sync pour déployer des ressources Kubernetes sur des clusters enregistrés dans un parc. Après avoir créé et déployé un package de parc, lorsque vous ajoutez un cluster à votre parc, le package de parc déploie automatiquement les fichiers de configuration Kubernetes dans le dépôt Git sur le nouveau cluster.

FleetPackage est une API déclarative permettant de déployer des fichiers manifestes Kubernetes bruts sur un parc de clusters. Toutes les ressources Kubernetes que vous souhaitez déployer avec un package de parc doivent être déjà hydratées (WET).

Avant de commencer

  1. Créez un dépôt Git contenant les ressources Kubernetes que vous souhaitez déployer dans un parc ou assurez-vous d'y avoir accès.

  2. Installez et initialisez la Google Cloud CLI, qui fournit les commandes gcloud et nomos. Si vous utilisez Cloud Shell, Google Cloud CLI est préinstallé. Si vous avez déjà installé Google Cloud CLI, obtenez la dernière version en exécutant la commande gcloud components update.

  3. Activez l'API Config Sync (anthosconfigmanagement) et l'API ConfigDelivery :

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

  4. Définissez un emplacement par défaut :

    gcloud config set config_delivery/location us-central1

  5. Définissez un projet par défaut :

    gcloud config set project PROJECT_ID

    Remplacez PROJECT_ID par l'ID du projet hôte du parc.

  6. Assurez-vous que vos clusters sont enregistrés dans un parc.

  7. Utilisez les dépôts Cloud Build pour créer une connexion à un fournisseur compatible comme GitHub ou GitLab. Lorsque vous utilisez un package de parc, vous ne devez configurer Cloud Build qu'une seule fois par dépôt que vous souhaitez synchroniser.

Vérifier la configuration requise pour les clusters

Avant d'installer Config Sync sur votre cluster, consultez les recommandations et exigences concernant la configuration du cluster.

Préparer votre environnement

Pour préparer votre environnement aux packages de parc Config Sync, accordez les rôles IAM requis à l'utilisateur qui enregistre le cluster.

Installer Config Sync

Vous pouvez installer Config Sync avec la console Google Cloud ou Google Cloud CLI.

Console

Pour installer Config Sync, tous les clusters doivent être enregistrés dans un parc. Lorsque vous installez Config Sync dans la console Google Cloud , la sélection de clusters individuels enregistre automatiquement ces clusters dans votre parc.

  1. Dans la console Google Cloud , accédez à la page Configuration sous la section Fonctionnalités.

    Accéder à la page "Configuration"

  2. Cliquez sur Installer Config Sync.

  3. Sous Options d'installation, sélectionnez Installer Config Sync sur l'ensemble du parc (recommandé).

  4. Cliquez sur Installer Config Sync. Dans l'onglet Paramètres, après quelques minutes, Activé devrait s'afficher dans la colonne État pour les clusters de votre parc.

gcloud

  1. Activez la fonctionnalité de parc ConfigManagement :

    gcloud beta container fleet config-management enable

  2. Pour activer Config Sync, créez un fichier nommé apply-spec.yaml avec le contenu suivant :

    applySpecVersion: 1
spec:
  configSync:
    enabled: true

  3. Appliquez le fichier apply-spec.yaml :

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

    Remplacez MEMBERSHIP_NAME par le nom d'appartenance au parc que vous avez choisi lors de l'enregistrement de votre cluster. Pour trouver le nom d'appartenance, exécutez la commande gcloud container fleet memberships list.

Créer un compte de service pour Cloud Build

Les packages de parc utilisent Cloud Build pour extraire les ressources Kubernetes de votre dépôt Git et les déployer sur vos clusters. Cloud Build nécessite un compte de service disposant des autorisations nécessaires pour exécuter ce job. Pour créer le compte de service et accorder les autorisations requises, procédez comme suit :

  1. Créez le compte de service :

    gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"

    Remplacez SERVICE_ACCOUNT_NAME par le nom que vous souhaitez donner au compte de service. Le nom doit être un ID alphanumérique de 6 à 30 caractères, par exemple my-service-account. Une fois le compte de service créé, vous ne pouvez pas en modifier le nom.

  2. Ajoutez une liaison de stratégie IAM pour le rôle "Éditeur de groupes de ressources" :

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

    Si vous y êtes invité, sélectionnez None comme condition pour le règlement.

  3. Ajoutez une liaison de stratégie IAM pour le rôle Rédacteur de journaux :

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

    Si vous y êtes invité, sélectionnez None comme condition pour le règlement.

  4. Ajoutez une liaison de stratégie IAM pour le rôle Rédacteur Artifact Registry :

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

    Si vous y êtes invité, sélectionnez None comme condition pour le règlement.

Créer un package de parc

Pour créer un package de parc, vous définissez une spécification FleetPackage qui pointe vers le dépôt contenant vos ressources Kubernetes que vous avez connectées à Cloud Build. Vous appliquez ensuite FleetPackage, qui récupère les ressources à partir de Git et les déploie dans le parc.

  1. Créez un fichier nommé fleetpackage-spec.yaml avec le contenu suivant :

    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

    Remplacez les éléments suivants :

    • CONNECTION_NAME : nom que vous avez choisi lorsque vous avez associé votre hôte Git à Cloud Build. Vous pouvez afficher toutes les connexions Cloud Build de votre projet en exécutant gcloud builds connections list ou en ouvrant la page Dépôts dans la console Google Cloud  :

      Ouvrir la page "Dépôts"

    • REPOSITORY_NAME : le nom de votre dépôt. Cette valeur doit être identique à celle saisie lors de la configuration de votre connexion Cloud Build.

    • TAG : tag Git de votre dépôt. Le format doit être la version sémantique complète avec le numéro de version majeure, mineure et de correctif. Par exemple, v1.0.0 est un tag valide, tandis que v1 ou v1.0 ne le sont pas.

    • CONFIG_FILE_PATH : chemin d'accès à vos ressources Kubernetes dans le dépôt. Si vos fichiers se trouvent à la racine du dépôt, vous pouvez omettre ce champ.

    • MAX_CLUSTERS : nombre maximal de clusters sur lesquels déployer des ressources Kubernetes à la fois. Par exemple, si vous définissez cette valeur sur 1, les bundles de ressources sont déployés sur un cluster à la fois.

      Pour obtenir la liste complète de tous les champs que vous pouvez configurer, consultez la documentation de référence sur FleetPackage.

  2. Créez le package de parc :

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

    Remplacez FLEET_PACKAGE_NAME par le nom du déploiement de package de votre parc.

  3. Vérifiez que le package de parc a été créé :

    gcloud container fleet packages list

    Le résultat liste l'état du déclencheur de compilation. Après quelques secondes, le champ MESSAGE est mis à jour avec un résultat semblable à celui-ci :

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

    Vous pouvez cliquer sur le lien fourni pour afficher les journaux de flux de la tâche Cloud Build. Cloud Build peut mettre quelques minutes à traiter le déclencheur de compilation.

    Si le déclencheur de compilation réussit, le package de parc commence à déployer les ressources Kubernetes dans votre parc.

  4. Lorsque le déclencheur de compilation se termine correctement, le résultat de gcloud container fleet packages list est semblable à ce qui suit :

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

    Le package de parc commence à déployer les ressources Kubernetes dans votre parc.

Maintenant que vous avez déployé un package de parc, lorsque vous ajoutez un cluster à votre parc, les ressources Kubernetes définies dans le package de parc sont automatiquement déployées sur le nouveau cluster.

Mettre à jour un package de parc

Vous pouvez mettre à jour un package de parc pour modifier les paramètres ou les ressources qu'il déploie. Voici quelques exemples :

  • Modifiez la stratégie de déploiement en changeant la valeur du champ maxConcurrent.
  • Mettez temporairement en pause un package de flotte en définissant state: SUSPENDED. Lorsqu'un package de parc est suspendu, les déploiements en cours se poursuivent. Aucun déploiement n'est créé ni planifié tant que vous n'avez pas rétabli l'état ACTIVE.
  • Mettez à jour les ressources Kubernetes déployées par le package de parc en modifiant le champ tag pour extraire les données à partir d'un autre tag Git.

Pour mettre à jour un package de parc, procédez comme suit :

  1. Mettez à jour votre spécification FleetPackage avec vos modifications.

  2. Mettez à jour le package de parc :

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

    Il peut s'écouler quelques minutes avant que la modification ne soit prise en compte et ne commence à être déployée sur vos clusters.

Gérer les déploiements de packages de parc

Vous pouvez surveiller la progression des déploiements de packages de flotte et gérer les déploiements actifs. Lorsqu'un package de flotte est modifié, un nouveau déploiement est automatiquement créé. Les commandes suivantes vous aident à obtenir des informations détaillées sur les déploiements. Par exemple, si vous devez déboguer un problème de déploiement, vous pouvez examiner les détails du déploiement, et le suspendre ou l'annuler si nécessaire.

  1. Lister un déploiement vous permet de voir l'état de tous les déploiements liés à un package, y compris les erreurs qui peuvent entraîner l'échec d'un déploiement. Pour lister les déploiements et afficher leur état, exécutez la commande suivante :

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

    Le résultat se présente comme suit :

    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. La description d'un déploiement fournit des informations détaillées sur un déploiement spécifique, y compris l'état de chaque cluster cible et les éventuelles erreurs spécifiques à un cluster. Pour décrire un déploiement, exécutez la commande suivante :

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

    Remplacez ROLLOUT_NAME par le nom de votre déploiement. Vous pouvez obtenir le nom complet du déploiement à partir de la commande list de l'étape précédente.

    Le résultat se présente comme suit :

    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. Vous pouvez gérer les déploiements actifs en exécutant les commandes suivantes :

    • La suspension d'un déploiement en cours le fait passer à l'état SUSPENDED. Les mises à jour de packages en cours se poursuivent, et aucune autre mise à jour de package n'est planifiée. Pour suspendre un déploiement, exécutez la commande suivante :

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

    • La reprise d'un déploiement SUSPENDED le fait repasser à l'état IN_PROGRESS. Les mises à jour des packages sont déployées sur les clusters cibles comme prévu. Pour reprendre un déploiement, exécutez la commande suivante :

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

    • L'annulation d'un déploiement en cours met immédiatement fin au déploiement et le place dans l'état ABORTED. Toutes les mises à jour de packages en attente prévues dans le déploiement sont annulées. Pour annuler un déploiement, exécutez la commande suivante :

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

Utiliser des libellés pour déployer des applications sur différents clusters

Les libellés sont des paires clé/valeur que vous associez à des objets. Les packages de parc n'acceptent que les libellés d'appartenance à un parc. Les libellés de cluster GKE ne sont pas acceptés.

Vous pouvez utiliser des étiquettes pour déployer un package de parc sur un sous-ensemble de clusters de votre parc.

Ajouter des libellés de lien familial

Pour ajouter un badge de membre :

  1. Obtenez la liste des appartenances au parc :

    gcloud container fleet memberships list

  2. Ajoutez un libellé à l'abonnement :

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

    Remplacez les éléments suivants :

    • MEMBERSHIP_NAME : nom du cluster enregistré dans le parc.
    • KEY et VALUE : libellé à ajouter à l'abonnement. Si un libellé existe, sa valeur est modifiée. Sinon, un libellé est créé. Les clés doivent commencer par une lettre minuscule et ne contenir que des tirets (-), des traits de soulignement (_), des minuscules et des chiffres. Les valeurs ne doivent contenir que des tirets (-), des traits de soulignement (_), des minuscules et des chiffres.

    Répétez cette commande pour chaque abonnement auquel vous souhaitez ajouter un libellé.

Déployer sur un sous-ensemble de clusters

Vous pouvez déployer sur un sous-ensemble de clusters en spécifiant le champ target.fleet.selector.matchLabels avec votre paire clé/valeur. Par exemple, si vous définissez matchLabels sur country: "us", le service de package de parc déploie vos ressources uniquement sur les clusters dont le libellé country correspond à "us".

Pour déployer un package de parc sur un sous-ensemble de clusters, procédez comme suit :

  1. Créez ou mettez à jour votre spécification FleetPackage avec le sélecteur de libellés :

    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. Créez ou mettez à jour le package de parc :

    Créer un package de parc

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

    Mettre à jour un package de parc

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

Déployer des ressources de variantes sur des clusters

Les variantes sont différentes versions d'une ressource. Ces ressources peuvent avoir des valeurs différentes selon l'emplacement, le projet ou le nom du cluster. Vous pouvez déployer des ressources de variantes sur différents clusters en spécifiant les champs variantsPattern et variantNameTemplate.

Vous pouvez utiliser des libellés de membres ou d'autres métadonnées de membres (comme le lieu, le projet ou le nom) pour faire correspondre les variantes.

Pour déployer un package de parc avec des variantes, procédez comme suit :

  1. Créez ou mettez à jour votre spécification FleetPackage avec les informations sur les variantes :

    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

    Remplacez les éléments suivants :

    • VARIANT_PATTERN : modèle de variante, par exemple "variants/*.yaml" ou "us-*".
    • VARIANT_NAME_TEMPLATE  : chaîne de modèle qui fait référence à des variables contenant des métadonnées d'appartenance à un cluster, telles que l'emplacement, le projet, le nom ou l'étiquette, servant à déterminer le nom de la variante pour un cluster cible. Pour obtenir d'autres exemples, consultez la documentation de référence de FleetPackage.

  2. Créez ou mettez à jour le package de parc :

    Créer un package de parc

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

    Mettre à jour un package de parc

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

Supprimer un package de parc

La suppression d'un package de parc entraîne également la suppression des ressources suivantes :

  • Ressources Kubernetes déployées sur vos clusters
  • Historique de déploiement du package de parc

Pour supprimer un package de parc, exécutez la commande suivante :

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Résoudre les problèmes

Pour connaître les méthodes de diagnostic et de résolution des erreurs liées à Cloud Build, consultez Résoudre les erreurs de compilation.

Étapes suivantes