Atualizar propriedades da instância

Use uma única solicitação da CLI do Google Cloud ou da API Compute Engine para atualizar várias propriedades de instância e reiniciar a instância, se necessário. O método de atualização processa a lógica para validar as propriedades da instância atualizada e garantir que os recursos necessários estejam disponíveis para concluir a atualização. Se a solicitação incluir propriedades inválidas ou se os recursos solicitados não estiverem disponíveis, a solicitação retornará um erro e não fará alterações na instância. Isso protege a instância contra atualizações parciais e impede que ela seja interrompida e não consiga acessar os recursos para ser reiniciada.

Antes de começar

  • Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine da seguinte maneira.

    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

      Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

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

        gcloud init

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

Restrições

  • As solicitações de atualização de instância pela gcloud CLI ou da API Compute Engine não são compatíveis com a semântica PATCH. O recurso de instância na solicitação de atualização deve incluir todas as propriedades da instância. As propriedades ausentes na configuração da instância na sua solicitação de atualização serão consideradas excluídas da instância.
  • É possível atualizar apenas uma lista específica de propriedades.
  • Não é possível alterar instâncias de e para locatário individual.
  • Você pode alterar uma instância de uma reserva para outra, mas não é possível anexar ou desanexar uma instância de uma reserva usando o processo de atualização.
  • Se a instância tiver um SSD local anexado, não será possível atualizar as propriedades que exigem a reinicialização. Exclua e recrie a instância. Não se esqueça de migrar os dados importantes do SSD local para um disco permanente ou para outra VM antes de excluir a VM.
  • Se uma instância usar recursos disponíveis apenas na API Compute Engine Beta, você precisará usar a versão correta do método instances.update para atualizar essas propriedades. Por exemplo, se você criar uma instância usando a API Compute Engine Beta e configurá-la com um recurso reconhecido apenas pela API Beta, também será necessário 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 sua instância usa. Por isso, ela exclui esses recursos da configuração da instância durante o processo de atualização. Isso também se aplica aos recursos na versão Alfa da API.

Permissões

É necessário ter a permissão compute.instances.update para atualizar instâncias. Essa permissão está incluída em vários papéis existentes de gerenciamento de identidade e acesso (IAM, na sigla em inglês). Você também precisa ter permissão para usar os recursos que quer modificar na instância. Por exemplo, para adicionar um disco a uma instância, é preciso ter as permissões a seguir:

  • A permissão compute.instances.update na instância que você quer atualizar.
  • A permissão compute.disks.use para um disco existente ou compute.disks.create em um projeto em que você quer criar um novo disco.

Práticas recomendadas

Para garantir que a interface de atualização da instância funcione com mais eficiência, use as seguintes práticas recomendadas:

  • Se possível, use a mesma versão da API Compute Engine de maneira consistente para criar, configurar e atualizar instâncias. Assim, você poderá atualizar e modificar qualquer recurso da instância se eles estiverem disponíveis apenas em uma versão da API.
  • É possível usar o método instances.update para atualizar instâncias em um grupo de instâncias gerenciadas (MIG, na sigla em inglês). Entretanto, na maioria das situações, é melhor alterar o modelo de instância do grupo e reverter para o MIG.

Propriedades que podem ser atualizadas

É possível alterar apenas um conjunto específico de propriedades da instância por meio do método de atualização. Para atualizar algumas propriedades, é necessário reiniciar a instância. Para evitar reinicializações acidentais nas instâncias, a solicitação precisa definir qual ação tem permissão para ser executada. A solicitação pode especificar uma das seguintes ações:

  • NO_EFFECT: a solicitação de atualização verifica se a solicitação é válida e se os recursos estão disponíveis, mas não executa a atualização. Use-o para testar comandos sem iniciar atualizações reais.
  • REFRESH: a solicitação de atualização só será executada se as propriedades da instância modificada não exigirem a reinicialização da instância. A solicitação retorna um erro INFEASIBLE se for válida, mas será necessário reiniciar.
  • RESTART: se a atualização exigir que a instância seja reiniciada, o sistema a reiniciará.

Propriedades que exigem a atualização do RESTART:

  • disks: discos de inicialização
    • disks.deviceName: todos os discos
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Propriedades que exigem a atualização apenas do REFRESH:

  • canIpForward
  • deletionProtection
  • description
  • disks: propriedades de disco que não são de inicialização, exceto deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Atualizar propriedades da instância

Atualize suas instâncias seguindo as seguintes etapas:

  1. Exporte as propriedades de configuração da instância atual.
  2. Modifique as propriedades de configuração da instância.
  3. Realize uma solicitação 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, solicite uma atualização da instância e especifique a ação mais disruptiva aceitável para esta atualização.

O sistema iniciará o processo de atualização apenas se sua solicitação atender aos requisitos a seguir:

  • Na sua solicitação, a propriedade fingerprint da instância deve corresponder ao fingerprint da instância que você está atualizando. Isso impede que solicitações de atualização simultâneas na mesma instância substituam umas às outras.
  • As propriedades da solicitação de atualização devem ser válidas.
  • Os recursos solicitados devem estar disponíveis.
  • Se as propriedades da solicitação exigirem que a instância reinicie, ela precisará especificar RESTART como uma ação permitida.

Se os requisitos forem atendidos, o sistema iniciará o processo de atualização da instância. Caso contrário, o sistema não fará alterações na instância ou na configuração dela.

É possível iniciar atualizações usando a gcloud CLI ou a API Compute Engine.

gcloud

  1. Use o comando instances export para exportar as propriedades da instância atual:

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

    Substitua:

    • INSTANCE_NAME: o nome da instância que você quer exportar;
    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho de saída em que você quer salvar o arquivo de configuração da instância na estação de trabalho local.

  2. Use um editor de texto para modificar uma ou mais propriedades no arquivo de configuração da instância exportada. Para saber quais propriedades é possível atualizar, consulte a lista de propriedades atualizáveis. 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:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • MACHINE_TYPE: o tipo de máquina da instância Por exemplo, n1-standard-2.

  3. Use o comando instances update-from-file para executar uma atualização de teste da instância de destino. Especifique a sinalização --most-disruptive-allowed-action=NO_EFFECT. A resposta identifica propriedades configuradas incorretamente e indica se uma ação RESTART ou REFRESH é necessária para realizar 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:

    • INSTANCE_NAME: o nome da instância que você quer exportar;
    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho para o arquivo de configuração da instância modificado na estação de trabalho local.

  4. Use o comando instances update-from-file para atualizar a instância de destino. Se você estiver atualizando uma propriedade que requer a reinicialização da instância, inclua a sinalização --most-disruptive-allowed-action=RESTART. Se as propriedades não exigirem reinicialização, especifique a sinalização --most-disruptive-allowed-action=REFRESH. Para saber quais propriedades exigem reinicialização, consulte a lista de propriedades atualizáveis.

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

    Substitua:

    • INSTANCE_NAME: o nome da instância que você quer exportar;
    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • FILE_PATH: o caminho para o arquivo de configuração da instância modificado na estação de trabalho local.
    • ALLOWED_ACTION: define o grau de disrupção da atualização. Especifique RESTART para permitir uma reinicialização completa da instância. Especifique REFRESH para atualizar a instância somente se as propriedades modificadas não exigirem a reinicialização dela.

Se a solicitação de atualização for válida e os recursos necessários estiverem disponíveis, o processo de atualização da instância será iniciado. É possível monitorar o status da operação visualizando os registros de auditoria. Se a atualização exigir uma reinicialização e o comando permitir um RESTART, a instância será 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:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância;
    • INSTANCE_NAME: o nome da instância que você quer exportar.

    Essa solicitação retorna uma definição de recurso de instância.

  2. Na resposta, modifique as propriedades dos recursos da instância. Para saber quais propriedades podem ser atualizadas, consulte a lista de propriedades atualizáveis. Por exemplo, para alterar o tipo de máquina da instância, altere a propriedade machineType. É possível alterar várias propriedades.

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

    Substitua:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • 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 most_disruptive_allowed_action=NO_EFFECT para executar uma atualização de teste da instância de destino. A resposta identifica propriedades configuradas incorretamente e indica se é necessário aplicar uma ação RESTART ou REFRESH para realizar a atualização.

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

    Substitua:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • INSTANCE_NAME: o nome da instância que você quer exportar.

  4. Use o método instances.update na API Compute Engine para atualizar a instância de destino. Se você estiver atualizando uma propriedade que exige a reinicialização da instância, inclua o parâmetro de consulta ?most_disruptive_allowed_action=RESTART para indicar que a instância pode ser reiniciada durante a atualização. Se as propriedades não exigirem uma reinicialização, especifique o parâmetro de consulta ?most_disruptive_allowed_action=REFRESH. Para saber quais propriedades exigem reinicialização, consulte a lista de propriedades atualizáveis. Inclua o corpo completo do recurso da instância que você modificou. No exemplo a seguir, 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?most_disruptive_allowed_action=ALLOWED_ACTION

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

    Substitua:

    • PROJECT_ID: o ID do projeto desta solicitação;
    • ZONE: a zona desta instância.
    • INSTANCE_NAME: o nome da instância que você quer exportar.
    • ALLOWED_ACTION: define o grau de disrupção da atualização. Especifique RESTART para permitir uma reinicialização completa da instância. Especifique REFRESH para atualizar a instância somente se as propriedades modificadas não exigirem a reinicialização dela.

Se a solicitação de atualização for válida e os recursos necessários estiverem disponíveis, o processo de atualização da instância será iniciado. É possível monitorar o status da operação visualizando os registros de auditoria. Se a atualização exigir uma reinicialização e o comando permitir um RESTART, a instância será reiniciada para aplicar as alterações.

A seguir