Partager via

Mise à jour d’un cluster Azure Kubernetes Service (AKS)

Une partie du cycle de vie du cluster AKS implique l’exécution de mises à niveau périodiques vers la dernière version de Kubernetes. Il est important d’appliquer les dernières mises à jour et mises à niveau de sécurité pour obtenir les fonctionnalités les plus récentes. Cet article explique comment vérifier et appliquer des mises à niveau à votre cluster AKS.

Mises à niveau de version de Kubernetes

Important

Quand vous mettez à niveau un cluster AKS pris en charge, vous ne pouvez pas ignorer les versions mineures de Kubernetes. Vous devez effectuer toutes les mises à niveau séquentiellement par numéro de version secondaire. Par exemple, les mises à niveau 1.14.x ->1.15.x ou 1.15.x ->1.16.x sont autorisées. 1.14.x ->1.16.x n'est pas autorisé. Vous ne pouvez ignorer plusieurs versions que lors d’une mise à niveau d’une version non prise en charge vers une version prise en charge. Par exemple, vous pouvez effectuer une mise à niveau à partir d’une version 1.10.x non prise en charge vers une version 1.12.x prise en charge, si disponible.

Lorsque vous exécutez une mise à niveau à partir d’une version non prise en charge qui ignore au moins deux versions mineures, le fonctionnement de la mise à niveau n’est pas garanti et celle-ci est exclue des contrats de niveau de service et de la garantie limitée. Si votre version est obsolète, nous vous recommandons de recréer votre cluster à la place.

Avant de commencer

  • Si vous utilisez l’interface de ligne de commande Azure, cet article nécessite Azure CLI version 2.34.1 ou ultérieure. Exécutez az --version pour trouver la version. Si vous devez installer ou mettre à niveau, voir Installer Azure CLI.
  • Si vous utilisez Azure PowerShell, cet article nécessite Azure PowerShell version 5.9.0 ou ultérieure. Exécutez Get-InstalledModule -Name Az pour trouver la version. Si vous avez besoin de procéder à une installation ou à une mise à niveau, consultez Installer Azure PowerShell.
  • L’exécution d’opérations de mise à niveau nécessite le rôle RBAC Microsoft.ContainerService/managedClusters/agentPools/write. Pour plus d’informations sur les rôles RBAC Azure, consultez les opérations du fournisseur de ressources Azure.
  • À compter de la version Kubernetes 1.30 et des versions 1.27 LTS, les API bêta sont désactivées par défaut lorsque vous effectuez une mise à niveau vers ces versions.

Avertissement

Une mise à niveau de cluster AKS déclenche une mise en cordon et une vidange de vos nœuds. Si vous disposez d’un faible quota, la mise à niveau peut échouer. Pour plus d’informations, consultez Augmenter les quotas.

Recherchez les mises à niveau du cluster AKS disponibles

Remarque

Pour rester au courant des correctifs, des versions et des mises à jour AKS, consultez le suivi des versions AKS.

  • Recherchez les publications de Kubernetes disponibles pour votre cluster au moyen de la commande az aks get-upgrades.

    az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster --output table

    L’exemple de sortie suivant montre que la version actuelle est 1.26.6 et répertorie les versions disponibles sous upgrades :

    {
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.26.6",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.3"
      }
    ]
  },
  ...
}

Questions fréquentes (FAQ)

J’ai mis à niveau uniquement le plan de contrôle. Pourquoi mes nœuds ont-ils également été mis à niveau ?

AKS peut déclencher une mise à niveau de nœud propagé (pool d’agents) parallèlement ou après une mise à niveau du plan de contrôle afin de maintenir la conformité et le bon fonctionnement du cluster. Cela se produit généralement lorsqu’une mise à niveau de nœud précédente a échoué ou a laissé des nœuds sur des versions mixtes.

Résoudre les messages d’erreur de mise à niveau du cluster AKS

L’exemple de sortie suivant signifie que l’extension appservice-kube n’est pas compatible avec votre version d’Azure CLI (la version minimale requise est 2.34.1) :

The 'appservice-kube' extension is not compatible with this version of the CLI.
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

Si vous recevez cette sortie, vous devez mettre à jour votre version d’Azure CLI. La commande az upgrade a été ajoutée dans la version 2.11.0, et elle ne fonctionne pas avec les versions antérieures à 2.11.0. Vous pouvez mettre à jour les anciennes versions en réinstallant Azure CLI comme décrit dans Installer l’interface Azure CLI. Si votre version d’Azure CLI est 2.11.0 ou ultérieure, exécutez az upgrade pour mettre à niveau Azure CLI vers la dernière version.

Si votre interface Azure CLI est mise à jour et que vous recevez l’exemple de sortie suivant, cela signifie qu’aucune mise à niveau n’est disponible :

ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

Si aucune mise à niveau n’est disponible, créez un cluster avec une version prise en charge de Kubernetes et migrez vos charges de travail du cluster existant vers le nouveau cluster. AKS ne prend pas en charge la mise à niveau d’un cluster vers une version plus récente de Kubernetes quand az aks get-upgrades il indique qu’aucune mise à niveau n’est disponible.

Mettre à niveau un cluster AKS

Pendant le processus de mise à niveau du cluster, AKS effectue les opérations suivantes :

  • Il ajoute un nouveau nœud de tampon (ou autant de nœuds que ceux configurés dans max-surge) au cluster qui exécute la version de Kubernetes spécifiée.
  • Il effectue l’isolation et le drainage de l’un des anciens nœuds afin de limiter la perturbation des applications en cours d’exécution. Si vous utilisez max surge, il isole et draine autant de nœuds que le nombre de nœuds de tampon spécifiés.
  • Pour les pods de longue durée, vous pouvez configurer le délai d’expiration du drainage de nœud, afin de personnaliser le délai d’attente avant éviction des pods et l’arrêt normal de chaque nœud. Si aucun délai n’est spécifié, la valeur par défaut est de 30 minutes. La valeur de délai d’attente minimale autorisée est de 5 minutes. La limite maximale pour le délai d’expiration du drainage est de 24 heures.
  • Lorsque l’ancien nœud est entièrement vidé, il est reconfiguré pour recevoir la nouvelle version et devient le nœud tampon pour le nœud suivant à mettre à niveau.
  • Optionnellement, vous pouvez définir une durée à attendre entre le drainage d'un nœud et sa réimagerie avant de passer au nœud suivant. Un intervalle court vous permet d’effectuer d’autres tâches, comme vérifier l’intégrité de l’application depuis un tableau de bord Grafana pendant le processus de mise à niveau. Nous vous recommandons un délai court pour le processus de mise à niveau, aussi près que possible de 0 minute. Dans le cas contraire, un temps d'immersion du nœud plus élevé influe sur le délai de découverte d'un problème. La valeur minimale de temps de trempage est de 0 minutes, avec un maximum de 30 minutes. Si elle n’est pas spécifiée, sa valeur par défaut est de 0 minute.
  • Ce processus se répète jusqu’à ce que tous les nœuds du cluster soient mis à niveau.
  • À la fin du processus, le dernier nœud tampon est supprimé, ce qui a pour effet de maintenir le nombre de nœuds d’agent existants et l’équilibre de la zone.

Remarque

Si aucun patch n’est spécifié, le cluster est automatiquement mis à niveau vers le dernier patch GA de la version mineure spécifiée. Par exemple, la définition de --kubernetes-version sur 1.28 entraîne la mise à niveau du cluster vers 1.28.9.

Pour plus d’informations, consultez Mises à niveau des versions mineures de Kubernetes prises en charge dans AKS.

  1. Mettez à niveau votre cluster à l’aide de la commande az aks upgrade.

    az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version <KUBERNETES_VERSION>

  2. Vérifiez si la mise à niveau a réussi avec la commande az aks show.

    az aks show --resource-group myResourceGroup --name myAKSCluster --output table

    L’exemple de sortie suivant montre que le cluster exécute à présent la version 1.27.3 :

    Name          Location    ResourceGroup    KubernetesVersion    ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  -------------------  ----------------------------------------------
myAKSCluster  eastus      myResourceGroup  1.27.3               Succeeded            myakscluster-dns-379cbbb9.hcp.eastus.azmk8s.io

Définir un canal de mise à niveau automatique

Vous pouvez définir un canal de mise à niveau automatique sur votre cluster. Pour plus d’informations, consultez Mise à niveau automatique d’un cluster AKS.

Personnaliser l’augmentation du nombre de nœuds pendant une mise à niveau

Important

  • Une augmentation du nombre de nœuds nécessite un quota d’abonnement pour l’augmentation maximale (max-surge) demandée pour chaque opération de mise à niveau. Par exemple, un cluster comprenant cinq pools de nœuds avec quatre nœuds chacun comporte en tout 20 nœuds. Si chaque pool de nœuds a une valeur max-surge de 50 %, un quota de calcul et d’adresse IP supplémentaire de 10 nœuds (2 nœuds * 5 pools) est nécessaire pour effectuer la mise à niveau.

  • Le paramètre max-surge sur un pool de nœuds est persistant. Les mises à niveau ultérieures de Kubernetes ou les mises à niveau des versions de nœud utiliseront ce paramètre. Vous pouvez modifier la valeur de surtension maximale (max-surge) pour vos pools de nœuds à tout moment. Pour les pools de nœuds de production, nous vous recommandons de définir un paramètre max-surge de 33 %.

  • Si vous utilisez Azure CNI, vérifiez que des adresses IP sont disponibles dans le sous-réseau et assurez-vous de satisfaire aux exigences IP d’Azure CNI.

AKS configure les mises à niveau avec un nœud supplémentaire par défaut. La valeur par défaut un pour les paramètres de surtension maximale (max-surge) permet à AKS de réduire les interruptions de la charge de travail en créant un nœud avant l’isolation ou le drainage des applications existantes pour remplacer un nœud de version antérieure. Vous pouvez personnaliser la valeur de surtension maximale par pool de nœuds. Lorsque vous augmentez la valeur de surtension maximale, le processus de mise à niveau se termine plus rapidement, et vous risquez de subir des interruptions pendant le processus de mise à niveau.

Par exemple, une valeur max surge de 100% offre le processus de mise à niveau le plus rapide possible, mais entraîne également le drainage simultané de tous les nœuds du pool de nœuds. Vous pouvez utiliser une valeur plus élevée comme celle-ci pour les environnements de test. Pour les pools de nœuds de production, nous vous recommandons d’utiliser un paramètre max_surge de 33%.

AKS accepte à la fois des valeurs entières et des valeurs en pourcentage pour le taux de montée maximal. Par exemple, une valeur entière de 5 indique l’ajout de cinq nœuds supplémentaires. Une valeur de pourcentage de 50% indique une valeur d’augmentation de la moitié du nombre actuel de nœuds dans le pool. Les valeurs maximales de pourcentage d’augmentation peuvent avoir un minimum de 1% et un maximum de 100%. Si vous utilisez une valeur en pourcentage, le nombre de nœuds est arrondi à la valeur entière la plus proche. Si la valeur de surtension maximale est supérieure au nombre requis de nœuds à mettre à niveau, le nombre de nœuds à mettre à niveau est utilisé pour la valeur de surtension maximale. Pendant une mise à niveau, la valeur maximale d’augmentation peut être minimale 0 et une valeur maximale égale au nombre de nœuds de votre pool de nœuds. Vous pouvez définir des valeurs plus élevées, mais le nombre maximal de nœuds utilisés pour la surtension maximale ne peut pas être supérieur au nombre de nœuds dans le pool au moment de la mise à niveau.

Définir la valeur de surtension maximale

  • Définissez les valeurs de surtension maximale des pools de nœuds nouveaux ou existants à l’aide de la commande az aks nodepool add ou az aks nodepool update.

    # Set max surge for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%

# Update max surge for an existing node pool 
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 5

Personnaliser les nœuds indisponibles pendant la mise à niveau

Important

  • maxSurge doit être défini sur 0 pour que maxUnavailable soit défini. Les deux valeurs ne peuvent pas être actives en même temps.
  • maxUnavailable ne crée pas de nœuds de surcharge pendant le processus de mise à niveau. Au lieu de cela, AKS isole nmaxUnavailable nœuds à la fois et évacue les pods vers d’autres nœuds du même pool d’agents. Cela peut entraîner des perturbations de la charge de travail si les pods ne peuvent pas être programmés.
  • maxUnavailable peut entraîner davantage d’échecs en raison de PodDisruptionBudgets (PDB) non satisfaits, car il y aura moins de ressources sur lesquelles programmer les pods. Consultez la résolution des problèmes de PodDisruptionBudgets pour obtenir des suggestions d’atténuation si vous rencontrez des échecs lors de l’utilisation de cette fonctionnalité.
  • Vous ne pouvez pas définir maxUnavailable sur les pools de nœuds système.

AKS peut également configurer des mises à niveau pour ne pas utiliser de nœud de surtension et mettre à niveau les nœuds en place. La valeur maxUnavailable peut être utilisée pour déterminer le nombre de nœuds pouvant être isolés et drainés des nœuds de pool de nœuds existants.

AKS accepte les valeurs entières et une valeur de pourcentage pour maxUnavailable. Par exemple, une valeur entière de 5 indique que cinq nœuds seront isolés des nœuds existants du pool de nœuds. Une valeur de pourcentage de 50% indique une valeur de maxUnavailable de la moitié du nombre de nœuds actuels dans le pool. Les valeurs de pourcentage peuvent être au minimum de maxUnavailable et au maximum de 1%. Si vous utilisez une valeur en pourcentage, le nombre de nœuds est arrondi à la valeur entière la plus proche. Lors d'une mise à niveau, la valeur maxUnavailable peut être au minimum 0 et atteindre une valeur maximale égale au nombre de nœuds de votre pool de nœuds.

Définir la valeur de maxUnavailable

  • Définissez les valeurs de maxUnvailable pour les pools de nœuds nouveaux ou existants à l'aide de la commande az aks nodepool add ou az aks nodepool update.

    # Set maxUnavailable for a new node pool
az aks nodepool add --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5
# Update maxUnavailable for an existing node pool 
az aks nodepool update --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5
# Set maxUnavailable at upgrade time for an existing node pool
az aks nodepool upgrade --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5

Définir la valeur du délai d’expiration pour le drainage de nœud

Il peut arriver qu’une charge de travail durable s’exécute sur un pod donné et qu’elle ne puisse pas être replanifiée sur un autre nœud pendant son exécution, par exemple une charge de travail avec état utilisant intensivement la mémoire dont l’exécution doit se terminer. Dans ce cas, vous pouvez configurer un délai d’expiration de drainage de nœud que AKS respectera dans le flux de travail de mise à niveau. Si aucune valeur de délai d’expiration de drainage de nœud n’est spécifiée, la valeur par défaut est de 30 minutes. La valeur minimale autorisée du délai d’expiration du drainage est de 5 minutes et la limite maximale de délai d’expiration du drainage est de 24 heures.

Si la valeur du délai d’expiration du drainage s’écoule et que les pods sont toujours en cours d’exécution, l’opération de mise à niveau est arrêtée. Les opérations PUT ultérieures reprendront la mise à niveau arrêtée. Il est également recommandé pour les pods de longue durée de configurer [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/].

  • Définissez le délai d'expiration pour le drainage des nœuds dans les pools de nœuds nouveaux ou existants en utilisant la commande az aks nodepool add ou az aks nodepool update.

    # Set drain time-out for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster  --drain-time-out 100

# Update drain time-out for an existing node pool
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --drain-time-out 45

Définir la valeur du temps d'immersion du nœud

Pour permettre un temps de pause entre le drainage d’un nœud et sa reconfiguration avant de passer au nœud suivant, vous pouvez définir le délai sur une valeur comprise entre 0 et 30 minutes. Si aucune valeur de temps de trempage des nœuds n’est spécifiée, la valeur par défaut est de 0 minutes.

  • Définissez le délai d’absorption des nœuds sur les pools de nœuds nouveaux ou existants en utilisant la commande az aks nodepool add, az aks nodepool update, ou az aks nodepool upgrade.

    # Set node soak time for a new node pool
az aks nodepool add --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10

# Update node soak time for an existing node pool
az aks nodepool update --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 5

# Set node soak time when upgrading an existing node pool
az aks nodepool upgrade --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 20

Mise à niveau via une dérive de version significative

Lors de la mise à niveau d’une version non prise en charge de Kubernetes vers une version prise en charge, il est important de tester vos charges de travail sur la version cible. Bien qu’AKS fasse tous les efforts pour mettre à niveau votre plan de contrôle et votre plan de données, il n'y a aucune garantie que vos charges de travail continueront de fonctionner. Si vos charges de travail s’appuient sur des API Kubernetes déconseillées, la plateforme a introduit des changements ou comportements incompatibles (documentés dans les notes de version AKS), ces changements doivent être corrigés.

Dans ces situations, nous vous recommandons de tester vos charges de travail sur la nouvelle version et de résoudre les problèmes de version avant d’effectuer une mise à niveau sur place de votre cluster.

Un modèle courant dans cette situation consiste à effectuer un déploiement bleu/vert de vos charges de travail modifiées vers un nouveau cluster qui se trouve sur une version de Kubernetes prise en charge et acheminer les demandes vers le nouveau cluster.

Afficher les événements de mise à niveau

  • Affichez les événements de mise à niveau à l’aide de la commande kubectl get events.

    kubectl get events

    L’exemple de sortie suivant montre certains des événements ci-dessus listés pendant une mise à niveau :

    ...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 1m45s Normal Upgrade node/aks-nodepool1-96663640-vmss000001   Soak duration 5m0s after draining node: aks-nodepool1-96663640-vmss000001
...
default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool nodepool1
...

Compatibilité de version Client-Server pour kubectl

Vérifiez que votre client kubectl se trouve à ±1 version mineure du plan de contrôle AKS (serveur API) pour maintenir la compatibilité. Le dépassement de cette asymétrie de version prise en charge peut entraîner des échecs de commande ou un comportement inattendu. La commande suivante affiche à la fois la version du client et la version du serveur et avertit s’ils ne sont pas synchronisés :

kubectl version

S’il existe une incompatibilité de version :

  • Mettez à jour ou rétrogradez votre kubectl pour vous aligner sur la version du serveur.
  • Sinon, si vous êtes limité à la modification de votre kubectl local, envisagez d’utiliser la commande az aks command invoke dans Azure CLI pour exécuter vos commandes kubectl à distance sur votre cluster.

Étapes suivantes

Pour savoir comment configurer des mises à niveau automatiques, consultez Configurer des mises à niveau automatiques pour un cluster AKS.

Pour obtenir une discussion détaillée sur les meilleures pratiques de mise à niveau et d’autres considérations, consultez Instructions de mise à jour corrective et de mise à niveau AKS.

  • Last updated on