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 du 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

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.
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é la Google Cloud CLI, obtenez la dernière version en exécutant la commande gcloud components update.

Remarque : Pour les installations de gcloud CLI existantes, veillez à définir les propriétés compute/region et compute/zone. En définissant des emplacements par défaut, vous pouvez éviter les erreurs gcloud CLI telles que celle-ci : One of [--zone, --region] must be supplied: Please specify location.

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

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

Définissez un emplacement par défaut :
```
gcloud config set config_delivery/location us-central1
```
Remarque : La seule position disponible pour l'API ConfigDelivery est us-central1.
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.
Assurez-vous que vos clusters sont enregistrés dans un parc.
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.

Important : Votre connexion Cloud Build doit se trouver dans us-central1, car la connexion Git et FleetPackage doivent se trouver dans la même région. L'API ConfigDelivery n'est disponible que dans us-central1.

Examiner les exigences des 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.

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

Accéder à la page "Configuration"

Cliquez sur Installer Config Sync.
Sous Options d'installation, sélectionnez Installer Config Sync sur l'ensemble du parc (recommandé).
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

Activez la fonctionnalité de parc ConfigManagement :

gcloud beta container fleet config-management enable

Pour activer Config Sync, créez un fichier nommé apply-spec.yaml avec le contenu suivant :
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
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 de l'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 :

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.

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 la règle.

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 la règle.

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 la règle.

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.

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
    # Match all files and directories to generate variants
    variantsPattern: "*"
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
variantSelector:
  variantNameTemplate: "VARIANT_NAME"
# 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.
- VARIANT_NAME : variante à déployer sur vos clusters. Le nom doit correspondre à une variante de votre dépôt (nom de fichier sans extension ou nom de répertoire). Par exemple, si vous avez un fichier nommé prod.yaml, définissez ce champ sur prod. Pour utiliser le comportement par défaut (par exemple, pour déployer la même configuration sur tous les clusters d'un parc), définissez ce champ sur default et assurez-vous que votre dépôt contient un fichier nommé default.yaml.
  
  Pour obtenir la liste complète de tous les champs que vous pouvez configurer, consultez la documentation de référence sur FleetPackage.

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.

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 à ce qui suit :
```
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.

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 :

Mettez à jour votre spécification FleetPackage avec vos modifications.
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.

Inspecter les packages de ressources et les versions

Lorsque vous créez ou mettez à jour un package de parc basé sur votre dépôt Git, l'API FleetPackages crée automatiquement des ressources resource bundle et release. L'inspection de ces ressources est utile pour résoudre les problèmes, en particulier si vous devez vérifier les variantes générées à partir de votre dépôt.

Pour inspecter les bundles et les versions de ressources, utilisez une ou plusieurs des commandes suivantes :

Affichez des informations détaillées sur un bundle de ressources spécifique :

gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME

Répertoriez toutes les versions associées à un bundle de ressources :

gcloud container fleet packages resource-bundles releases list \
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

Affichez des informations détaillées sur une version spécifique, y compris le bundle de ressources qu'elle utilise. Cette commande est particulièrement utile pour déboguer les problèmes liés aux variantes, car elle vous permet d'inspecter exactement les variantes incluses dans une version spécifique :
```
gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
```

Remplacez les éléments suivants :

FLEET_PACKAGE_NAME : nom de votre package de parc. Le nom du bundle de ressources est automatiquement précédé de flpkg-rb-.
RELEASE_NAME : nom de la version à partir de la résultat de la commande list.

Gérer les déploiements de packages de parc

Vous pouvez surveiller la progression des déploiements de packages de parc et gérer les déploiements actifs. Lorsqu'un package de parc 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.

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

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

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 cadre du 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
```

Stratégies de déploiement

Vous pouvez déployer des ressources de différentes manières : en les déployant sur un sous-ensemble de clusters en spécifiant des libellés, ou en utilisant des variantes de correspondance de modèle pour déployer différentes ressources. Vous pouvez combiner les deux stratégies pour mieux contrôler les ressources déployées sur différents clusters.

Déployer sur un sous-ensemble de clusters

Vous pouvez déployer la même ressource sur un sous-ensemble de clusters en utilisant des libellés et en spécifiant le champ target.fleet.selector.matchLabels avec vos libellés (paire clé-valeur). Par exemple, si vous définissez matchLabels sur country: "us", le service de package de parc informatique ne déploie vos ressources que sur les clusters dont le libellé country correspond à "us".

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.

(Facultatif) Si vous n'avez pas encore de libellés que vous souhaitez utiliser, ajoutez-les en procédant comme suit :
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é.

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

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

Vous pouvez déployer des configurations uniques sur différents clusters (par exemple, dev par rapport à prod) en ajoutant des définitions de variantes à votre package de parc.

Pour obtenir une présentation conceptuelle de la façon dont les variantes sont générées à partir de la structure de votre dépôt, consultez Comment les variantes sont générées.

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

Créez ou mettez à jour votre spécification FleetPackage pour inclure les champs variantsPattern et variantNameTemplate :
```
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 glob permettant de générer des variantes à partir de votre dépôt, tel que * (correspond à tous les fichiers et répertoires) ou *.yaml (correspond uniquement aux fichiers). Pour en savoir plus sur les modèles compatibles, consultez Correspondance variantsPattern.
- VARIANT_NAME_TEMPLATE : chaîne ou modèle permettant de sélectionner une variante pour chaque cluster. Vous pouvez utiliser des variables de métadonnées telles que ${membership.labels['env']} ou ${membership.location}.
Remarque : Assurez-vous que votre variantsPattern génère des noms de variantes uniques. Si deux fichiers sont associés au même nom (par exemple, app1/deploy.yaml et app2/deploy.yaml, qui renvoient tous les deux à deploy), le déploiement peut échouer en raison d'un conflit de noms.

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

Consultez la page de référence sur les champs FleetPackage.

Déployer des packages de parc Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Examiner les exigences des clusters

Préparer votre environnement

Installer Config Sync

Console

gcloud

Créer un compte de service pour Cloud Build

Créer un package de parc

Mettre à jour un package de parc

Inspecter les packages de ressources et les versions

Gérer les déploiements de packages de parc

Stratégies de déploiement

Déployer sur un sous-ensemble de clusters

Créer un package de parc

Mettre à jour un package de parc

Déployer des ressources de variantes sur des clusters

Créer un package de parc

Mettre à jour un package de parc

Supprimer un package de parc

Résoudre les problèmes

Étapes suivantes

Déployer des packages de parc