Condividi tramite

Aggiornare un cluster del servizio Azure Kubernetes

  • Articolo

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 del servizio Azure Kubernetes.

Aggiornamenti della versione di Kubernetes

Quando si aggiorna un cluster del servizio Azure Kubernetes supportato, non è possibile ignorare le versioni secondarie di Kubernetes. È necessario eseguire tutti gli aggiornamenti in sequenza in base al numero di versione principale. 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 versione non è aggiornata in modo significativo, è consigliabile 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 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 del servizio Azure Kubernetes attiva un processo di blocco 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.

Verificare la presenza di aggiornamenti disponibili per il cluster del servizio Azure Kubernetes

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. Il servizio Azure Kubernetes 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 del servizio Azure Container

Durante il processo di aggiornamento del cluster, il servizio Azure Kubernetes 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 consente il tempo di attesa personalizzato per la rimozione dei pod e la terminazione normale per ogni nodo. Se non specificato, il valore predefinito è 30 minuti. Il valore minimo di timeout consentito è 5 minuti.
  • Quando il nodo precedente è completamente svuotato, viene ricreata l'immagine per ricevere la nuova versione e diventa il nodo del 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 altre informazioni, vedere Aggiornamenti delle versioni secondarie di Kubernetes supportati nel servizio Azure Kubernetes.

  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 altre informazioni, vedere Aggiornamento automatico di un cluster del servizio Azure Kubernetes.

Personalizzare l'aggiornamento del picco di nodi

Importante

  • I picchi di nodo richiedono la quota di sottoscrizione per il numero massimo di operazioni di aggiornamento richieste. 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.

Il servizio Azure Kubernetes configura gli aggiornamenti per aumentare le operazioni con un nodo aggiuntivo per impostazione predefinita. Un valore predefinito di uno per le impostazioni di sovratensione massima consente al servizio Azure Kubernetes di ridurre al minimo le interruzioni del carico di lavoro creando un nodo aggiuntivo prima del blocco/svuotamento delle applicazioni esistenti per sostituire un nodo con controllo delle versioni precedente. È 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 di sovratensione massima del 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, ad esempio questo per gli ambienti di test. Per i pool di nodi di produzione, è consigliabile impostare max_surge del 33%.

Il servizio Azure Kubernetes accetta valori interi e un valore percentuale per il picco massimo. Un numero intero, ad esempio 5, indica cinque nodi aggiuntivi da aumentare. Un valore pari al 50% indica un valore di aumento della metà del numero di nodi corrente nel pool. I valori percentuali di sovratensione massima possono essere minimo 1% e massimo 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 max surge può essere minimo 1 e un valore massimo uguale al numero di nodi nel pool di nodi. È 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

Impostare il valore di timeout di svuotamento del nodo

A volte, potrebbe essere disponibile un carico di lavoro a esecuzione prolungata in un determinato pod e non può essere riprogrammato in un altro nodo durante il runtime, ad esempio un carico di lavoro con stato intensivo di memoria che deve terminare l'esecuzione. In questi casi, è possibile configurare un timeout di svuotamento del nodo che il servizio Azure Kubernetes rispetterà 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 svuotamento consentito è 5 minuti.

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 che i pod a esecuzione prolungata configurino [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/].

  • Impostare il timeout di svuotamento dei nodi per i pool di nodi nuovi o esistenti usando il comando az aks nodepool add o az aks nodepool update.

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

# Update drain timeout for an existing node pool
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --drain-timeout 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 il nuovo passaggio dell’immagine al nodo successivo, è possibile impostare il tempo di immersione 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

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.