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.

Un FleetPackage est une API déclarative permettant de déployer des fichiers manifestes bruts Kubernetes 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 sur un parc ou assurez-vous d'y avoir accès.
Installez et initialisez 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 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 : Le seul emplacement 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 de parc.
Assurez-vous que vos clusters sont enregistrés dans un parc.
Utilisez des dépôts Cloud Build pour créer une connexion à un fournisseur compatible tel que GitHub ou GitLab. Lorsque vous utilisez un package de parc, vous n'avez besoin de 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 la configuration requise pour les clusters

Avant d'installer Config Sync sur votre cluster, consultez les recommandations et exigences de configuration des clusters.

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 Google Cloud console 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 Google Cloud console, la sélection de clusters individuels enregistre automatiquement ces clusters dans votre parc.

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

Accéder à la page "Configuration"

Cliquez sur Install Config Sync.
Sous Installation options (Options d'installation), sélectionnez Install Config Sync on entire fleet (recommended) (Installer Config Sync sur l'ensemble du parc (recommandé)).
Cliquez sur Install Config Sync (Installer Config Sync). Dans l'onglet Settings (Paramètres), après quelques minutes, Enabled (Activé) devrait s'afficher dans la colonne Status (É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 apply-spec.yaml fichier :
```
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 gcloud container fleet memberships list commande.

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 cette tâche. 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 groupe 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 stratégie.

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 stratégie.

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 stratégie.

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é à Cloud Build. Vous appliquez ensuite le FleetPackage, qui extrait les ressources de Git et les déploie sur 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 connecté 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 Repositories (Dépôts) dans la Google Cloud console :
  
  Ouvrir la page "Dépôts"
- REPOSITORY_NAME : nom de votre dépôt. Il doit être identique à la valeur 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 en même temps. Par exemple, si vous définissez cette valeur sur 1, les groupes 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 FleetPackage documentation de référence.

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 de votre déploiement de package de parc.

Vérifiez que le package de parc a été créé :
```
gcloud container fleet packages list
```
Le résultat indique 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 streaming de la tâche Cloud Build. Le traitement du déclencheur de compilation par Cloud Build peut prendre quelques minutes.

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

Une fois le déclencheur de compilation terminé, 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 des paramètres ou les ressources déployées par le package de parc, comme dans les exemples suivants :

Modifiez la stratégie de déploiement en modifiant la valeur du champ maxConcurrent.
Mettez en pause temporairement un package de parc en définissant state: SUSPENDED. Lorsqu'un package de parc est suspendu, tous les déploiements en cours se poursuivent. Aucun nouveau déploiement n'est créé ni planifié tant que vous ne rétablissez pas l'état ACTIVE.
Mettez à jour les ressources Kubernetes déployées par le package de parc en modifiant le tag champ pour extraire 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
```
La prise en compte de la modification et son déploiement sur vos clusters peuvent prendre quelques minutes.

Inspecter les groupes de ressources et les versions

Lorsque vous créez ou mettez à jour un package de parc en fonction de votre dépôt Git, l' FleetPackages API crée automatiquement des ressources groupe de ressources et version. 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 groupes de ressources et les versions, utilisez une ou plusieurs des commandes suivantes :

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

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

Répertoriez toutes les versions associées à un groupe 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 groupe 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 groupe de ressources est automatiquement précédé de flpkg-rb-.
RELEASE_NAME : nom de la version à partir du 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 mettre en pause ou l'annuler si nécessaire.

La liste des déploiements 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 vous fournit des informations détaillées sur un déploiement spécifique y compris l'état de chaque cluster cible et les 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 met un déploiement en cours d'exécution à l'état SUSPENDED. Toutes les mises à jour de packages en cours se poursuivent, et aucune autre mise à jour de packages 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 rétablit l'état IN_PROGRESS d'un déploiement SUSPENDED. Les mises à jour de 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 met à 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, soit en les déployant sur un sous-ensemble de clusters en spécifiant des libellés, soit en utilisant la correspondance de modèles de variantes 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 à l'aide de 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 déploie vos ressources uniquement sur les clusters dont le libellé country correspond à "us".

Les packages de parc n'acceptent que les libellés d'appartenance au parc. Les libellés de cluster GKE ne sont pas acceptés.

(Facultatif) Si vous ne disposez pas encore des 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'appartenance :
```
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'appartenance. Si un libellé existe, sa valeur est modifiée. Sinon, un nouveau 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 appartenance à laquelle 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 variante 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 génération des variantes à partir de la structure de votre dépôt, consultez la section Génération des variantes.

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

Créez ou mettez à jour votre FleetPackage spécification 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 acceptés, consultez la section Correspondance variantsPattern matching.
- 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 mappés sur le même nom (par exemple, app1/deploy.yaml et app2/deploy.yaml, tous deux résolvant en 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 :

Les ressources Kubernetes déployées sur vos clusters
L'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 la section Résoudre les erreurs de compilation.

Étape suivante

Consultez la page de référence des 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 la configuration requise pour les 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 groupes 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 variante 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

Étape suivante

Déployer des packages de parc