Aggiorna proprietà istanza

Puoi utilizzare una singola richiesta Google Cloud CLI o il API Compute Engine per aggiornare più proprietà dell'istanza e, facoltativamente, se necessario, riavvia l'istanza. 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. Se la richiesta include proprietà non valide o se le risorse richieste non sono disponibili, restituisce un errore e non apporta modifiche all'istanza. Questo protegge l'istanza da aggiornamenti parziali e da aggiornamenti è stato arrestato e non è in grado di accedere alle risorse per riavviarlo.

Prima di iniziare

  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è la procedura mediante la quale la tua identità viene verificata per l'accesso alle API e ai servizi Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi eseguire l'autenticazione Compute Engine come segue.

    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. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

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

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Per ulteriori informazioni, vedi Esegui l'autenticazione 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 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 single-tenancy non è supportata.
  • Puoi spostare un'istanza da una prenotazione all'altra, ma non puoi collegare o scollegare un'istanza da una prenotazione utilizzando la procedura di aggiornamento.
  • Se all'istanza è collegato un SSD locale, non puoi aggiornare le proprietà che e richiede il riavvio dell'istanza. Devi eliminare e poi ricreare il cluster in esecuzione in un'istanza Compute Engine. Assicurati di eseguire la migrazione dei dati critici dall'SSD locale a un disco permanente o a un'altra VM prima l'eliminazione della VM.
  • Se un'istanza utilizza risorse disponibili solo nella versione beta l'API Compute Engine, devi utilizzare la versione corretta instances.update metodo 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, per cui vengono eliminate delle risorse della configurazione dell'istanza durante il processo di aggiornamento. Questo si applica anche alle risorse nell'API alpha.

Autorizzazioni

Per aggiornare le istanze, devi disporre dell'autorizzazione compute.instances.update. Questa autorizzazione è inclusa in diversi ruoli IAM (Identity and Access Management) esistenti. Devi anche disporre dell'autorizzazione per utilizzare le risorse su cui vuoi modificare l'istanza. Ad esempio, per aggiungere un disco a un'istanza, devi avere le seguenti autorizzazioni:

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

Best practice

Per assicurarti 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, impostare 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, nella maggior parte delle situazioni è meglio modificare modello di istanza del gruppo implementare l'aggiornamento al gruppo di istanze gestite .

Proprietà che puoi aggiornare

Puoi modificare solo un insieme specifico di proprietà dell'istanza tramite l'aggiornamento . Gli aggiornamenti di alcune proprietà richiedono il riavvio dell'istanza. Per evitare riavvii accidentali delle istanze, la tua richiesta deve definire l'azione consentita sulle tue istanze. La tua 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. Usa questa per testare i comandi senza avviare alcun aggiornamento effettivo.
  • REFRESH: la richiesta di aggiornamento viene eseguita solo se le proprietà dell'istanza modificate non richiedono il riavvio dell'istanza. La richiesta restituisce un INFEASIBLE errore se la richiesta è valida, ma è necessario un riavvio.
  • RESTART: se l'aggiornamento richiede il riavvio dell'istanza, il sistema e riavviare l'istanza.

Proprietà che richiedono l'aggiornamento di RESTART:

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

Proprietà che richiedono solo REFRESH per l'aggiornamento:

  • canIpForward
  • deletionProtection
  • description
  • disks - Proprietà dei dischi diversi da quello di avvio, escluso deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Aggiorna proprietà istanza

Aggiorna le istanze seguendo questa procedura:

  1. Esporta le proprietà di configurazione dell'istanza esistente.
  2. Modifica le proprietà della configurazione dell'istanza.
  3. Esegui una richiesta di test specificando NO_EFFECT come l'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 tua richiesta soddisfa i seguenti requisiti:

  • La proprietà fingerprint dell'istanza nella richiesta deve corrispondere a fingerprint dell'istanza che stai aggiornando. In questo modo di sovrascrivere più richieste di aggiornamento simultanee sulla stessa istanza tra loro.
  • Le proprietà nella richiesta di aggiornamento devono essere valide.
  • Le risorse richieste devono essere disponibili.
  • Se le proprietà nella richiesta richiedono il riavvio dell'istanza, la 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 relativa configurazione.

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

gcloud

  1. Utilizza la instances export per esportare proprietà dell'istanza esistente:

    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 dove vuoi per 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 nell'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 per questa istanza.
    • MACHINE_TYPE: la macchina tipo 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 --most-disruptive-allowed-action=NO_EFFECT flag. La risposta identifica proprietà non configurate correttamente e indica se 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 dell'istanza modificata di configurazione del deployment sulla workstation locale.

  4. Utilizza la instances update-from-file comando per aggiornare l'istanza di destinazione. Se stai aggiornando una proprietà che richiede il parametro per riavviare l'istanza, includi --most-disruptive-allowed-action=RESTART flag. Se le proprietà non richiedono un riavvio, specifica --most-disruptive-allowed-action=REFRESH flag. Per scoprire quali proprietà richiedono il 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 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 l'entità dell'interruzione causata dall'aggiornamento. Specifica RESTART per consentire un riavvio completo dell'app in esecuzione in un'istanza Compute Engine. 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 i log di controllo. Se l'aggiornamento richiede un riavvio e il tuo comando consente RESTART, l'istanza si riavvia 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 vuoi esportare.

    Questa richiesta restituisce un definizione di risorsa istanza.

  2. Nella risposta, modifica le proprietà della risorsa dell'istanza. Per sapere quali sono aggiornabili, consulta le 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 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 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 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 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 l'istanza può essere riavviata durante l'aggiornamento. Se le proprietà non richiedono il riavvio, specifica Parametro di query ?most_disruptive_allowed_action=REFRESH. Per sapere quali proprietà richiedono un riavvio, consulta l'elenco delle proprietà aggiornabili. Includi l'intero corpo macchina per la 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?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 questa istanza.
    • INSTANCE_NAME: il nome dell'istanza vuoi esportare.
    • ALLOWED_ACTION: definisce quanto sia invasivo il un aggiornamento al 100%. 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, viene avviato il processo di aggiornamento dell'istanza. Puoi monitorare lo stato operazione eseguita da la visualizzazione degli audit log. Se l'aggiornamento richiede un riavvio e il comando consente un RESTART, l'istanza viene riavviata per applicare le modifiche.

Passaggi successivi