Condividi tramite

Aggiornare un cluster del servizio Azure Kubernetes

Parte del ciclo di vita del cluster del servizio Azure Kubernetes prevede l'esecuzione di aggiornamenti periodici alla versione più recente di Kubernetes. È importante applicare le versioni di sicurezza e gli aggiornamenti più recenti per ottenere le funzionalità più recenti. Questo articolo illustra come verificare e applicare gli aggiornamenti al cluster AKS.

Aggiornamenti della versione di Kubernetes

Importante

Quando si aggiorna un cluster AKS supportato, non è possibile ignorare le versioni minori di Kubernetes. È necessario eseguire tutti gli aggiornamenti in sequenza in base al numero di versione secondaria. Ad esempio, gli aggiornamenti tra 1.14.x ->1.15.x o 1.15.x ->1.16.x sono consentiti. 1.14.x ->1.16.x non è consentito. È possibile ignorare più versioni solo quando si esegue l'aggiornamento da una versione non supportata a una versione supportata. Ad esempio, è possibile eseguire un aggiornamento da una versione 1.10.x non supportata a una versione 1.12.x supportata, se disponibile.

Quando si esegue un aggiornamento da una versione non supportata che ignora due o più versioni secondarie, l'aggiornamento non ha alcuna garanzia di funzionalità ed è escluso dai contratti di servizio e dalla garanzia limitata. Se la tua versione non è aggiornata, ti consigliamo di ricreare il cluster.

Operazioni preliminari

  • Se si usa l'interfaccia della riga di comando di Azure, questo articolo richiede l'interfaccia della riga di comando di Azure versione 2.34.1 o successiva. Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure.
  • Se si usa Azure PowerShell, questo articolo richiede Azure PowerShell versione 5.9.0 o successive. Eseguire Get-InstalledModule -Name Az per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare Azure PowerShell.
  • Per eseguire le operazioni di aggiornamento è necessario il ruolo Controllo degli accessi in base al ruolo Microsoft.ContainerService/managedClusters/agentPools/write. Per altre informazioni sui ruoli Controllo degli accessi in base al ruolo di Azure, vedere le operazioni del provider di risorse di Azure.
  • A partire dalla versione 1.30 kubernetes e dalla versione 1.27 LTS, le API beta verranno disabilitate per impostazione predefinita quando si esegue l'aggiornamento.

Avviso

Un aggiornamento del cluster AKS attiva un cordonamento e svuotamento dei nodi. Se è disponibile una quota di risorse di calcolo ridotta, l'aggiornamento potrebbe non riuscire. Per altre informazioni, vedere aumentare le quote.

Controlla la disponibilità di aggiornamenti per il cluster di Azure Kubernetes Service

Nota

Per rimanere aggiornati sulle correzioni, le versioni e gli aggiornamenti del servizio Azure Kubernetes, vedere lo strumento di rilevamento delle versioni del servizio Azure Kubernetes.

  • Verificare quali versioni di Kubernetes sono disponibili per il cluster usando il comando az aks get-upgrades.

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

    L'output di esempio seguente mostra la versione corrente come 1.26.6 ed elenca le versioni disponibili in upgrades:

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

Risolvere i problemi relativi ai messaggi di errore di aggiornamento del cluster del servizio Azure Kubernetes

L'output di esempio seguente indica che l'estensione appservice-kube non è compatibile con la versione dell'interfaccia della riga di comando di Azure (è necessaria almeno la versione 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.

Se si riceve questo output, è necessario aggiornare la versione dell'interfaccia della riga di comando di Azure. Il comando az upgrade è stato aggiunto nella versione 2.11.0 e non funziona con le versioni precedenti alla versione 2.11.0. È possibile aggiornare le versioni precedenti reinstallando l'interfaccia della riga di comando di Azure come descritto in Installare l'interfaccia della riga di comando di Azure. Se la versione dell'interfaccia della riga di comando di Azure è 2.11.0 o successiva, eseguire az upgrade per aggiornare l'interfaccia della riga di comando di Azure alla versione più recente.

Se l'interfaccia della riga di comando di Azure viene aggiornata e viene visualizzato l'output di esempio seguente, significa che non sono disponibili aggiornamenti:

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

Se non sono disponibili aggiornamenti, creare un nuovo cluster con una versione supportata di Kubernetes ed eseguire la migrazione dei carichi di lavoro dal cluster esistente al nuovo cluster. AKS non supporta l'aggiornamento di un cluster a una versione più recente di Kubernetes quando az aks get-upgrades indica che non sono disponibili aggiornamenti.

Aggiornare un cluster AKS

Durante il processo di aggiornamento del cluster, AKS esegue le operazioni seguenti:

  • Aggiungere un nuovo nodo del buffer (o tutti i nodi configurati in sovratensione massima) al cluster che esegue la versione di Kubernetes specificata.
  • Bloccare e svuotare uno dei nodi precedenti per ridurre al minimo le interruzioni per l'esecuzione delle applicazioni. Se si usa la sovratensione massima, blocca e svuota contemporaneamente tanti nodi quanti sono i nodi del buffer specificati.
  • Per i pod a esecuzione prolungata, è possibile configurare il timeout di svuotamento del nodo, che prevede un tempo di attesa personalizzato per la rimozione dei pod e la terminazione normale per nodo. Se non specificato, il valore predefinito è 30 minuti. Il valore di timeout minimo consentito è 5 minuti. Il limite massimo per il timeout di svuotamento è di 24 ore.
  • Quando il nodo vecchio è completamente svuotato, viene formattato per accettare la nuova versione e diventa il nodo buffer per il nodo seguente da aggiornare.
  • Facoltativamente, è possibile impostare un periodo di tempo di attesa tra lo svuotamento di un nodo e il passaggio al nodo successivo. Un breve intervallo consente di completare altre attività, ad esempio il controllo dell'integrità dell'applicazione da un dashboard di Grafana durante il processo di aggiornamento. È consigliabile un breve intervallo di tempo per il processo di aggiornamento, il più vicino possibile a 0 minuti. In caso contrario, un tempo di immersione del nodo superiore influisce sul tempo prima di individuare un problema. Il valore minimo di tempo di immersione è 0 minuti, con un massimo di 30 minuti. Se non è specificato, il valore predefinito è 0 minuti.
  • Questo processo viene ripetuto fino a quando non vengono aggiornati tutti i nodi del cluster.
  • Al termine del processo, l'ultimo nodo del buffer viene eliminato, mantenendo il numero di nodi dell'agente esistente e il bilanciamento della zona.

Nota

Se non viene specificata alcuna patch, il cluster esegue automaticamente l'aggiornamento alla patch GA più recente della versione secondaria specificata. Ad esempio, l'impostazione --kubernetes-version su 1.28 comporta l'aggiornamento del cluster a 1.28.9.

Per ulteriori informazioni, vedere Aggiornamenti supportati delle versioni secondarie di Kubernetes in AKS.

  1. Aggiornare il cluster usando il comando az aks upgrade.

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

  2. Verificare che l'aggiornamento sia riuscito usando il comando az aks show.

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

    L'output di esempio seguente mostra che ora nel cluster viene eseguita la versione 1.27.3:

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

Impostare il canale di aggiornamento automatico

È possibile impostare un canale di aggiornamento automatico nel cluster. Per ulteriori informazioni, vedere Aggiornamento automatico di un cluster AKS.

Personalizzare l'aggiornamento del picco di nodi

Importante

  • I picchi di nodi richiedono la quota sottoscrizione per il numero massimo di picchi per ogni operazione di aggiornamento richiesta. Ad esempio, un cluster con cinque pool di nodi, ognuno con un conteggio di quattro nodi, ha un totale di 20 nodi. Se ogni pool di nodi ha un valore di sovratensione massima di 50%, per completare l'aggiornamento è necessario un valore massimo di calcolo e una quota IP di 10 nodi (2 nodi * 5 pool).

  • L'impostazione di sovratensione massima in un pool di nodi è persistente. Gli aggiornamenti successivi di Kubernetes o della versione del nodo useranno questa impostazione. È possibile modificare il valore sovratensione massima per i pool di nodi in qualsiasi momento. Per i pool di nodi di produzione, è consigliabile impostare un max-surge del 33%.

  • Se si usa Azure CNI, verificare che nella subnet siano disponibili indirizzi IP per soddisfare i requisiti IP di Azure CNI.

Per impostazione predefinita, il servizio Azure Kubernetes configura gli aggiornamenti per aumentare le operazioni con un nodo aggiuntivo. Un valore predefinito di uno per le impostazioni del max surge consente ad AKS di ridurre al minimo le interruzioni del flusso di lavoro creando un nodo aggiuntivo prima del blocco e svuotamento delle applicazioni esistenti per sostituire un nodo versionato più vecchio. È possibile personalizzare il valore di sovratensione massima per ogni pool di nodi. Quando si aumenta il valore di sovratensione massima, il processo di aggiornamento viene completato più velocemente e si potrebbero verificare interruzioni durante il processo di aggiornamento.

Ad esempio, un valore max surge di 100% fornisce il processo di aggiornamento più rapido possibile, ma comporta anche lo svuotamento simultaneo di tutti i nodi nel pool di nodi. È possibile usare un valore superiore come questo per gli ambienti di test. Per i pool di nodi di produzione, è consigliabile un'max_surgeimpostazione di 33%.

Il servizio Azure Kubernetes accetta valori interi e un valore percentuale per il picco massimo. Ad esempio, un valore intero di 5 indica cinque nodi aggiuntivi da aumentare. Un valore percentuale di 50% indica un incremento pari alla metà del numero attuale di nodi nel pool. Le percentuali di aumento massimo possono essere un minimo di 1% e un massimo di 100%. Un valore percentuale viene arrotondato al numero di nodi più vicino. Se il valore di sovratensione massima è superiore al numero necessario di nodi da aggiornare, viene usato il numero di nodi da aggiornare per il valore di sovratensione massima. Durante un aggiornamento, il valore massimo di incremento può essere un minimo di 0 e un valore massimo pari al numero di nodi nel pool. È possibile impostare valori più grandi, ma non è possibile impostare il numero massimo di nodi usati per un picco massimo superiore al numero di nodi nel pool al momento dell'aggiornamento.

Impostare il valore massimo di picco

  • Impostare i valori di sovratensione massima per i pool di nodi nuovi o esistenti usando il comando az aks nodepool add o 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

Personalizzare i nodi non disponibili durante l'aggiornamento

Importante

  • maxSurge deve essere impostato su 0 affinché maxUnavailable possa essere impostato. I due valori non possono essere entrambi attivi contemporaneamente.
  • maxUnavailable non creerà nodi di picco durante il processo di aggiornamento. Invece, il servizio Azure Kubernetes isola nmaxUnavailable nodi alla volta ed espelle i pod verso altri nodi nel pool di agenti. Ciò potrebbe causare interruzioni del carico di lavoro se i pod non possono essere programmati.
  • maxUnavailable potrebbe causare più errori a causa di PodDisruptionBudgets (PDB) non soddisfatti, perché ci saranno meno risorse disponibili su cui programmare i pod. Vedere la risoluzione dei problemi per PodDisruptionBudgets per i suggerimenti di mitigazione in caso di errori durante l'uso di questa funzionalità.
  • Non è possibile impostare maxUnavailable nei pool di nodi di sistema.

Il servizio Azure Kubernetes può anche configurare gli aggiornamenti per non utilizzare un picco di nodi e aggiornare i nodi sul posto. Il maxUnavailable valore può essere usato per determinare il numero di nodi che possono essere delimitati e svuotati dai nodi del pool di nodi esistenti.

AKS accetta valori interi e un valore percentuale per maxUnavailable. Ad esempio, un valore intero indica 5 che cinque nodi verranno delimitati dai nodi esistenti nel pool di nodi. Un valore percentuale di 50% indica un maxUnavailable valore pari a metà del numero di nodi corrente nel pool. maxUnavailable valori percentuali possono avere un minimo di 1% e un massimo di 100%. Un valore percentuale viene arrotondato al numero di nodi più vicino. Durante un aggiornamento, maxUnavailable può essere un valore minimo di 0 e un valore massimo uguale al numero di nodi nel tuo pool.

Impostare il valore maxUnavailable

  • Impostare i valori maxUnvailable per i pool di nodi nuovi o esistenti usando il comando az aks nodepool add o 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

Impostare il valore di timeout di svuotamento del nodo

Potrebbe talvolta essere disponibile un carico di lavoro a esecuzione prolungata in un determinato pod e non è possibile riprogrammarlo in un altro nodo durante il runtime, ad esempio un carico di lavoro stateful a elevato utilizzo di memoria che deve terminare l'esecuzione. In questi casi, è possibile configurare un time-out di svuotamento del nodo che verrà rispettato da AKS nel flusso di lavoro di aggiornamento. Se non viene specificato alcun valore di timeout di svuotamento del nodo, il valore predefinito è 30 minuti. Il valore minimo di timeout di scarico consentito è di 5 minuti e il limite massimo di timeout di svuotamento è di 24 ore.

Se il valore di timeout di svuotamento è trascorso e i pod sono ancora in esecuzione, l'operazione di aggiornamento viene arrestata. Qualsiasi operazione PUT successiva riprenderà l'aggiornamento arrestato. È anche consigliabile configurare [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/] per i pod a esecuzione prolungata.

  • Impostare il timeout di svuotamento dei nodi per i pool di nodi nuovi o esistenti usando il az aks nodepool add comando o 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

Impostare il valore del tempo di immersione del nodo

Per consentire un intervallo di tempo di attesa tra lo svuotamento di un nodo e la reinstallazione dell'immagine su di esso prima di passare al nodo successivo, è possibile impostare il tempo di attesa su un valore compreso tra 0 e 30 minuti. Se non viene specificato alcun valore di tempo di immersione del nodo, il valore predefinito è 0 minuti.

  • Impostare il tempo di immersione dei nodi per i pool di nodi nuovi o esistenti usando il comando az aks nodepool add, az aks nodepool update o 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

Eseguire l'aggiornamento tramite una deriva significativa della versione

Quando si esegue l'aggiornamento da una versione non supportata di Kubernetes a una versione supportata, è importante testare i carichi di lavoro nella versione di destinazione. Anche se servizio Azure Kubernetes farà ogni sforzo per aggiornare il piano di controllo e il piano dati, non è garantito che i carichi di lavoro continueranno a funzionare correttamente. Se i tuoi carichi di lavoro si basano su API Kubernetes deprecate, e la piattaforma ha introdotto cambiamenti critici o comportamenti documentati nelle note di rilascio di AKS, questi devono essere risolti.

In queste situazioni è consigliabile testare i carichi di lavoro nella nuova versione e risolvere eventuali problemi di versione prima di eseguire un aggiornamento sul posto del cluster.

Un modello comune in questa situazione consiste nell'eseguire una distribuzione blu/verde dei carichi di lavoro modificati in un nuovo cluster che si trova in una versione di Kubernetes supportata e instradare le richieste al nuovo cluster.

Visualizzare gli eventi di aggiornamento

  • Visualizzare gli eventi di aggiornamento usando il comando kubectl get events.

    kubectl get events

    L'output di esempio seguente mostra alcuni degli eventi precedenti elencati durante un aggiornamento:

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

Passaggi successivi

Per informazioni su come configurare gli aggiornamenti automatici, vedere Configurare gli aggiornamenti automatici per un cluster del servizio Azure Kubernetes.

Per una descrizione dettagliata delle procedure consigliate per l'aggiornamento e altre considerazioni, vedere Linee guida per l'aggiornamento e le patch del servizio Azure Kubernetes.