Migrer des nœuds vers containerd 2

Les clusters Google Kubernetes Engine (GKE) utilisent des images de nœud containerd avec tous les nœuds de calcul exécutant la version 1.24 ou ultérieure. Les nœuds de calcul utilisent une version spécifique de containerd, en fonction de la version de GKE :

  • Les nœuds qui exécutent GKE 1.32 ou une version antérieure, avec des images de nœud containerd, utilisent containerd 1.7 ou des versions antérieures.
  • Les nœuds qui exécutent GKE 1.33 utilisent containerd 2.0.

Lorsque les nœuds GKE sont mis à niveau de la version 1.32 à la version 1.33, ils migrent de containerd 1.7 vers la nouvelle version majeure, containerd 2.0. Vous ne pouvez pas modifier la version de containerd utilisée par une version de GKE.

Vous pouvez ignorer cette page si vous savez que vos charges de travail s'exécutent comme prévu sur containerd 2.

Transition de GKE vers containerd 2

Consultez le calendrier suivant pour comprendre comment GKE migre les clusters existants vers containerd 2 :

  • Avec la version mineure 1.32, GKE utilise containerd 1.7. containerd 1.7 a rendu obsolètes les images Docker de schéma 1 et l'API CRI (Container Runtime Interface) v1alpha2. Pour en savoir plus sur les autres fonctionnalités obsolètes dans les versions antérieures, consultez Propriétés de configuration obsolètes.
  • Avec la version mineure 1.33, GKE utilise containerd 2.0, qui ne prend plus en charge les images Docker de schéma 1 ni l'API CRI v1alpha2.
  • Les propriétés de configuration containerd suivantes du plug-in CRI sont obsolètes et seront supprimées dans containerd 2.2, avec une version GKE qui n'a pas encore été annoncée : registry.auths, registry.configs, registry.mirrors. registry.configs.tls, cependant, a déjà été supprimé dans containerd 2.0.

Pour connaître la date approximative des mises à niveau automatiques vers des versions mineures ultérieures, telles que la version 1.33, consultez le calendrier estimé des canaux de publication.

Impact de la transition vers containerd 2

Lisez la section suivante pour comprendre l'impact de cette transition vers containerd 2.

Mises à niveau automatiques suspendues

GKE suspend les mises à niveau automatiques vers la version 1.33 lorsqu'il détecte qu'un cluster utilise les fonctionnalités obsolètes. Toutefois, si les nœuds de votre cluster utilisent ces fonctionnalités, nous vous recommandons de créer une exclusion de maintenance pour empêcher la mise à niveau des nœuds. L'exclusion de maintenance garantit que vos nœuds ne sont pas mis à niveau si GKE ne détecte aucune utilisation.

Une fois que vous avez migré depuis ces fonctionnalités, GKE reprend les mises à niveau mineures automatiques vers la version 1.33 si les conditions suivantes sont remplies :

  • GKE n'a pas détecté d'utilisation de fonctionnalités obsolètes depuis 14 jours, ou depuis 3 jours pour les propriétés CRI registry.configs obsolètes.
  • 1.33 est une cible de mise à niveau automatique pour les nœuds de votre cluster.
  • Aucun autre facteur bloquant n'a été identifié. Pour en savoir plus, consultez Calendrier des mises à niveau automatiques.

Pour les pools de nœuds de cluster Standard, vous pouvez également mettre à niveau manuellement le pool de nœuds.

Fin de la période de compatibilité et conséquences du non-respect de la préparation à la migration

GKE suspend les mises à niveau automatiques jusqu'à la fin de l'assistance standard. Si votre cluster est enregistré dans le canal Extended, vos nœuds peuvent rester sur une version jusqu'à la fin de l'assistance Extended. Pour en savoir plus sur les mises à niveau automatiques des nœuds à la fin de la période de compatibilité, consultez Mises à niveau automatiques à la fin de la période de compatibilité.

Si vous ne migrez pas depuis ces fonctionnalités, lorsque la version 1.32 atteindra la fin de sa période de compatibilité et que les nœuds de votre cluster seront automatiquement mis à niveau vers la version 1.33, vous pourrez rencontrer les problèmes suivants avec vos clusters :

  • Les charges de travail utilisant des images Docker de schéma 1 échouent.
  • Les applications qui appellent l'API CRI v1alpha2 rencontrent des échecs lors de l'appel de l'API.

Identifier les clusters concernés

GKE surveille vos clusters et utilise l'outil de recommandation pour vous fournir des conseils via des insights et des recommandations sur la façon d'identifier les nœuds de cluster qui utilisent ces fonctionnalités obsolètes.

Exigences concernant les versions

Les clusters reçoivent ces insights et recommandations s'ils exécutent les versions suivantes ou ultérieures :

  • 1.28.15-gke.1159000
  • 1.29.9-gke.1541000
  • 1.30.5-gke.1355000
  • 1.31.1-gke.1621000

Obtenir des insights et des recommandations

Suivez les instructions pour afficher des insights et des recommandations. Vous pouvez obtenir des insights à l'aide de la console Google Cloud . Vous pouvez également utiliser la Google Cloud CLI ou l'API Recommender en filtrant avec les sous-types suivants :

  • DEPRECATION_CONTAINERD_V1_SCHEMA_IMAGES: Images Docker de schéma 1
  • DEPRECATION_CONTAINERD_V1ALPHA2_CRI_API: API CRI v1alpha2
  • DEPRECATION_CONTAINERD_V2_CONFIG_REGISTRY_CONFIGS : propriétés CRI registry.configs obsolètes, y compris registry.configs.auth et registry.configs.tls

Migrer depuis des fonctionnalités obsolètes

Consultez le contenu suivant pour comprendre comment migrer depuis les fonctionnalités obsolètes avec containerd 2.

Migrer depuis les images Docker de schéma 1

Identifiez les charges de travail utilisant des images à migrer, puis migrez-les.

Trouver les images à migrer

Vous pouvez utiliser différents outils pour trouver les images à migrer.

Utiliser les insights et les recommandations ou Cloud Logging

Comme expliqué dans la section Identifier les clusters concernés, vous pouvez utiliser des insights et des recommandations pour trouver les clusters qui utilisent des images Docker Schema 1 si votre cluster exécute une version minimale ou ultérieure. De plus, vous pouvez utiliser la requête suivante dans Cloud Logging pour vérifier les journaux containerd et trouver les images Docker Schema 1 dans votre cluster :

jsonPayload.SYSLOG_IDENTIFIER="containerd"
"conversion from schema 1 images is deprecated"

Si plus de 30 jours se sont écoulés depuis l'extraction de l'image, il est possible que vous ne voyiez pas de journaux pour cette image.

Utiliser la commande ctr directement sur un nœud

Pour interroger un nœud spécifique afin de renvoyer toutes les images non supprimées qui ont été extraites en tant que schéma 1, exécutez la commande suivante sur un nœud :

  ctr --namespace k8s.io images list 'labels."io.containerd.image/converted-docker-schema1"'

Cette commande peut être utile si, par exemple, vous résolvez les problèmes d'un nœud spécifique et que vous ne voyez pas d'entrées de journal dans Cloud Logging, car l'image a été extraite il y a plus de 30 jours.

Utiliser l'outil Open Source crane

Vous pouvez également utiliser des outils Open Source tels que crane pour rechercher des images.

Exécutez la commande crane suivante pour vérifier la version du schéma d'une image :

crane manifest $tagged_image | jq .schemaVersion

Préparer les charges de travail

Pour préparer les charges de travail qui exécutent des images Docker de schéma 1, vous devez les migrer vers des images Docker de schéma 2 ou des images OCI (Open Container Initiative). Voici quelques options de migration :

  • Trouvez une image de remplacement : vous pourrez peut-être trouver une image open source ou fournie par un fournisseur et accessible au public.
  • Convertissez l'image existante : si vous ne trouvez pas d'image de remplacement, vous pouvez convertir les images Docker de schéma 1 existantes en images OCI en suivant les étapes ci-dessous :
    1. Extrayez l'image Docker dans containerd, qui la convertit automatiquement en image OCI.
    2. Transférez la nouvelle image OCI vers votre registre.

Migrer depuis l'API CRI v1alpha2

L'API CRI v1alpha2 a été supprimée dans Kubernetes 1.26. Vous devez identifier les charges de travail qui accèdent au socket containerd et mettre à jour ces applications pour qu'elles utilisent l'API v1.

Identifier les charges de travail potentiellement concernées

Vous pouvez utiliser différentes techniques pour identifier les charges de travail qui peuvent nécessiter une migration. Ces techniques peuvent générer des faux positifs que vous devez examiner plus en détail pour déterminer si aucune action n'est nécessaire.

Utiliser les insights et les recommandations

Vous pouvez utiliser les insights et les recommandations pour trouver les clusters qui utilisent l'API v1alpha2 si votre cluster exécute une version minimale ou ultérieure. Pour en savoir plus, consultez Identifier les clusters concernés.

Lorsque vous consultez des insights dans la console Google Cloud , consultez le panneau latéral Migrez vos charges de travail depuis l'API CRI v1alpha2 obsolète. Le tableau Charges de travail à valider de ce panneau liste les charges de travail qui pourraient être affectées. Cette liste inclut toutes les charges de travail qui ne sont pas gérées par GKE et qui comportent des volumes hostPath contenant le chemin du socket containerd (par exemple, /var/run/containerd/containerd.sock ou /run/containerd/containerd.sock).

Il est important de comprendre les points suivants :

  • La liste des charges de travail à valider peut contenir des faux positifs. Utilisez-le uniquement pour les investigations. Le fait qu'une charge de travail figure dans cette liste ne signifie pas nécessairement qu'elle utilise l'API obsolète. La présence d'un faux positif n'entraînera pas la suspension des mises à niveau automatiques. La mise en veille n'est basée que sur l'utilisation réellement observée de l'API obsolète.
  • Cette liste peut être vide ou incomplète. Une liste vide ou incomplète peut se produire si les charges de travail qui utilisent l'API obsolète étaient éphémères et ne s'exécutaient pas lorsque GKE a effectué sa vérification périodique. La présence de la recommandation elle-même signifie que l'utilisation de l'API CRI v1alpha2 a été détectée sur au moins un nœud de votre cluster. Les mises à niveau automatiques reprennent une fois que l'utilisation des API obsolètes n'a pas été détectée pendant 14 jours.

Par conséquent, nous vous recommandons d'examiner plus en détail l'utilisation réelle de l'API à l'aide des méthodes suivantes.

Vérifier les charges de travail tierces concernées

Pour les logiciels tiers déployés sur vos clusters, vérifiez que ces charges de travail n'utilisent pas l'API CRI v1alpha2. Vous devrez peut-être contacter les fournisseurs concernés pour vérifier les versions de leurs logiciels qui sont compatibles.

Utiliser kubectl

La commande suivante vous aide à identifier les charges de travail potentiellement concernées en recherchant celles qui accèdent au socket containerd. Elle utilise une logique semblable à celle utilisée pour le tableau Charges de travail à valider dans la recommandation de la console Google Cloud . Il renvoie les charges de travail non gérées par GKE qui comportent des volumes hostPath, y compris le chemin d'accès au socket. Comme la recommandation, cette requête peut renvoyer des faux positifs ou manquer des charges de travail de courte durée.

Exécutez la commande suivante :

kubectl get pods --all-namespaces -o json | \
jq -r '
  [
    "/", "/var", "/var/","/var/run", "/var/run/",
    "/var/run/containerd", "/var/run/containerd/", "/var/run/containerd/containerd.sock",
    "/run", "/run/", "/run/containerd", "/run/containerd/",
    "/run/containerd/containerd.sock"
  ] as $socket_paths |
  [
    "kube-system", "kube-node-lease", "istio-system", "asm-system",
    "gatekeeper-system", "config-management-system", "config-management-monitoring",
    "cnrm-system", "hnc-system", "gke-managed-system", "gke-gmp-system",
    "gmp-system", "gke-managed-cim"
  ] as $excluded_namespaces |
  .items[] |
  select(
    (.spec.volumes[]?.hostPath.path as $p | $socket_paths | index($p))
    and
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
  ) |
  .metadata.namespace + "/" + .metadata.name
'
Utiliser le traçage eBPF pour identifier les appelants d'API

Pour identifier plus précisément les charges de travail qui appellent l'API CRI v1alpha2, vous pouvez déployer deux DaemonSets spécialisés :

  • containerd-socket-tracer enregistre tout processus ouvrant une connexion au socket containerd, ainsi que les détails du pod et du conteneur.
  • cri-v1alpha2-api-deprecation-reporter enregistre la dernière fois que l'API CRIv1alpha2 a été appelée.

Ces outils utilisent le filtre de paquets Berkeley étendu (eBPF) pour tracer les connexions au socket containerd et les corréler avec les appels d'API obsolètes réels.

En corrélant les codes temporels de ces deux outils, vous pouvez identifier précisément la charge de travail qui effectue l'appel d'API obsolète. Cette méthode offre un degré de confiance plus élevé que la simple vérification des volumes hostPath, car elle observe les connexions de socket et l'utilisation de l'API réelles.

Pour obtenir des instructions détaillées sur le déploiement et l'utilisation de ces outils, ainsi que sur l'interprétation de leurs journaux, consultez Suivre les connexions de socket containerd.

Si, après avoir utilisé ces outils, vous ne parvenez toujours pas à identifier la source des appels d'API obsolètes, mais que la recommandation reste active, consultez Obtenir de l'aide.

Une fois que vous avez identifié une charge de travail qui utilise l'API CRI v1alpha2, soit à l'aide des méthodes précédentes, soit en inspectant votre code, vous devez mettre à jour son code pour qu'il utilise l'API v1.

Mettre à jour le code de l'application

Pour mettre à jour votre application, supprimez l'endroit où l'application importe la bibliothèque cliente k8s.io/cri-api/pkg/apis/runtime/v1alpha2 et modifiez le code pour utiliser la version v1 de l'API. Cette étape consiste à modifier le chemin d'importation et à mettre à jour la façon dont votre code appelle l'API.

Par exemple, consultez le code Golang suivant, qui utilise la bibliothèque obsolète :

  package main

  import (
    ...

    runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"
  )

  func foo() {
    ...

    client := runtimeapi.NewRuntimeServiceClient(conn)
    version, err := client.Version(ctx, &runtimeapi.VersionRequest{})

    ...
  }

Ici, l'application importe la bibliothèque v1alpha2 et l'utilise pour émettre des RPC. Si les RPC utilisent la connexion au socket containerd, cette application est à l'origine de la suspension des mises à niveau automatiques pour le cluster par GKE.

Pour rechercher et mettre à jour le code de votre application, procédez comme suit :

  1. Identifiez les applications Golang problématiques en exécutant la commande suivante pour rechercher le chemin d'importation v1alpha2 :

      grep -r "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

    Si le résultat de cette commande indique que la bibliothèque v1alpha2 est utilisée dans le fichier, vous devez mettre à jour le fichier.

    Par exemple, remplacez le code d'application suivant :

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

  2. Mettez à jour le code pour utiliser la version 1 :

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1"

Migrer depuis les propriétés de configuration containerd obsolètes

Les propriétés de configuration containerd registry.auths, registry.configs et registry.mirrors du plug-in CRI sont obsolètes et seront supprimées dans containerd 2.2, avec une version GKE qui n'a pas encore été annoncée. registry.configs.tls, cependant, a déjà été supprimé dans containerd 2.0.

Identifier les charges de travail

Vous pouvez utiliser différentes techniques pour identifier les charges de travail à migrer.

Utiliser les insights et les recommandations

Dans un premier temps, vous pouvez utiliser les insights et les recommandations pour trouver les clusters qui utilisent les propriétés de configuration containerd obsolètes. Cela nécessite une version minimale de GKE. Pour en savoir plus sur cette approche, consultez Identifier les clusters concernés.

Lorsque vous consultez des insights dans la console Google Cloud , consultez le panneau latéral Migrer votre configuration containerd depuis le champ des authentifications obsolète du registre CRI ou Migrer votre configuration containerd depuis le champ des duplications obsolète du registre CRI. Pour trouver les charges de travail susceptibles d'accéder à la configuration containerd, consultez la section Charges de travail à vérifier.

Utiliser kubectl

Vous pouvez également utiliser kubectl pour identifier les charges de travail.

Recherchez les charges de travail qui modifient la configuration containerd en vérifiant les charges de travail avec les attributs suivants :

  • Charges de travail contenant un volume hostPath incluant la configuration containerd
  • Charges de travail comportant un conteneur avec accès privilégié (spec.containers.securityContext.privileged: true) et utilisant l'espace de noms de l'ID de processus (PID) de l'hôte (spec.hostPID: true)

Cette commande peut renvoyer des faux positifs, car la charge de travail peut accéder à d'autres fichiers de ces répertoires qui ne sont pas la configuration containerd. Il est également possible que cette commande ne renvoie pas les charges de travail qui accèdent au fichier de configuration containerd de manière moins courante.

Exécutez la commande suivante pour rechercher les DaemonSets :

kubectl get daemonsets --all-namespaces -o json | \
jq -r '
  [
    "/", "/etc", "/etc/",
    "/etc/containerd", "/etc/containerd/",
    "/etc/containerd/config.toml"
  ] as $host_paths |
  [
    "kube-system", "kube-node-lease", "istio-system", "asm-system",
    "gatekeeper-system", "config-management-system", "config-management-monitoring",
    "cnrm-system", "hnc-system", "gke-managed-system", "gke-gmp-system",
    "gmp-system", "gke-managed-cim"
  ] as $excluded_namespaces |
  .items[] |
  select(
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
    and
    (
      (any(.spec.template.spec.volumes[]?.hostPath.path; IN($host_paths[])))
      or
      (
        .spec.template.spec.hostPID == true and
        any(.spec.template.spec.containers[]; .securityContext?.privileged == true)
      )
    )
  ) |
  .metadata.namespace + "/" + .metadata.name
'

Migrer depuis les propriétés de registre CRI auths ou configs.auth

Si vos charges de travail utilisent les propriétés auths ou configs.auth dans la configuration containerd pour s'authentifier auprès d'un registre privé afin d'extraire des images de conteneurs, vous devez migrer les charges de travail utilisant ces images vers le champ imagePullSecrets. Pour en savoir plus, consultez Extraire une image d'un registre privé.

Pour identifier et migrer les charges de travail qui utilisent les propriétés auths ou configs.auth obsolètes, consultez les instructions suivantes.

Trouver les informations d'authentification pour votre registre

Vous pouvez trouver les informations d'authentification de votre registre de l'une des manières suivantes :

  • Examinez les sections auths et configs.auth du registre CRI dans le fichier /etc/containerd/config.toml en vous connectant à un nœud GKE.
  • Recherchez la charge de travail qui modifie votre fichier de configuration containerd et consultez les informations d'authentification incluses à l'aide des méthodes de identification des charges de travail décrites précédemment. GKE n'utilise pas ces paramètres pour ses charges de travail système.

Si vous utilisez la propriété registry.configs.auth, les informations d'authentification peuvent ressembler à ce qui suit :

  [plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN".auth]
    username = "example-user"
    password = "example-password"

Collectez ces informations d'authentification pour chaque domaine de registre spécifié dans votre configuration.

Mettre à jour votre charge de travail pour utiliser le champ imagePullSecrets
  1. Créez un secret avec vos informations d'authentification de la section précédente en suivant les instructions pour extraire une image d'un registre privé.

  2. Identifiez les charges de travail à migrer vers le champ imagePullSecrets en exécutant la commande suivante :

    kubectl get pods -A -o json |
jq -r ".items[] |
  select(.spec.containers[] |
        .image | startswith(\"$REGISTRY_DOMAIN\")) |
  .metadata.namespace + \"/\" + .metadata.name"

    Vous devez créer un secret pour chaque espace de noms utilisé par les charges de travail avec des images provenant de ce domaine de registre.

  3. Mettez à jour vos charges de travail pour qu'elles utilisent le champ imagePullSecrets avec les secrets que vous avez créés à l'étape précédente.

    Si vous devez migrer un grand nombre de charges de travail, vous pouvez également implémenter un MutatingAdmissionWebhook pour ajouter le champ imagePullSecrets.

Mettez à jour votre configuration containerd pour arrêter de définir les authentifications du registre

Une fois que vous avez migré vos charges de travail pour qu'elles utilisent le champ imagePullSecrets, vous devez mettre à jour les charges de travail qui modifient votre configuration containerd pour qu'elles cessent de définir les authentifications du registre. Pour toutes les charges de travail que vous avez identifiées comme modifiant la configuration, modifiez-les pour qu'elles cessent de définir les authentifications du registre.

Tester avec un nouveau pool de nœuds et migrer les charges de travail vers le nouveau pool de nœuds

Pour réduire le risque de provoquer des problèmes avec vos charges de travail, procédez comme suit :

  1. Créer un pool de nœuds.
  2. Planifiez la charge de travail mise à jour qui modifie votre configuration containerd sur les nœuds du nouveau pool de nœuds.
  3. Migrez vos charges de travail restantes vers le nouveau pool de nœuds en suivant les instructions pour migrer des charges de travail entre des pools de nœuds.

Migrer depuis la propriété configs.tls du registre CRI

Si vos charges de travail utilisent la propriété registry.configs.tls, vous devez les migrer pour accéder aux registres privés avec des certificats CA privés.

Suivez les instructions pour migrer à partir de DaemonSets de configuration. Pour ce faire, procédez comme suit :

  1. Mettez à jour vos charges de travail qui modifient la configuration containerd pour qu'elles cessent de définir les détails TLS.
  2. Stockez les certificats dans Secret Manager.
  3. Créez un fichier de configuration d'exécution qui pointe vers vos certificats.
  4. Créez un pool de nœuds et vérifiez que vos charges de travail qui utilisent des images hébergées à partir du registre privé fonctionnent comme prévu.
  5. Appliquez la configuration à un nouveau cluster et commencez à exécuter les charges de travail sur ce cluster, ou appliquez la configuration au cluster existant. L'application de la configuration au cluster existant pourrait potentiellement perturber d'autres charges de travail existantes. Pour en savoir plus sur ces deux approches, consultez Créer un fichier de configuration d'exécution.

Après la migration, assurez-vous de ne plus appliquer de modifications à votre champ registry.configs, car cela pourrait entraîner des problèmes avec containerd.

Obtenir de l'aide

Si vous ne parvenez toujours pas à déterminer la source des appels d'API obsolètes et que les recommandations restent actives, envisagez l'étape suivante :