Séquencer le déploiement des mises à niveau de clusters avec des étapes personnalisées

Ce document explique comment gérer les mises à niveau de clusters Google Kubernetes Engine (GKE) qui utilisent le séquençage du déploiement avec des étapes personnalisées. Pour créer une séquence de déploiement, vous devez utiliser des groupes de clusters organisés en parcs et, éventuellement, des sous-ensembles de clusters de ces parcs. Vous pouvez choisir le temps de stabilisation des tests souhaité une fois les mises à niveau des clusters terminées dans un groupe (30 jours maximum). Vous pouvez inclure à la fois des clusters Autopilot et Standard. Pour en savoir plus sur le fonctionnement de cette fonctionnalité, consultez À propos du séquençage du déploiement avec des étapes personnalisées.

Si vous gérez des déploiements sur plusieurs parcs, nous vous recommandons d'utiliser un projet dédié pour héberger vos objets RolloutSequence. Ce projet sert de parent et de coordinateur pour les déploiements de la séquence. Ce projet ne fait généralement pas partie de la séquence, c'est-à-dire qu'il ne contient pas de flottes ni de clusters qui en font partie.

Avant de commencer

  • Installez la Google Cloud CLI. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante : 

    gcloud init

    Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  • Assurez-vous de disposer de clusters Autopilot ou Standard existants. Pour créer un cluster, consultez la page Créer un cluster Autopilot.

  • (Facultatif) Si vous n'avez pas encore de projet Google Cloud dédié pour héberger votre configurationRolloutSequence, créez-en un à l'aide de la console Google Cloud ou d'une autre méthode.

  • Assurez-vous d'avoir activé les API requises pour les parcs. Ces API doivent être activées dans vos projets hôtes de parc pour permettre la création de n'importe quel type de séquence de déploiement. Pour votre projet hôte de séquence de déploiement, activez l'API gkehub.googleapis.com.

Rôles requis

Pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Pour créer ou modifier une séquence de déploiement, vous devez disposer du rôle IAM Éditeur de parc (roles/gkehub.editor) dans chaque projet hôte de parc de la séquence de déploiement et dans votre projet hôte de séquence de déploiement. Ce rôle fournit les autorisations suivantes :

  • gkehub.rolloutsequences.create
  • gkehub.rolloutsequences.get
  • gkehub.rolloutsequences.list
  • gkehub.rolloutsequences.update
  • gkehub.rolloutsequences.delete
  • gkehub.fleet.get

Ces autorisations vous permettent de créer, d'accéder et de modifier des objets RolloutSequence, et d'utiliser des flottes dans la séquence de déploiement.

Si vous devez enregistrer ou annuler l'enregistrement de clusters dans un parc, vous devez disposer de toutes les autorisations suivantes :

Pour en savoir plus sur les rôles IAM avec le moins de privilèges requis pour différentes tâches, consultez Obtenir des suggestions de rôles prédéfinis avec l'assistance Gemini.

Configurer une séquence de déploiement

Pour créer une séquence de déploiement, vos clusters doivent être organisés en groupes de parcs. Vous pouvez également créer des étapes précises qui peuvent cibler des sous-ensembles spécifiques de clusters au sein d'un parc à l'aide d'étiquettes Kubernetes. Pour savoir comment organiser vos clusters, consultez l'exemple de banque communautaire. Après avoir organisé les clusters en groupes et les avoir éventuellement libellés, vous créez une séquence de déploiement en définissant la liste ordonnée des étapes et la durée de stabilisation pour chaque groupe.

Organiser les clusters en parcs

Dans une séquence de déploiement, nous vous recommandons d'enregistrer tous les clusters dans le même version disponible. Si les clusters ne sont pas enregistrés dans le même canal, GKE sélectionne une version du canal le plus conservateur de la séquence. Par exemple, si des clusters sont enregistrés dans les canaux Stable et Standard, GKE choisit la version du canal Stable. Nous vous recommandons également que tous les clusters exécutent la même version mineure pour pouvoir bénéficier de la même version cible de mise à niveau automatique.

Si vous avez déjà organisé vos clusters en parcs, vous pouvez ignorer les étapes suivantes et passer à la section Créer des sous-ensembles de clusters.

  1. Regroupez vos clusters dans des parcs. Vous pouvez organiser vos clusters par environnements de déploiement tels que "Test", "Préproduction" et "Production" (recommandé).
  2. Enregistrez chaque cluster dans un parc en fonction du regroupement choisi.

Créer des sous-ensembles de clusters (facultatif)

Pour qu'une étape de votre séquence de déploiement cible des clusters spécifiques, vous devez les étiqueter.

Par exemple, pour tester une nouvelle version sur un petit sous-ensemble de clusters avant un déploiement complet, vous pouvez appliquer un libellé canary à ces clusters. Pour ajouter le libellé canary avec la valeur true à un cluster à l'aide de Google Cloud CLI, exécutez la commande suivante :

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

Remplacez les éléments suivants :

L'option --update-labels=canary=true demande à GKE d'appliquer le libellé canary au cluster .

Pour savoir comment ajouter un libellé à un cluster, consultez Ajouter ou mettre à jour des libellés pour des clusters existants.

Créer une séquence de déploiement avec des étapes personnalisées

Une séquence de déploiement définit l'ordre des mises à niveau à l'aide d'étapes. Pour créer une séquence de déploiement, vous devez d'abord créer un fichier YAML qui définit les étapes, puis créer un RolloutSequence.

Pour s'assurer que la séquence capture tous les clusters, chaque parc doit inclure une étape générique (une étape sans sélecteur de libellé). Cette étape générique capture tous les clusters restants que GKE n'a pas sélectionnés lors des étapes précédentes. Si vous attribuez un même cluster à plusieurs étapes d'un même RolloutSequence, pour résoudre les conflits, GKE attribue implicitement le cluster uniquement à l'étape la plus ancienne.

L'exemple de configuration suivant crée trois étapes :

  • La première étape cible tous les clusters du parc dev. Une fois la mise à niveau terminée, une période de stabilisation de sept jours (valeur de 604800 secondes) est appliquée.
  • La deuxième étape cible les clusters du parc prod qui portent le libellé canary=true. Une fois la mise à niveau terminée, un temps de stabilisation de sept jours est nécessaire.
  • La troisième étape cible les clusters restants du parc prod. Une fois la mise à niveau terminée, une période de stabilisation de sept jours est nécessaire.

  1. Enregistrez le manifeste suivant sous le nom rollout-sequence.yaml :

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: resource.labels.canary=='true'
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

    Veuillez noter les points suivants :

    • stage : inclut un parc ou un sous-ensemble de clusters au sein d'un parc. Les clusters des étapes précédentes doivent être entièrement mis à niveau et testés avant que la séquence ne passe à l'étape suivante. Toutefois, si la mise à niveau d'un cluster n'est pas terminée 30 jours après le début du processus de mise à niveau, GKE lance la période de stabilisation.
    • fleet-projects : liste des parcs à partir desquels sélectionner des clusters pour cette étape. Vous ne pouvez faire référence qu'à une seule flotte par étape. Un parc est identifié par le projet dans lequel il est hébergé. Ce projet peut être différent de celui dans lequel se trouvent les clusters, si le parc contient des appartenances inter-projets. Le format permettant de spécifier un projet de parc est projects/PROJECT_ID.
    • label-selector (facultatif) : sélectionne un sous-ensemble de clusters à partir des flottes spécifiées. Ce champ utilise la syntaxe Common Expression Language (CEL) et doit commencer par resource.labels.
    • soak-duration : délai d'attente après la mise à niveau de tous les clusters d'une étape précédente avant de passer à l'étape suivante. Exprimé en secondes.

  2. Pour créer la séquence de déploiement que vous avez définie dans le fichier manifeste rollout-sequence.yaml, exécutez la commande suivante :

    gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
    --display-name=DISPLAY_NAME \
    --stage-config=rollout-sequence.yaml

    Remplacez les éléments suivants :

    • ROLLOUT_SEQUENCE_NAME : identifiant immuable conforme aux spécifications RFC-1034, par exemple test-rollout-sequence.
    • DISPLAY_NAME : chaîne lisible pour votre séquence de déploiement.

Vérifier l'état d'un déploiement

Une fois que vous avez configuré une séquence de déploiement, le système crée automatiquement des objets Rollout pour gérer les mises à niveau. Vous pouvez observer et suivre la progression de ces objets à l'aide des commandes Google Cloud CLI.

Lister les déploiements

Pour lister tous les déploiements actifs et historiques dans le projet hôte de votre séquence de déploiement, exécutez la commande suivante :

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Remplacez HOST_PROJECT_ID par l'ID de votre projet hôte de séquence de déploiement.

Vous pouvez omettre l'option --project=HOST_PROJECT_ID si vous vous trouvez déjà dans le projet où votre séquence de déploiement est hébergée.

Le résultat ressemble à ce qui suit :

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

Dans le résultat précédent, les noms de déploiement qui contiennent kcp font référence aux mises à niveau du plan de contrôle, et ceux qui contiennent node font référence aux mises à niveau des nœuds. Le segment du nom du déploiement après kcp ou node est dérivé de la version GKE.

Décrire un déploiement

Pour obtenir des informations détaillées sur un déploiement particulier, y compris la version cible, l'état et les clusters qui ont été mis à niveau, utilisez la commande describe avec l'ID de déploiement que vous avez obtenu à partir de la commande précédente :

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

Remplacez les éléments suivants :

  • ROLLOUT_ID : ID du déploiement que vous avez obtenu lorsque vous avez listé les déploiements.
  • HOST_PROJECT_ID : ID du projet dans lequel votre séquence de déploiement est hébergée.

Exemple :

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

Le résultat ressemble à ce qui suit :

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

Informations sur l'état d'un déploiement

Lorsque vous décrivez un déploiement, les champs stages et membershipStates de la sortie indiquent respectivement l'état d'avancement de chaque étape et de chaque cluster au sein de cette étape.

Le tableau suivant répertorie les états potentiels d'une étape :

État Description
PENDING La mise à niveau n'a pas encore commencé pour cette étape.
RUNNING La mise à niveau est en cours pour cette étape. Si vous avez configuré un intervalle de maintenance pour les clusters de l'étape, GKE attend que l'intervalle s'ouvre avant de mettre à niveau les clusters.
SOAKING Tous les clusters de cette étape ont terminé leur mise à niveau et la période de stabilisation configurée est en cours.
FORCED_SOAKING La mise à niveau a pris plus de temps (30 jours). GKE a donc forcé le démarrage de la phase de stabilisation. La mise à niveau se poursuit sur les clusters restants.
COMPLETED La phase de trempage est terminée et le déploiement passe à l'étape suivante.

Le tableau suivant liste les états potentiels d'un cluster dans une séquence :

État Description
PENDING La mise à niveau est en attente sur ce cluster.
INELIGIBLE Ce cluster n'est pas éligible à la mise à niveau, probablement en raison d'un écart de version. Le motif d'inéligibilité est indiqué dans le résultat.
RUNNING La mise à niveau est en cours sur ce cluster.
SUCCEEDED La mise à niveau a bien été effectuée sur ce cluster.
FAILED La mise à niveau a échoué sur ce cluster. Les cibles ayant échoué sont réessayées indéfiniment tant que leur étape est active (à l'état RUNNING ou FORCED_SOAKING).

Gérer une séquence de déploiement

Vous pouvez contrôler les mises à niveau automatiques des clusters avec le séquençage du déploiement de plusieurs manières, comme expliqué dans les sections suivantes.

Lister vos séquences de déploiement

Pour lister toutes les séquences de déploiement dans votre projet hôte, exécutez la commande suivante :

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Remplacez HOST_PROJECT_ID par l'ID de votre projet hôte de séquence de déploiement.

Décrire une séquence de déploiement

Pour afficher les détails d'une séquence de déploiement spécifique, exécutez la commande suivante :

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Remplacez les éléments suivants :

  • ROLLOUT_SEQUENCE_NAME : nom de la séquence de déploiement.
  • HOST_PROJECT_ID : ID de votre projet hôte de séquence de déploiement.

Le résultat ressemble à ce qui suit :

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

Modifier une séquence de déploiement

Vous pouvez modifier une séquence de déploiement existante en modifiant le fichier de configuration YAML dans lequel vous l'avez définie. Par exemple, vous pouvez modifier le temps d'imprégnation d'une étape ou modifier l'étape pour changer l'ordre des mises à niveau. Après avoir modifié le fichier, appliquez les modifications.

Par exemple, si vous avez défini la séquence de déploiement d'origine dans un fichier nommé rollout-sequence.yaml, modifiez le fichier selon vos besoins. Exécutez ensuite la commande suivante :

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

Supprimer une séquence de déploiement

Pour supprimer une séquence de déploiement, exécutez la commande suivante :

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Remplacez les éléments suivants :

  • ROLLOUT_SEQUENCE_NAME par le nom de la séquence de déploiement.
  • Remplacez HOST_PROJECT_ID par l'ID de votre projet hôte de séquence de déploiement.

Lorsque vous supprimez une séquence de déploiement, tous les déploiements en cours pour cette séquence sont annulés. Les clusters qui faisaient partie de la séquence reviennent au comportement de mise à niveau automatique par défaut pour leur version disponible enregistré.

Migrer une séquence de déploiement existante pour utiliser des étapes personnalisées

Si vous utilisez la version de la séquence de déploiement basée sur les flottes, disponible de manière générale, vous pouvez migrer vers une séquence qui utilise des étapes personnalisées en créant un RolloutSequence qui fait référence à vos flottes existantes.

Avant de migrer la séquence, nous vous recommandons de faire une copie de votre configuration de séquence de déploiement actuelle.

Pour migrer votre séquence de déploiement, procédez comme suit :

  1. Créez un projet Google Cloud dédié pour héberger votre séquence de déploiement. Ce projet ne fait généralement pas partie de la séquence, c'est-à-dire qu'il ne contient pas de parcs ni de clusters qui en font partie.
  2. Si vous souhaitez que la séquence de déploiement inclue des clusters spécifiques dans un parc, ajoutez des libellés à ces clusters. Cette étape est facultative.

  3. Suivez les instructions de la section Créer une séquence de déploiement avec des étapes personnalisées.

    Par exemple, le fichier manifeste suivant, nommé rollout-sequence-migrate.yaml, fait référence aux flottes existantes dans une séquence de déploiement précédente. Ce fichier manifeste décrit trois étapes, dont une étape canary dans le parc prod :

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: canary=true
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

Immédiatement après avoir défini un nouveau RolloutSequence pour vos parcs, GKE commence à mettre à niveau les parcs selon la nouvelle séquence et supprime la configuration précédente.

Migrer une séquence de déploiement avec des étapes personnalisées vers la séquence de déploiement précédente

Cette section explique comment revenir de la séquence de déploiement avec des étapes personnalisées au modèle de séquencement basé sur le parc généralement disponible. Ce processus consiste à supprimer le nouveau fichier RolloutSequence et à restaurer votre configuration d'origine basée sur le parc.

Éviter les mises à niveau dans le désordre lors de la migration

Pour éviter les mises à niveau non souhaitées ou dans le désordre pendant que vous reconfigurez votre séquence, appliquez une exclusion de maintenance à vos clusters de production. Cette étape suspend temporairement toutes les mises à niveau automatiques sur ces clusters. Par exemple, vous pouvez configurer une exclusion de maintenance de type no upgrades sur vos clusters de production.

Supprimer la séquence de déploiement

Supprimez l'objet RolloutSequence qui gère vos clusters. Cette suppression désactive la fonctionnalité d'étapes personnalisées.

Pour supprimer le RolloutSequence, exécutez la commande suivante :

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Remplacez ROLLOUT_SEQUENCE_NAME par le nom de votre séquence de déploiement.

Restaurer la configuration précédente de votre séquence de déploiement (sans étapes personnalisées)

Une fois que vous avez supprimé le RolloutSequence, vous pouvez restaurer votre configuration d'origine basée sur le parc. Ce processus consiste à recréer les fonctionnalités clusterupgrade avec leurs paramètres d'origine, y compris les liens upstreamFleet et les temps d'imprégnation pour chaque parc de votre séquence. Pour en savoir plus, consultez Créer une séquence de déploiement.

Supprimer les exclusions de maintenance

Une fois que vous avez restauré votre configuration d'origine de séquençage de déploiement basé sur un parc, supprimez l'exclusion de maintenance que vous avez appliquée lors de la première étape de cette section. GKE reprend les mises à niveau automatiques, qui sont désormais régies par votre séquence restaurée basée sur le parc.

Étape suivante