Aggiorna proprietà 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 per garantire che siano disponibili le risorse necessarie per completare correttamente l'aggiornamento. Se la richiesta include proprietà non valide o se le risorse richieste non sono disponibili, restituisce un errore e non apporta modifiche all'istanza. In questo modo protegge l'istanza da aggiornamenti parziali e protegge l'istanza dall'arresto e dall'impossibilità di accedere alle risorse per il riavvio.

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale viene verificata l'identità per l'accesso ai servizi e alle API Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti in Compute Engine nel seguente modo.

    Seleziona la scheda relativa a come prevedi di utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi e alle API di Google Cloud, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI, quindi initialize eseguendo questo comando: 

      gcloud init
    2. Imposta una regione e una zona predefinite.

    REST

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

      Installa Google Cloud CLI, quindi initialize eseguendo questo comando: 

      gcloud init

Limitazioni

  • Le richieste di aggiornamento delle istanze tramite gcloud CLI o l'API Compute Engine non supportano la semantica di PATCH. La risorsa istanza nella richiesta di aggiornamento deve includere tutte le proprietà dell'istanza. Le proprietà mancanti nella configurazione dell'istanza nella richiesta di aggiornamento sono considerate eliminate dall'istanza.
  • Puoi aggiornare solo un elenco specifico di proprietà.
  • La modifica delle istanze da e verso la modalità single-tenant non è supportata.
  • Puoi modificare un'istanza da una prenotazione a un'altra, ma non puoi collegare o scollegare un'istanza da una prenotazione utilizzando il processo di aggiornamento.
  • Se all'istanza è collegato un SSD locale, non puoi aggiornare le proprietà che richiedono il riavvio dell'istanza. Devi eliminare e poi ricreare l'istanza. Assicurati di eseguire la migrazione dei dati critici dall'SSD locale a un disco permanente o a un'altra VM prima di eliminare la VM.
  • Se un'istanza utilizza risorse disponibili solo nell'API Compute Engine beta, devi utilizzare la versione corretta del metodo instances.update per aggiornare queste 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 queste risorse. La versione v1 del metodo instances.update non riconosce le risorse beta utilizzate dall'istanza, perciò le elimina dalla configurazione dell'istanza durante il processo di aggiornamento. Questo si applica anche alle risorse nell'API alpha.

Autorizzazioni

Devi avere l'autorizzazione compute.instances.update per aggiornare le istanze. Questa autorizzazione è inclusa in diversi ruoli IAM (Identity and Access Management) esistenti. Devi anche avere l'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 per l'istanza che vuoi aggiornare.
  • Autorizzazione compute.disks.use per un disco esistente o compute.disks.create in un progetto in cui vuoi creare un nuovo disco.

best practice

Per assicurarti che l'interfaccia di aggiornamento delle istanze funzioni nel modo più efficace per te, utilizza le seguenti best practice:

  • Se possibile, utilizza sempre la stessa versione dell'API Compute Engine per creare, impostare e aggiornare le istanze. Questo garantisce la possibilità di aggiornare e modificare qualsiasi risorsa dell'istanza, se è disponibile solo in una versione dell'API.
  • Anche se puoi utilizzare il metodo instances.update per aggiornare le istanze in un gruppo di istanze gestite, nella maggior parte dei casi è meglio modificare il modello di istanza del gruppo e implementare l'aggiornamento al gruppo di istanze gestite.

Proprietà che puoi aggiornare

Puoi modificare solo un insieme specifico di proprietà dell'istanza tramite il metodo di aggiornamento. Gli aggiornamenti ad alcune proprietà richiedono il riavvio dell'istanza. Per evitare riavvii accidentali delle istanze, la richiesta deve definire l'azione che è possibile eseguire sulle istanze. La tua richiesta può specificare una delle seguenti azioni:

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

Proprietà che richiedono l'aggiornamento di RESTART:

  • reservationAffinity
  • disks - Dischi di avvio
    • disks.deviceName - Tutti i dischi
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Proprietà che richiedono solo REFRESH per l'aggiornamento:

  • canIpForward
  • deletionProtection
  • description
  • disks: proprietà del disco non di avvio, tranne deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Aggiorna proprietà 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 prova specificando NO_EFFECT come azione più invasiva. La risposta indica campi non validi nella configurazione dell'istanza e indica l'azione richiesta per applicare le modifiche.
  4. Se la configurazione è accettabile, richiedi un aggiornamento dell'istanza e specifica l'azione più di disturbo accettabile per l'aggiornamento dell'istanza.

Il sistema avvia il processo di aggiornamento solo se la tua richiesta soddisfa i seguenti requisiti:

  • La proprietà dell'istanza fingerprint nella richiesta deve corrispondere a fingerprint dell'istanza che stai aggiornando. In questo modo, le richieste di aggiornamento simultanee sulla stessa istanza non si sovrascrivono a vicenda.
  • Le proprietà nella richiesta di aggiornamento devono essere valide.
  • Le risorse che hai richiesto devono essere disponibili.
  • Se le proprietà della richiesta richiedono il riavvio dell'istanza, nella richiesta deve specificare RESTART come azione consentita.

Se i requisiti sono soddisfatti, il sistema avvia il processo di aggiornamento dell'istanza. In caso contrario, il sistema non apporta modifiche all'istanza esistente o alla sua 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 da esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per l'istanza.
    • FILE_PATH: il percorso di output in cui vuoi salvare il file di configurazione dell'istanza sulla workstation locale.

  2. Utilizza un editor di testo per modificare una o più proprietà nel file di configurazione dell'istanza esportato. Per sapere quali proprietà puoi aggiornare, consulta l'elenco di proprietà aggiornabili. Ad esempio, per cambiare 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 l'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 di destinazione. Specifica il flag --most-disruptive-allowed-action=NO_EFFECT. 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 da esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per l'istanza.
    • FILE_PATH: il percorso del file di configurazione dell'istanza modificata sulla workstation locale.

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

    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 da esportare.
    • PROJECT_ID: l'ID progetto per questa richiesta.
    • ZONE: la zona per l'istanza.
    • FILE_PATH: il percorso del file di configurazione dell'istanza modificata sulla workstation locale.
    • ALLOWED_ACTION: definisce il potenziale invasivo dell'aggiornamento. Specifica RESTART per consentire il 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, viene avviato il processo di aggiornamento dell'istanza. Puoi monitorare lo stato di questa operazione visualizzando gli audit log. Se l'aggiornamento richiede un riavvio e il comando consente un valore RESTART, l'istanza si riavvia per applicare le modifiche.

REST

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

    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 l'istanza.
    • INSTANCE_NAME: il nome dell'istanza da esportare.

    Questa richiesta restituisce una definizione della risorsa istanza.

  2. Nella risposta, modifica le proprietà della risorsa dell'istanza. Per sapere quali proprietà sono aggiornabili, consulta l'elenco delle proprietà aggiornabili. Ad esempio, per cambiare 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 l'istanza.
    • MACHINE_TYPE: il tipo di macchina dell'istanza. Ad esempio: n1-standard-2.

  3. Usa il metodo instances.update nell'API Compute Engine e specifica most_disruptive_allowed_action=NO_EFFECT per eseguire un aggiornamento di prova dell'istanza di destinazione. 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?most_disruptive_allowed_action=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 l'istanza.
    • INSTANCE_NAME: il nome dell'istanza da esportare.

  4. Utilizza il metodo instances.update nell'API Compute Engine per aggiornare l'istanza di destinazione. Se stai aggiornando una proprietà che richiede il riavvio di un'istanza, includi il parametro di query ?most_disruptive_allowed_action=RESTART per indicare che è possibile riavviare l'istanza durante l'aggiornamento. Se le proprietà non richiedono un riavvio, specifica il parametro di query ?most_disruptive_allowed_action=REFRESH. Per sapere quali proprietà richiedono un riavvio, consulta l'elenco delle proprietà aggiornabili. Includi il corpo completo della risorsa dell'istanza che hai modificato. Nell'esempio seguente, il corpo del testo cambia il tipo di macchina in n1-standard-2:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=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 l'istanza.
    • INSTANCE_NAME: il nome dell'istanza da esportare.
    • ALLOWED_ACTION: definisce il potenziale invasivo dell'aggiornamento. Specifica RESTART per consentire il 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, viene avviato il processo di aggiornamento dell'istanza. Puoi monitorare lo stato di questa operazione visualizzando gli audit log. Se l'aggiornamento richiede un riavvio e il comando consente un valore RESTART, l'istanza si riavvia per applicare le modifiche.

Passaggi successivi