Creare e gestire una specifica di immagine preparata (PIS) in Servizio Azure Kubernetes (AKS) (anteprima)

Prepared Image Specification (PIS) consente di definire immagini di nodo preconfigurate che includono le immagini container e le personalizzazioni necessarie. AKS crea l'immagine preparata una sola volta e la riutilizza durante il provisioning dei nodi, riducendo il tempo di avvio per le successive operazioni di scalabilità. Per altre informazioni su come funziona Prepared Image Specification e su quando usarla, vedere Prepared Image Specification in AKS (anteprima).

Questo articolo descrive come creare e gestire un PIS in AKS.

Importante

Le funzionalità in anteprima di AKS sono disponibili in modalità self-service, su base volontaria. Le anteprime vengono fornite "così come sono" e "come disponibili" e sono escluse dai contratti di servizio e dalla garanzia limitata. Le anteprime di AKS sono coperte solo parzialmente dall'assistenza clienti nei limiti del possibile. Di conseguenza, queste funzionalità non sono destinate all'uso in produzione. Per altre informazioni, vedere gli articoli di supporto seguenti:

Prerequisiti

Un cluster AKS esistente che esegue una versione supportata di Kubernetes. Se non ne hai uno, vedi Creare un cluster AKS.
Interfaccia a riga di comando di Azure v. 2.85.0 o successiva. Eseguire az --version per trovare la versione in uso. Se è necessario installare o aggiornare, vedere Installare interfaccia della riga di comando di Azure.
Sono necessarie le autorizzazioni appropriate di Azure RBAC per creare e gestire le risorse di AKS nel tuo gruppo di risorse.
Le immagini dei contenitori devono essere accessibili dal cluster AKS. Se usi Registro Azure Container (ACR), assicurati che sia integrato con il tuo cluster AKS.
Estensione dell’interfaccia della riga di comando aks-preview versione 21.0.0b5 o successiva. Se non è installata, vedi Installare l'estensione CLI aks-preview.
Flag di funzionalità AKSPreparedImageSpecificationPreview registrato nella sottoscrizione. Se non è stato registrato, vedere Registrare il flag di funzionalità AKSPreparedImageSpecificationPreview.

Limitations

Durante l'anteprima vengono applicate le limitazioni seguenti:

Disponibile nelle regioni pubbliche di Azure, esclusi i cloud sovrani e gli ambienti isolati.
I sistemi operativi supportati includono Ubuntu, Azure Linux e Windows.
Gli script personalizzati possono causare errori durante la creazione dell'immagine o lo scale-up.
Potrebbe essere necessario ricreare le specifiche esistenti durante la modifica.

Installare l'estensione CLI `aks-preview`

Installare l'estensione aks-preview dell'interfaccia della riga di comando usando il comando az extension add.

az extension add --name aks-preview

Aggiornare l'estensione per assicurarsi che sia installata la versione più recente usando il az extension update comando .

az extension update --name aks-preview

Registrare il flag di funzionalità `AKSPreparedImageSpecificationPreview`

Registra il flag di funzionalità AKSPreparedImageSpecificationPreview nella tua sottoscrizione usando il comando az feature register.
```
az feature register \
  --namespace Microsoft.ContainerService \
  --name AKSPreparedImageSpecificationPreview
```

Verificare lo stato della registrazione usando il az feature show comando .

az feature show \
  --namespace Microsoft.ContainerService \
  --name AKSPreparedImageSpecificationPreview

Dopo aver registrato il flag di funzionalità, aggiornare la registrazione del provider di risorse Microsoft.ContainerService usando il comando az provider register.
```
az provider register --namespace Microsoft.ContainerService
```

Creare una specifica dell'immagine preparata (PIS)

Creare una specifica di immagine preparata di base

Creare un piS usando il az aks prepared-image-specification create comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a basic Prepared Image Specification
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --location $LOCATION

Creare una specifica di immagine preparata con immagini memorizzate nella cache

Creare una PIS che precarichi nella cache le immagini del contenitore usando il comando az aks prepared-image-specification create.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a Prepared Image Specification with cached images
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --container-images \
        myacr.azurecr.io/model-server:v1 \
        myacr.azurecr.io/inference:v1

Creare una specifica di immagine preparata usando script personalizzati

Creare un PIS che esegue script di personalizzazione durante la creazione dell'immagine usando il comando az aks prepared-image-specification create.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
PIS_NAME=<your-pis-name>
LOCATION=<location>
PIS_VERSION=v1

# Create a Prepared Image Specification using custom scripts
az aks prepared-image-specification create \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --version $PIS_VERSION \
    --customization-scripts @scripts.json

Creare un cluster o un pool di nodi utilizzando una specifica di immagine preparata

Dopo aver creato un piS, è possibile farvi riferimento quando si crea o si aggiorna un cluster o un pool di nodi. È necessario l'ID risorsa della versione dell'immagine preparata.

Creare un cluster utilizzando un PIS

Ottieni l'ID della risorsa della versione PIS utilizzando il comando az aks prepared-image-specification version show.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Get the PIS version resource ID
PIS_VERSION_ID=$(az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION \
    --query id -o tsv)

Creare un nuovo cluster AKS che faccia riferimento all'immagine preparata usando il comando az aks create con il parametro --prepared-image-specification-id.

# Set environment variables
CLUSTER_NAME=<your-aks-cluster-name>

# Create a new AKS cluster using the prepared image
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --prepared-image-specification-id $PIS_VERSION_ID \
    --generate-ssh-keys

Crea un pool di nodi utilizzando un PIS

Ottieni l'ID della risorsa della versione PIS utilizzando il comando az aks prepared-image-specification version show.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Get the PIS version resource ID
PIS_VERSION_ID=$(az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION \
    --query id -o tsv)

Creare un nuovo pool di nodi che faccia riferimento all'immagine preparata usando il az aks nodepool add comando con il --prepared-image-specification-id parametro .

# Set environment variables
CLUSTER_NAME=<your-aks-cluster-name>

# Create a new node pool using the prepared image
az aks nodepool add \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --prepared-image-specification-id $PIS_VERSION_ID

Verifica che il pool di nodi stia utilizzando il PIS utilizzando il comando az aks nodepool show.

az aks nodepool show \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --query "{state:provisioningState, pisId:preparedImageSpecificationId}"

Gestire le specifiche delle immagini preparate

Elencare le specifiche delle immagini preparate

Elencare tutte le specifiche di immagine preparate in un gruppo di risorse usando il az aks prepared-image-specification list comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>

# List all Prepared Image Specifications in the resource group
az aks prepared-image-specification list --resource-group $RESOURCE_GROUP

Visualizzare una determinata specifica dell'immagine preparata

Ottenete i dettagli di una specifica di immagine preparata usando il comando az aks prepared-image-specification show.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Show the details of the Prepared Image Specification
az aks prepared-image-specification show \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME

Aggiornare i metadati delle specifiche dell'immagine preparata

Esistono due concetti relativi alle risorse: la risorsa PIS e le versioni pis. L'aggiornamento dei metadati pis, ad esempio i tag, aggiorna la risorsa PIS e non modifica l'immagine o gli script della versione a cui si fa riferimento. Per modificare le immagini o gli script del contenitore, creare una nuova versione di PIS e aggiornare il pool di nodi per fare riferimento all'ID versione pis.

È possibile aggiornare i metadati, ad esempio i tag, in una specifica di immagine preparata esistente usando il az aks prepared-image-specification update comando . Per modificare le immagini o gli script del contenitore, creare invece una nuova versione.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Update the Prepared Image Specification metadata
az aks prepared-image-specification update \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME \
    --tags environment=prod

Elencare tutte le versioni di una specifica di immagine preparata

Elencare tutte le versioni di una specifica di immagine preparata usando il az aks prepared-image-specification version list comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# List all versions of the Prepared Image Specification
az aks prepared-image-specification version list \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME

Visualizzare una versione specifica di una specifica di immagine preparata

Ottieni i dettagli di una versione specifica usando il comando az aks prepared-image-specification version show con il parametro --name impostato sulla versione PIS.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=v1

# Show the details of the specific version of the Prepared Image Specification
az aks prepared-image-specification version show \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION

Elenca i pool di nodi che utilizzano una specifica dell'immagine preparata

Per trovare tutti i pool di nodi in un cluster che fanno riferimento a una specifica di immagine preparata, usare il az aks nodepool list comando con un filtro JMESPath.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>

# List all node pools in the cluster that reference a Prepared Image Specification
az aks nodepool list \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --query "[?preparedImageSpecificationId != null]"

Aggiornare la versione della specifica dell'immagine preparata

Quando le immagini di base, le dipendenze o le personalizzazioni cambiano, creare una nuova versione e aggiornare i pool di nodi per farvi riferimento. Il flusso di lavoro consigliato è:

Creare una nuova versione con immagini o script del contenitore aggiornati.
Convalidare la nuova versione in un pool di nodi non di produzione.

Aggiornare i pool di nodi di produzione per fare riferimento alla nuova versione.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
NEW_PIS_VERSION_ID=<new-pis-version-resource-id>

# Update a node pool to reference a new PIS version using the `az aks nodepool update` command
az aks nodepool update \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name userpool \
    --prepared-image-specification-id $NEW_PIS_VERSION_ID

Pulire le immagini inutilizzate per l'ottimizzazione dei costi.

Aggiornamenti della versione di AKS

Quando si aggiorna la versione di Kubernetes, AKS rigenera automaticamente il VHD preparato per la versione PIS di riferimento. Non è necessario creare una nuova versione di PIS per un aggiornamento della versione di Kubernetes. È consigliabile creare una nuova versione di PIS quando il contenuto pis, ad esempio immagini del contenitore o script, cambia.

Verificare la disponibilità di aggiornamenti usando il az aks get-upgrades comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>

# Check for available upgrades
az aks get-upgrades \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME

Aggiornare il cluster usando il az aks upgrade comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
KUBERNETES_VERSION=<new-kubernetes-version>

# Upgrade the cluster to the new Kubernetes version
az aks upgrade \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --kubernetes-version $KUBERNETES_VERSION

Importante

Creare e convalidare una nuova versione della specifica dell'immagine preparata che supporti le nuove versioni di Kubernetes e delle immagini dei nodi prima di aggiornare i pool di nodi di produzione.

Aggiornare un pool di nodi specifico usando il az aks nodepool upgrade comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>
NODE_POOL_NAME=<your-node-pool-name>

# Upgrade the node pool to the new Kubernetes version
az aks nodepool upgrade \
    --resource-group $RESOURCE_GROUP \
    --cluster-name $CLUSTER_NAME \
    --name $NODE_POOL_NAME

Rimuovere una specifica di immagine preparata da un pool di nodi

Per smettere di usare una specifica dell'immagine preparata in un pool di nodi, aggiorna il pool di nodi usando il comando az aks nodepool update con una stringa vuota per il parametro --prepared-image-specification-id.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
CLUSTER_NAME=<your-aks-cluster-name>

# Remove the Prepared Image Specification from the node pool
az aks nodepool update \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name userpool \
  --prepared-image-specification-id ""

Eliminare una versione della specifica dell'immagine preparata

Eliminare una versione specifica usando il az aks prepared-image-specification version delete comando .

Importante

Non eliminare una versione PIS referenziata da un pool di nodi. Invece, è necessario aggiornare il pool di nodi per rimuovere PIS o fare riferimento a un'altra versione di PIS. L'eliminazione di una versione a cui viene fatto riferimento può impedire ad AKS di ricompilare correttamente o eseguire il rollout dell'immagine preparata.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>
PIS_VERSION=<your-pis-version>

# Delete the specific version of the Prepared Image Specification
az aks prepared-image-specification version delete \
    --resource-group $RESOURCE_GROUP \
    --pis-name $PIS_NAME \
    --name $PIS_VERSION

Eliminare una specifica di immagine preparata

Eliminare un’intera risorsa della specifica dell'immagine preparata usando il comando az aks prepared-image-specification delete.

Importante

Prima di eliminare una risorsa pis, assicurarsi che nessun pool di nodi faccia riferimento a una delle relative versioni. Se si trovano riferimenti, rimuoverli o aggiornarli prima di eliminare la risorsa PIS. L'eliminazione di una PIS a cui viene fatto riferimento può impedire ad AKS di ricompilare correttamente o eseguire il rollout dell'immagine preparata.

# Set environment variables
RESOURCE_GROUP=<your-resource-group>
PIS_NAME=<your-pis-name>

# Delete the Prepared Image Specification
az aks prepared-image-specification delete \
    --resource-group $RESOURCE_GROUP \
    --name $PIS_NAME

Monitoraggio delle prestazioni della specifica dell'immagine preparata

Per valutare se PIS riduce la latenza di provisioning nel tuo ambiente, monitorare le metriche seguenti:

Durata del provisioning dei nodi e tempo per essere pronti: confronta con i nodi che non utilizzano un'immagine preparata.
Tempo di completamento dello scale-out: tempo che intercorre dall’attivazione del ridimensionamento automatico al raggiungimento dello stato Ready da parte dei nodi.
Durata della compilazione dell’immagine e percentuale di successo della compilazione: monitorare l’integrità della pipeline di preparazione delle immagini.
Tempo di avvio dei pod e durata del pull delle immagini del contenitore: verificare che la memorizzazione preventiva nella cache delle immagini venga usata in modo efficace.

Risolvere i problemi della specifica preconfigurata dell'immagine

Gli errori correlati al piS devono includere il motivo dell'errore e molti errori possono provenire da script personalizzati. Se la creazione o il ridimensionamento del pool di nodi non riesce dopo l'aggiunta di PIS, è necessario esaminare i log della compilazione dell'immagine/dello script personalizzato e convalidare lo script prima di creare una nuova versione o aggiornare il riferimento del pool di nodi.

Impossibile creare l'immagine

Annotazioni

Quando uno script di personalizzazione ha esito negativo durante la creazione dell'immagine, AKS dealloca la VM di compilazione anziché eliminarla, in modo che il cliente possa avviarla ed eseguire il debug. Nelle successive ricompilazioni della PIS, AKS elimina e ricrea il set di scalabilità di macchine virtuali e le risorse di compilazione.

Se il PIS non riesce a generare l'immagine preparata, verificare quanto segue:

Script di personalizzazione non validi o malformati.
Errori di autenticazione del registro container: verificare che il cluster AKS disponga delle autorizzazioni per eseguire il pull dai registri specificati.
Autorizzazioni Azure RBAC mancanti nel gruppo di risorse o nel registro.
Tipi di personalizzazione non supportati per il sistema operativo di destinazione.

La creazione del pool di nodi non riesce

Se un pool di nodi che fa riferimento a un PIS non viene creato, verifica quanto segue:

L'ID della versione PIS è valido e la versione esiste nella stessa regione.
La sottoscrizione ha una quota sufficiente per lo SKU di macchina virtuale richiesto.
Lo SKU della macchina virtuale richiesto è supportato dall'immagine preparata.
L'area geografica supporta la funzionalità PIS in anteprima.

Le operazioni di scalabilità non sono più rapide

Se non si rileva una riduzione dei tempi di provisioning, verificare quanto segue:

Le immagini del contenitore che si desidera velocizzare sono incluse nella versione della PIS.
Il pool di nodi fa riferimento alla versione corretta.
I nuovi nodi si avviano dall'immagine preparata, non dall'immagine del nodo AKS di base.
Il collo di bottiglia è il tempo di pull delle immagini del contenitore, non l’avvio del carico di lavoro o un’altra operazione di inizializzazione.

Pulire le risorse

Se in questo articolo sono state create risorse a scopo di test, eliminarle al termine per evitare addebiti in corso. Sono inclusi le versioni PIS, le risorse PIS, i pool di nodi di test e i cluster AKS di test.

Per eliminare il gruppo di risorse e tutte le risorse in esso contenute, usare il az group delete comando .

# Set environment variables
RESOURCE_GROUP=<your-resource-group>

# Delete the resource group and all resources in it
az group delete \
    --name $RESOURCE_GROUP \
    --yes \
    --no-wait

Per altre informazioni su Prepared Image Specification, vedi Prepared Image Specification in AKS (anteprima).

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-07-24

Creare e gestire una specifica di immagine preparata (PIS) in Servizio Azure Kubernetes (AKS) (anteprima)

Prerequisiti

Limitations

Installare l'estensione CLI aks-preview

Registrare il flag di funzionalità AKSPreparedImageSpecificationPreview

Creare una specifica dell'immagine preparata (PIS)

Creare una specifica di immagine preparata di base

Creare una specifica di immagine preparata con immagini memorizzate nella cache

Creare una specifica di immagine preparata usando script personalizzati

Creare un cluster o un pool di nodi utilizzando una specifica di immagine preparata

Creare un cluster utilizzando un PIS

Crea un pool di nodi utilizzando un PIS

Gestire le specifiche delle immagini preparate

Elencare le specifiche delle immagini preparate

Visualizzare una determinata specifica dell'immagine preparata

Aggiornare i metadati delle specifiche dell'immagine preparata

Elencare tutte le versioni di una specifica di immagine preparata

Visualizzare una versione specifica di una specifica di immagine preparata

Elenca i pool di nodi che utilizzano una specifica dell'immagine preparata

Aggiornare la versione della specifica dell'immagine preparata

Aggiornamenti della versione di AKS

Rimuovere una specifica di immagine preparata da un pool di nodi

Eliminare una versione della specifica dell'immagine preparata

Eliminare una specifica di immagine preparata

Monitoraggio delle prestazioni della specifica dell'immagine preparata

Risolvere i problemi della specifica preconfigurata dell'immagine

Impossibile creare l'immagine

La creazione del pool di nodi non riesce

Le operazioni di scalabilità non sono più rapide

Pulire le risorse

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive

Installare l'estensione CLI `aks-preview`

Registrare il flag di funzionalità `AKSPreparedImageSpecificationPreview`