Atualize as propriedades da instância

Pode usar um único pedido a partir da CLI do Google Cloud ou da API Compute Engine para atualizar várias propriedades da instância e, opcionalmente, reiniciar a instância, se necessário. O método de atualização processa a lógica para validar as propriedades da instância atualizadas e garantir que os recursos necessários estão disponíveis para concluir a atualização com êxito. Se o pedido incluir propriedades inválidas ou se os recursos pedidos não estiverem disponíveis, o pedido devolve um erro e não faz alterações à sua instância. Isto protege a instância contra atualizações parciais e impede que a instância seja interrompida e não consiga aceder aos recursos para ser iniciada novamente.

Para atualizar as interfaces de rede (networkInterfaces) de uma instância, consulte o artigo Atualize as interfaces de rede de uma instância.

Para adicionar ou remover interfaces de rede dinâmicas de uma instância (pré-visualização), use os seguintes procedimentos em vez de atualizar as propriedades da instância:

Antes de começar

  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

    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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

Restrições

  • Os pedidos de atualização de instâncias através da CLI gcloud ou da API Compute Engine não suportam a semântica PATCH. O recurso de instância no pedido de atualização tem de incluir todas as propriedades da instância. As propriedades em falta na configuração da instância no seu pedido de atualização são consideradas eliminadas da instância.
  • Pode atualizar apenas uma lista específica de propriedades.
  • A alteração de instâncias para e de arrendamento exclusivo não é suportada.
  • Pode alterar uma instância de uma reserva para outra, mas não pode anexar nem desanexar uma instância a uma reserva através do processo de atualização.
  • Se a instância tiver discos SSD locais anexados, não pode atualizar propriedades que exijam o reinício da instância enquanto esta estiver em execução. Pode eliminar e, em seguida, recriar a instância ou parar a instância, atualizar as propriedades e, em seguida, reiniciá-la.
  • Pode atualizar a propriedade networkInterfaces de uma instância, mas não pode adicionar nem remover NICs virtuais (vNICs) de uma instância.
  • Se uma instância usar recursos que só estão disponíveis na API Compute Engine beta, tem de usar a versão correta do método instances.update para atualizar essas propriedades. Por exemplo, se criar uma instância através da API Compute Engine beta e configurar a instância com um recurso que apenas a API beta reconhece, também tem de usar a versão beta do método instances.update para atualizar esses recursos. A versão v1 do método instances.update não reconhece os recursos beta que a sua instância usa, pelo que elimina esses recursos beta da configuração da instância durante o processo de atualização. Este comportamento também se aplica aos recursos na API alfa.

Autorizações

Tem de ter a autorização compute.instances.update para atualizar instâncias. Esta autorização está incluída em várias funções de gestão de identidade e de acesso (IAM) existentes. Também tem de ter autorização para usar os recursos que quer modificar na instância. Por exemplo, para adicionar um disco a uma instância, tem de ter as seguintes autorizações:

  • A autorização compute.instances.update na instância que quer atualizar.
  • Tem de ter a autorização compute.disks.use para um disco existente ou compute.disks.create num projeto onde quer criar um novo disco.

Práticas recomendadas

Para garantir que a interface de atualização de instâncias funciona da forma mais eficaz para si, use as seguintes práticas recomendadas:

  • Se possível, use sempre a mesma versão da API Compute Engine para criar, definir e atualizar instâncias. Isto garante que pode atualizar e modificar os recursos de instâncias se estiverem disponíveis apenas numa versão da API.
  • Embora possa usar o método instances.update para atualizar instâncias num grupo de instâncias geridas (GIG), na maioria das situações, é melhor alterar o modelo de instância do grupo e implementar essa atualização no GIG em alternativa.
  • Se estiver a atualizar um recurso usado pela instância, use o comando para atualizar essa instância de recurso em vez de atualizar as propriedades da instância. Por exemplo:
    • Pode modificar discos com o método disks.update
    • Para alterar a rede usada pela instância, pode usar o método instances.updateNetworkInterface, que não requer a paragem da instância.

Propriedades que pode atualizar

Só pode alterar um conjunto específico de propriedades da instância através do método update. As atualizações de algumas propriedades requerem o reinício da instância. Para evitar reinícios acidentais nas suas instâncias, o seu pedido tem de definir que ação é permitida nas suas instâncias. O seu pedido pode especificar uma das seguintes ações:

  • NO_EFFECT: o pedido de atualização verifica se o pedido é válido e se os recursos estão disponíveis, mas não executa a atualização. Use esta ação para testar comandos sem iniciar atualizações reais.
  • REFRESH: o pedido de atualização é executado apenas se as propriedades da instância modificada não exigirem o reinício da instância. O pedido devolve um erro INFEASIBLE se o pedido for válido, mas for necessário reiniciar.
  • RESTART: se a atualização exigir o reinício da instância, o sistema reinicia a instância.

As seguintes propriedades requerem um reinício (RESTART) para serem atualizadas:

  • disks: discos de arranque, incluindo todos os discos (disks.deviceName)
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkInterfaces
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity: só pode atualizar a forma como a instância consome as reservas (reservationAffinity.consumeReservationType) da seguinte forma:
    • Desde consumir qualquer reserva correspondente (ANY_RESERVATION) até não consumir reservas (NO_RESERVATION)
    • De não consumir reservas (NO_RESERVATION) para consumir quaisquer reservas correspondentes (ANY_RESERVATION)
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

As seguintes propriedades só requerem uma atualização (REFRESH) para serem atualizadas:

  • canIpForward
  • deletionProtection
  • description
  • disks: propriedades do disco não de arranque, excluindo deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Atualize as propriedades da instância

Atualize as suas instâncias através dos seguintes passos:

  1. Exporte as propriedades de configuração da instância existente.
  2. Modifique as propriedades da configuração da instância.
  3. Execute um pedido de teste especificando NO_EFFECT como a ação mais disruptiva. A resposta indica campos inválidos na configuração da instância e indica a ação necessária para aplicar as alterações.
  4. Se a configuração for aceitável, peça uma atualização da instância e especifique a ação mais disruptiva que é aceitável para a atualização da instância.

O sistema inicia o processo de atualização apenas se o seu pedido cumprir os seguintes requisitos:

  • A propriedade fingerprint na sua solicitação tem de corresponder ao fingerprint da instância que está a atualizar. Isto impede que os pedidos de atualização simultâneos na mesma instância se substituam uns aos outros.
  • As propriedades no seu pedido de atualização têm de ser válidas.
  • Os recursos que solicitou têm de estar disponíveis.
  • Se as propriedades no seu pedido exigirem o reinício da instância, o seu pedido tem de especificar RESTART como uma ação permitida.

Se os requisitos forem cumpridos, o sistema inicia o processo de atualização da instância. Caso contrário, o sistema não faz alterações à instância existente nem à respetiva configuração.

Pode iniciar atualizações através da CLI gcloud ou da API Compute Engine.

gcloud

  1. Use o instances exportcomando para exportar as propriedades da instância existentes:

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

    Substitua o seguinte:

    • INSTANCE_NAME: o nome da instância que quer exportar.
    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho de saída onde quer guardar o ficheiro de configuração da instância na sua estação de trabalho local.

  2. Use um editor de texto para modificar uma ou mais propriedades no ficheiro de configuração da instância exportado. Para saber que propriedades pode atualizar, consulte a lista de propriedades atualizáveis neste documento. Por exemplo, para alterar o tipo de máquina da instância, altere a propriedade machineType:

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • MACHINE_TYPE: o tipo de máquina da instância, por exemplo, n1-standard-2.

  3. Use o instances update-from-filecomando para executar uma atualização de teste da instância de destino. Especifique a flag --most-disruptive-allowed-action=NO_EFFECT. A resposta identifica as propriedades com configuração incorreta e indica se é necessária uma ação RESTART ou REFRESH para aplicar a atualização.

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

    Substitua o seguinte:

    • INSTANCE_NAME: o nome da instância que quer exportar.
    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho para o ficheiro de configuração da instância modificada na sua estação de trabalho local.

  4. Use o instances update-from-filecomando para atualizar a instância de destino. Se estiver a atualizar uma propriedade que requer o reinício da instância, inclua a flag --most-disruptive-allowed-action=RESTART. Se as propriedades não exigirem um reinício, especifique a flag --most-disruptive-allowed-action=REFRESH. Para saber que propriedades requerem um reinício, consulte a lista de propriedades atualizáveis neste documento.

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

    Substitua o seguinte:

    • INSTANCE_NAME: o nome da instância que quer exportar.
    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho para o ficheiro de configuração da instância modificada na sua estação de trabalho local.
    • ALLOWED_ACTION: define o quão disruptiva a atualização pode ser. Especifique RESTART para permitir um reinício completo da instância. Especifique REFRESH para atualizar a instância apenas se as propriedades modificadas não exigirem o reinício da instância.

Se o pedido de atualização for válido e os recursos necessários estiverem disponíveis, o processo de atualização da instância começa. Pode monitorizar o estado desta operação consultando os registos de auditoria. Se a atualização exigir um reinício e o seu comando permitir um RESTART, a instância é reiniciada para aplicar as alterações.

REST

  1. Use o método instances.get na API Compute Engine para exportar as propriedades da instância existente:

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona para esta instância.
    • INSTANCE_NAME: o nome da instância que quer exportar.

    Este pedido devolve uma definição de recurso de instância.

  2. Na resposta, modifique as propriedades do recurso de instância. Para saber que propriedades são atualizáveis, consulte a lista de propriedades atualizáveis neste documento. Por exemplo, para alterar o tipo de máquina da instância, altere a propriedade machineType. Pode alterar várias propriedades.

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • MACHINE_TYPE: o tipo de máquina da instância, por exemplo, n1-standard-2.

  3. Use o método instances.update na API Compute Engine e especifique o parâmetro de consulta mostDisruptiveAllowedAction=NO_EFFECT para executar uma atualização de teste da instância de destino. A resposta identifica propriedades configuradas incorretamente e indica se é necessária uma ação RESTART ou REFRESH para aplicar a atualização.

    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",
  ...
}

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • INSTANCE_NAME: o nome da instância que quer exportar.

  4. Use o método instances.update na API Compute Engine para atualizar a instância de destino. Se estiver a atualizar uma propriedade que requer o reinício de uma instância, inclua o parâmetro de consulta mostDisruptiveAllowedAction=RESTART para indicar que a instância pode ser reiniciada durante a atualização. Se as propriedades não exigirem um reinício, especifique o parâmetro de consulta mostDisruptiveAllowedAction=REFRESH. Para saber que propriedades requerem um reinício, consulte a lista de propriedades atualizáveis neste documento. Inclua o corpo completo do recurso de instância que modificou. No exemplo seguinte, o corpo altera o tipo de máquina para 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",
  ...
}

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto para este pedido.
    • ZONE: a zona desta instância.
    • INSTANCE_NAME: o nome da instância que quer exportar.
    • ALLOWED_ACTION: define o quão disruptiva a atualização pode ser. Especifique RESTART para permitir um reinício completo da instância. Especifique REFRESH para atualizar a instância apenas se as propriedades modificadas não exigirem o reinício da instância.

Se o pedido de atualização for válido e os recursos necessários estiverem disponíveis, o processo de atualização da instância começa. Pode monitorizar o estado desta operação consultando os registos de auditoria. Se a atualização exigir um reinício e o seu comando permitir um RESTART, a instância é reiniciada para aplicar as alterações.

O que se segue?