Aggiorna le proprietà dell'istanza

Puoi utilizzare una singola richiesta da Google Cloud CLI o dall' API Compute Engine per aggiornare più proprietà dell'istanza e, facoltativamente, riavviare l'istanza, se necessario. Il metodo di aggiornamento gestisce la logica per la convalida delle proprietà dell'istanza aggiornate e garantisce che le risorse necessarie siano disponibili per completare l'aggiornamento nel modo corretto. Se la richiesta include proprietà non valide o se le risorse richieste non sono disponibili, la richiesta restituisce un errore e non apporta modifiche all'istanza. In questo modo, l'istanza viene protetta dagli aggiornamenti parziali ed evita che venga arrestata e non possa accedere alle risorse per riavviarsi.

Per aggiornare le interfacce di rete (networkInterfaces) di un'istanza, consulta invece Aggiorna le interfacce di rete di un'istanza.

Per aggiungere o rimuovere interfacce di rete dinamiche da un'istanza (anteprima), utilizza le seguenti procedure anziché aggiornare le proprietà dell'istanza:

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso a Google Cloud servizi e API. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il seguente comando: 

      gcloud init

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    2. Set a default region and zone.

    REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il seguente comando: 

      gcloud init

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud .

Limitazioni

  • Le richieste di aggiornamento delle istanze tramite gcloud CLI o l'API Compute Engine non supportano la semantica PATCH. La risorsa nella richiesta di aggiornamento deve includere tutte le proprietà dell'istanza. Le proprietà mancanti nella configurazione dell'istanza nella richiesta di aggiornamento sono considerate come eliminate dall'istanza.
  • Puoi aggiornare solo un elenco specifico di proprietà.
  • Non è possibile modificare la modalità single-tenancy delle istanze.
  • Puoi spostare un'istanza da una prenotazione all'altra, ma non puoi collegare o scollegare un'istanza da una prenotazione tramite il processo di aggiornamento.
  • Se all'istanza sono collegati dischi SSD locali, non puoi aggiornare le proprietà che richiedono il riavvio dell'istanza mentre questa è in esecuzione. Puoi eliminare e ricreare l'istanza oppure interrompere l'istanza, aggiornare le proprietà e riavviarla.
  • Puoi aggiornare la proprietà networkInterfaces di un'istanza, ma non puoi aggiungere o rimuovere NIC virtuali (vNIC) da un'istanza.
  • Se un'istanza utilizza risorse disponibili solo nell'API Compute Engine beta, devi utilizzare la versione corretta del metodo instances.update per aggiornare le proprietà. Ad esempio, se crei un'istanza utilizzando l'API Compute Engine beta e la configuri con una risorsa riconosciuta solo dall'API beta, devi utilizzare anche la versione beta del metodo instances.update per aggiornare le risorse. La versione 1 del metodo instances.update non riconosce le risorse beta utilizzate dall'istanza, quindi le elimina dalla configurazione dell'istanza durante il processo di aggiornamento. Questo comportamento si applica anche alle risorse dell'API alpha.

Autorizzazioni

Per aggiornare le istanze, devi disporre dell'autorizzazione compute.instances.update inclusa in diversi ruoli IAM (Identity and Access Management) esistenti. Devi inoltre disporre dell'autorizzazione per utilizzare le risorse che vuoi modificare nell'istanza. Ad esempio, per aggiungere un disco a un'istanza devi disporre delle seguenti autorizzazioni:

  • L'autorizzazione compute.instances.update sull'istanza che vuoi aggiornare.
  • L'autorizzazione compute.disks.use su un disco esistente o compute.disks.create su un progetto in cui vuoi creare un nuovo disco.

Best practice

Per avere la certezza che l'interfaccia di aggiornamento dell'istanza funzioni in modo ottimale, utilizza le seguenti best practice:

  • Se possibile, utilizza sempre la stessa versione dell'API Compute Engine per creare, configurare e aggiornare le istanze. In questo modo, puoi aggiornare e modificare le risorse dell'istanza se sono disponibili solo in una versione dell'API.
  • Sebbene sia possibile utilizzare il metodo instances.update per aggiornare le istanze in un gruppo di istanze gestite (MIG), per la maggior parte delle situazioni è meglio modificare il template di istanza del gruppo e implementare l'aggiornamento nel MIG.
  • Se aggiorni una risorsa utilizzata dall'istanza, utilizza il comando per aggiornare l'istanza della risorsa anziché le proprietà dell'istanza, ad esempio:
    • Puoi modificare i dischi con il metodo disks.update
    • Per modificare la rete utilizzata dall'istanza, puoi utilizzare il metodo instances.updateNetworkInterface, che non richiede l'arresto dell'istanza.

Proprietà che puoi aggiornare

Puoi modificare solo un insieme specifico di proprietà dell'istanza tramite il metodo update. Gli aggiornamenti di alcune proprietà richiedono il riavvio dell'istanza. Per evitare riavvii accidentali delle istanze, la richiesta deve definire quali azioni sono consentite sulle istanze. La richiesta può specificare una delle seguenti azioni:

  • NO_EFFECT: la richiesta di aggiornamento verifica se la richiesta è valida e se le risorse sono disponibili, ma non esegue l'aggiornamento. Utilizza questa azione per testare i comandi senza avviare aggiornamenti effettivi.
  • REFRESH: la richiesta di aggiornamento viene eseguita solo se le proprietà dell'istanza modificate non richiedono il riavvio dell'istanza. La richiesta restituisce un errore INFEASIBLE se è valida, ma è necessario riavviare.
  • RESTART: se l'aggiornamento richiede il riavvio dell'istanza, il sistema riavvierà l'istanza.

Le seguenti proprietà richiedono un riavvio (RESTART) per effettuare l'aggiornamento:

  • disks: dischi di avvio, compresi tutti i dischi (disks.deviceName)
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkInterfaces
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity: puoi aggiornare solo il modo in cui l'istanza utilizza le prenotazioni (reservationAffinity.consumeReservationType) come segue:
    • Dall'utilizzo di tutte le prenotazioni corrispondenti (ANY_RESERVATION) all'utilizzo di nessuna prenotazione (NO_RESERVATION)
    • Dall'utilizzo di nessuna prenotazione (NO_RESERVATION) all'utilizzo di tutte le prenotazioni corrispondenti (ANY_RESERVATION)
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Per aggiornare le seguenti proprietà è sufficiente un aggiornamento (REFRESH):

  • canIpForward
  • deletionProtection
  • description
  • disks: proprietà dei dischi non di avvio, esclusa deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Aggiorna le proprietà dell'istanza

Aggiorna le istanze seguendo questa procedura:

  1. Esporta le proprietà di configurazione dell'istanza esistenti.
  2. Modifica le proprietà della configurazione dell'istanza.
  3. Esegui una richiesta di test specificando NO_EFFECT come azione più invasiva. La risposta indica i campi non validi nella configurazione dell'istanza e l'azione richiesta per applicare le modifiche.
  4. Se la configurazione è accettabile, richiedi un aggiornamento dell'istanza e specifica l'azione più invasiva accettabile per l'aggiornamento dell'istanza.

Il sistema avvia la procedura di aggiornamento solo se la richiesta soddisfa i seguenti requisiti:

  • La proprietà fingerprint dell'istanza nella richiesta deve corrispondere al fingerprint dell'istanza che stai aggiornando. In questo modo le richieste di aggiornamento simultanee sulla stessa istanza non si sovrascrivono.
  • Le proprietà nella richiesta di aggiornamento devono essere valide.
  • Le risorse richieste devono essere disponibili.
  • Se in base alle proprietà nella richiesta l'istanza deve riavviarsi, la richiesta deve specificare RESTART come azione consentita.

Se i requisiti sono soddisfatti, il sistema avvia la procedura di aggiornamento dell'istanza. In caso contrario, il sistema non apporta modifiche all'istanza esistente o alla relativa configurazione.

Puoi avviare gli aggiornamenti utilizzando gcloud CLI o l'API Compute Engine.

gcloud

  1. Utilizza il comando instances export per esportare le proprietà dell'istanza esistenti:

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    Sostituisci quanto segue:

    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per questa istanza.
    • FILE_PATH: il percorso di output in cui vuoi salvare il file di configurazione dell'istanza sulla tua workstation locale.

  2. Utilizza un editor di testo per modificare una o più proprietà nel file di configurazione dell'istanza esportato. Per scoprire quali proprietà puoi aggiornare, consulta l'elenco delle proprietà aggiornabili in questo documento. Ad esempio, per modificare il tipo di macchina dell'istanza, modifica la proprietà machineType:

    ...
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
...

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto per questa richiesta
    • ZONE: la zona per questa istanza.
    • MACHINE_TYPE: il tipo di macchina dell'istanza, ad esempio n1-standard-2.

  3. Utilizza il comando instances update-from-file per eseguire un aggiornamento di prova dell'istanza target. Specifica il --most-disruptive-allowed-action=NO_EFFECT flag. La risposta identifica le proprietà configurate in modo errato e indica se è necessaria un'azione RESTART o REFRESH per applicare l'aggiornamento.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    Sostituisci quanto segue:

    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per questa istanza.
    • FILE_PATH: il percorso del file di configurazione dell'istanza modificato sulla workstation locale.

  4. Utilizza il comando instances update-from-file per aggiornare l'istanza target. Se stai aggiornando una proprietà che richiede il riavvio dell'istanza, includi il flag --most-disruptive-allowed-action=RESTART. Se le proprietà non richiedono il riavvio, specifica il flag --most-disruptive-allowed-action=REFRESH. Per sapere quali proprietà richiedono il riavvio, consulta l'elenco delle proprietà aggiornabili in questo documento.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    Sostituisci quanto segue:

    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per questa istanza.
    • FILE_PATH: il percorso del file di configurazione dell'istanza modificato sulla workstation locale.
    • ALLOWED_ACTION: definisce quanto può essere invasivo l'aggiornamento. Specifica RESTART per consentire un riavvio completo dell'istanza. Specifica REFRESH per aggiornare l'istanza solo se le proprietà modificate non richiedono il riavvio dell'istanza.

Se la richiesta di aggiornamento è valida e le risorse richieste sono disponibili, inizia il processo di aggiornamento dell'istanza. Puoi monitorare lo stato dell'operazione visualizzando gli audit log. Se l'aggiornamento richiede un riavvio e il comando consente un RESTART, l'istanza viene riavviata per applicare le modifiche.

REST

  1. Utilizza il metodo instances.get nell'API Compute Engine per esportare le proprietà dell'istanza esistenti:

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto per questa richiesta
    • ZONE: la zona per questa istanza
    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare

    Questa richiesta restituisce una definizione della risorsa dell'istanza.

  2. Nella risposta, modifica le proprietà della risorsa dell'istanza. Per scoprire quali proprietà sono aggiornabili, consulta l'elenco delle proprietà aggiornabili in questo documento. Ad esempio, per modificare il tipo di macchina dell'istanza, modifica la proprietà machineType. Puoi modificare più proprietà.

    {
  ...
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ...
}

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto per questa richiesta
    • ZONE: la zona per questa istanza
    • MACHINE_TYPE: il tipo di macchina dell'istanza, ad esempio n1-standard-2

  3. Utilizza il metodo instances.update nell'API Compute Engine e specifica il parametro di query mostDisruptiveAllowedAction=NO_EFFECT per eseguire un aggiornamento di test dell'istanza target. La risposta identifica le proprietà configurate in modo errato e indica se è necessaria un'azione RESTART o REFRESH per applicare l'aggiornamento.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=NO_EFFECT

{
  ...
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ...
}

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto per questa richiesta
    • ZONE: la zona per questa istanza
    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare

  4. Utilizza il metodo instances.update nell'API Compute Engine per aggiornare l'istanza target. Se stai aggiornando una proprietà che richiede il riavvio di un'istanza, includi il parametro di query mostDisruptiveAllowedAction=RESTART per indicare che l'istanza può essere riavviata durante l'aggiornamento. Se le proprietà non richiedono un riavvio, specifica il parametro di query mostDisruptiveAllowedAction=REFRESH. Per sapere quali proprietà richiedono il riavvio, consulta l'elenco delle proprietà aggiornabili in questo documento. Includi il corpo completo della risorsa istanza che hai modificato. Nel seguente esempio, il corpo modifica il tipo di macchina in n1-standard-2:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=ALLOWED_ACTION

{
  ...
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ...
}

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto per questa richiesta
    • ZONE: la zona per questa istanza
    • INSTANCE_NAME: il nome dell'istanza che vuoi esportare.
    • ALLOWED_ACTION: definisce quanto può essere invasivo l'aggiornamento. Specifica RESTART per consentire un riavvio completo dell'istanza. Specifica REFRESH per aggiornare l'istanza solo se le proprietà modificate non richiedono il riavvio dell'istanza.

Se la richiesta di aggiornamento è valida e le risorse richieste sono disponibili, inizia il processo di aggiornamento dell'istanza. Puoi monitorare lo stato dell'operazione visualizzando gli audit log. Se l'aggiornamento richiede un riavvio e il comando consente un RESTART, l'istanza viene riavviata per applicare le modifiche.

Passaggi successivi