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.

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

Para adicionar ou remover interfaces de rede dinâmicas de uma instância (prévia), use os procedimentos a seguir em vez de atualizar as propriedades da instância:

Antes de começar

  • Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Google Cloud . Para executar código ou exemplos em um ambiente de desenvolvimento local, faça a autenticação no Compute Engine com um destes métodos:

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

      gcloud init

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

    2. Set a default region and zone.

    REST

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

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

      gcloud init

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

    Saiba mais em 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 CLI gcloud 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 discos SSD locais anexados, não será possível atualizar as propriedades que exigem a reinicialização enquanto a instância está em execução. Você pode excluir e recriar a instância ou parar a instância, atualizar as propriedades e reiniciá-la.
  • É possível atualizar a propriedade networkInterfaces de uma instância, mas não é possível adicionar ou remover NICs virtuais (vNICs) de uma instância.
  • 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 Beta da configuração da instância durante o processo de atualização. Esse comportamento 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.
  • Se você estiver atualizando 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:
    • É possível modificar discos com o método disks.update.
    • Para mudar a rede usada pela instância, use o método instances.updateNetworkInterface, que não exige a interrupção da instância.

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 essa açã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á.

As propriedades a seguir exigem uma reinicialização (RESTART) para serem atualizadas:

  • disks: discos de inicialização, incluindo todos os discos (disks.deviceName)
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkInterfaces
  • networkPerformanceConfig
  • performanceMonitoringUnit
  • reservationAffinity: só é possível atualizar como a instância consome reservas (reservationAffinity.consumeReservationType) da seguinte maneira:
    • De consumir qualquer reserva correspondente (ANY_RESERVATION) a não consumir reservas (NO_RESERVATION)
    • De não consumir reservas (NO_RESERVATION) a consumir qualquer reserva correspondente (ANY_RESERVATION)
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

As propriedades a seguir exigem apenas uma atualização (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 neste documento. Por exemplo, para mudar 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 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:

    • 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 neste documento. Por exemplo, para mudar 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 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 uma ação RESTART ou REFRESH é necessária 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:

    • 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 mostDisruptiveAllowedAction=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 mostDisruptiveAllowedAction=REFRESH. Para saber quais propriedades exigem reinicialização, consulte a lista de propriedades atualizáveis neste documento. Inclua o corpo completo do recurso da instância que você modificou. No exemplo a seguir, o corpo muda 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:

    • 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