Gerenciar extensões de VM usando políticas de extensão

O Gerenciador de extensões de VM usa políticas de extensão para gerenciar suas extensões de VM em grande escala. Para mais informações, consulte Sobre o Gerenciador de Extensões de VM. Neste documento, descrevemos como atualizar e excluir políticas de extensão de VM globais e zonais no nível do projeto ou nos níveis de pasta e organização (disponíveis em pré-lançamento). Para conferir as políticas de extensão, as extensões e versões de VM e os estados de extensão de ambiente de execução em instâncias de VM, consulte Conferir detalhes e status da extensão de VM. Para diagnosticar problemas de instalação ou de ambiente de execução, consulte Resolver problemas de extensões de VM.

Limitações do gerenciamento de políticas

Só é possível atualizar e excluir políticas de extensão de VM com escopo de pasta e de organização usando a Google Cloud CLI ou a API REST do Compute Engine. Não é possível gerenciar políticas com escopo de pasta ou de organização no console doGoogle Cloud .

Modificar extensões atualizando uma política de extensão de VM

Quando você atualiza uma política, o Gerenciador de Extensões de VM implementa as mudanças em todas as VMs aplicáveis, geralmente em um minuto. Se você modificar os rótulos de inclusão, as extensões poderão ser instaladas em novas VMs ou desinstaladas das VMs atuais, com base na correspondência com os rótulos atualizados.

Modificar extensões de VM em todas as zonas de uma organização

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo da organização, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da organização (roles/compute.orgVmExtensionPolicyAdmin) na sua organização. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.orgVmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo da organização.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão global com escopo de organização, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute global-vm-extension-policies update com a flag --organization para modificar uma política de extensão de VM global com escopo de organização. Quando você atualiza uma política usando gcloud, a solicitação funciona como uma substituição completa. Os campos opcionais omitidos voltam aos valores padrão em vez de manter os valores atuais da política modificada.

Para atualizar uma política global de extensão de VM no escopo da organização, execute o seguinte comando:

gcloud preview compute global-vm-extension-policies update POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs em todos os projetos e zonas descendentes na organização.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • ORGANIZATION_ID: a organização em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política. Esse UUID permite que você tente novamente uma atualização sem mudanças. Um erro vai ocorrer se você definir essa flag e a política for modificada. Para mais informações, consulte Repetir um lançamento.

Exemplo: atualizar uma política global com escopo de organização

O comando a seguir atualiza a política prod-frontend-policy na organização 123456789 para adicionar a extensão google-cloud-workload-extension e desafixar ops-agent para que ela rastreie a versão mais recente usando um plano de lançamento rápido:

gcloud preview compute global-vm-extension-policies update prod-frontend-policy \
  --organization=organizations/123456789 \
  --description="Updated policy: ops-agent + workload extension, unpinned" \
  --extensions=ops-agent,google-cloud-workload-extension \
  --config=ops-agent="updated-monitoring-config" \
  --inclusion-labels="env=prod,workload=frontend" \
  --priority=100 \
  --rollout-predefined-plan=fast_rollout

REST

Para atualizar uma política de extensão global com escopo de organização, faça uma solicitação PATCH ao método organizationGlobalVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/global/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY,
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "retryUuid": "RETRY_UUID",
    "name": "organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs em todos os projetos e zonas descendentes na organização.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu. Para usar um plano de lançamento predefinido, substitua o campo name por predefinedRolloutPlan e especifique um dos seguintes valores:
    • SLOW_ROLLOUT: lança a política ao longo de cinco dias. Esse plano predefinido é o plano de lançamento padrão se você não especificar um.
    • FAST_ROLLOUT: lança a política imediatamente em todas as zonas.
  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política.

Modificar extensões de VM em todas as zonas de uma pasta

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo de pasta, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da pasta (roles/compute.folderVmExtensionPolicyAdmin) na pasta. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.folderVmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo de pasta.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão global com escopo de pasta, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute global-vm-extension-policies update com a flag --folder para modificar uma política de extensão de VM global com escopo de pasta. Quando você atualiza uma política usando a gcloud, a solicitação funciona como uma substituição completa. Os campos opcionais omitidos voltam aos valores padrão em vez de manter os valores atuais da política modificada.

Para atualizar uma política de extensão de VM global com escopo de pasta, execute o seguinte comando:

gcloud preview compute global-vm-extension-policies update POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs em todos os projetos e zonas descendentes na pasta.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • FOLDER_ID: a pasta em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política. Esse UUID permite que você tente novamente uma atualização sem mudanças. Um erro vai ocorrer se você definir essa flag e a política for modificada. Para mais informações, consulte Repetir um lançamento.

REST

Para atualizar uma política de extensão global com escopo de pasta, faça uma solicitação PATCH ao método folderGlobalVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/global/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY,
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "retryUuid": "RETRY_UUID",
    "name": "folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • FOLDER_ID: o ID da pasta do Google Cloud .
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs em todos os projetos e zonas descendentes na pasta.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu. Para usar um plano de lançamento predefinido, substitua o campo name por predefinedRolloutPlan e especifique um dos seguintes valores:
    • SLOW_ROLLOUT: lança a política ao longo de cinco dias. Esse plano predefinido é o plano de lançamento padrão se você não especificar um.
    • FAST_ROLLOUT: lança a política imediatamente em todas as zonas.
  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política.

Modificar extensões de VM em todas as zonas de um projeto

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo de projeto, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute (roles/compute.vmExtensionPolicyAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.vmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo de projeto.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão global com escopo de projeto, selecione uma das seguintes opções:

Console

Para atualizar uma política de extensão de VM global com escopo de projeto no console do Google Cloud , siga estas etapas:

  1. No console do Google Cloud , acesse a página Políticas de extensão de VM.

    Acessar as políticas de extensão de VM

  2. Clique em Políticas globais e selecione a política que você quer editar.
  3. Clique em Editar.
  4. No campo Prioridade, especifique um número de prioridade para resolver conflitos entre políticas. Números menores indicam prioridade mais alta. O valor padrão é 1000.
  5. Na seção Gerenciar extensões, faça o seguinte:
    • Para adicionar mais extensões, clique em Adicionar extensão e selecione a extensão e a versão.
    • Para excluir uma extensão gerenciada por essa política, clique no botão Excluir ao lado do nome dela.
  6. Se você quiser aplicar rótulos, adicione-os às VMs de destino na seção Instâncias de VM de destino.
  7. Clique em Salvar.

gcloud

Use o comando gcloud compute global-vm-extension-policies update para modificar uma política de extensão de VM global com escopo de projeto. Quando você atualiza uma política usando gcloud, a solicitação funciona como uma substituição completa. Os campos opcionais omitidos voltam aos valores padrão em vez de manter os valores atuais da política modificada.

Para atualizar uma política de extensão de VM global com escopo de projeto, execute o seguinte comando:

gcloud compute global-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs em todas as zonas do projeto.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • PROJECT_NUMBER: o projeto em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política. Esse UUID permite que você tente novamente uma atualização sem mudanças. Um erro vai ocorrer se você definir essa flag e a política for modificada. Para mais informações, consulte Repetir um lançamento.

REST

Para atualizar uma política de extensão global com escopo de projeto, faça uma solicitação PATCH ao método globalVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY,
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "retryUuid": "RETRY_UUID",
    "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs em todas as zonas do projeto.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando o Gerenciador de Extensões de VM detecta um conflito entre uma política zonal e uma global. É possível especificar um dos seguintes comportamentos de conflito:
    • "" (string vazia): a política global não substitui as políticas zonais conflitantes que têm o mesmo nome. Esse comportamento de conflito é o padrão.
    • overwrite: a política global substitui qualquer política zonal com o mesmo nome e, em seguida, gerencia os lançamentos de políticas na zona.

    Para mais informações, consulte a flag --rollout-conflict-behavior.

  • PROJECT_NUMBER: o projeto em que o plano de lançamento personalizado está definido.
  • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu. Para usar um plano de lançamento predefinido, substitua o campo name por predefinedRolloutPlan e especifique um dos seguintes valores:
    • SLOW_ROLLOUT: lança a política ao longo de cinco dias. Esse plano predefinido é o plano de lançamento padrão se você não especificar um.
    • FAST_ROLLOUT: lança a política imediatamente em todas as zonas.
  • RETRY_UUID: um UUID que identifica uma tentativa de nova tentativa de lançamento de atualização de política.

Modificar extensões de VM em uma zona em uma organização

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo da organização, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da organização (roles/compute.orgVmExtensionPolicyAdmin) na sua organização. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.orgVmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo da organização.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão zonal com escopo de organização, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute zone-vm-extension-policies update com a flag --organization para modificar uma política de extensão de VM zonal no escopo da organização. Quando você atualiza uma política usando a gcloud, a solicitação atua como uma substituição completa. Os campos opcionais que você omitir vão voltar aos valores padrão, em vez de manter os valores atuais da política modificada.

Para atualizar uma política de extensão de VM zonal no escopo da organização, execute o seguinte comando:

gcloud preview compute zone-vm-extension-policies update POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política se aplica.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs na zona especificada em todos os projetos descendentes na organização.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

REST

Para atualizar uma política de extensão zonal com escopo de organização, faça uma solicitação PATCH ao método organizationZoneVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY
}

Substitua:

  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ZONE: a Google Cloud zona em que a política de extensão de VM está localizada.
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs na zona especificada em todos os projetos descendentes da organização.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

Modificar extensões de VM em uma zona em uma pasta

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo de pasta, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da pasta (roles/compute.folderVmExtensionPolicyAdmin) na pasta. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.folderVmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo de pasta.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão zonal com escopo de pasta, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute zone-vm-extension-policies update com a flag --folder para modificar uma política de extensão de VM zonal com escopo de pasta. Quando você atualiza uma política usando a gcloud, a solicitação atua como uma substituição completa. Os campos opcionais que você omitir vão voltar aos valores padrão, em vez de manter os valores atuais da política modificada.

Para atualizar uma política de extensão de VM zonal com escopo de pasta, execute o seguinte comando:

gcloud preview compute zone-vm-extension-policies update POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política se aplica.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs na zona especificada em todos os projetos descendentes na pasta.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

REST

Para atualizar uma política de extensão zonal com escopo de pasta, faça uma solicitação PATCH ao método folderZoneVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY
}

Substitua:

  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ZONE: a Google Cloud zona em que a política de extensão de VM está localizada.
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs na zona especificada em todos os projetos descendentes na pasta.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

Modificar extensões de VM em uma zona de um projeto

Permissões do IAM obrigatórias

Para receber a permissão necessária para atualizar uma política de extensão com escopo de projeto, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute (roles/compute.vmExtensionPolicyAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.vmExtensionPolicies.update, que é necessária para atualizar uma política de extensão com escopo de projeto.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para atualizar uma política de extensão zonal com escopo de projeto, selecione uma das seguintes opções:

Console

Para atualizar uma política de extensão de VM zonal com escopo de projeto no console do Google Cloud , siga estas etapas:

  1. No console do Google Cloud , acesse a página Políticas de extensão de VM.

    Acessar as políticas de extensão de VM

  2. Selecione a política que você quer atualizar.
  3. Clique em Editar.
  4. Modifique a Descrição, a Prioridade, as Extensões ou as Instâncias de VM de destino.
  5. Clique em Salvar.

gcloud

Use o comando gcloud compute zone-vm-extension-policies update para modificar uma política de extensão de VM zonal com escopo de projeto. Quando você atualiza uma política usando a gcloud, a solicitação atua como uma substituição completa. Os campos opcionais que você omitir vão voltar aos valores padrão, em vez de manter os valores atuais da política modificada.

Para atualizar uma política de extensão de VM zonal com escopo de projeto, execute o seguinte comando:

gcloud compute zone-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • ZONE: a zona do Google Cloud em que a política se aplica.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: uma lista separada por vírgulas de extensões a serem adicionadas à política. É necessário especificar pelo menos uma extensão. É possível especificar qualquer uma das seguintes extensões compatíveis:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é a versão da extensão. Se você não especificar uma versão para uma extensão, o Gerenciador de extensões de VM vai usar a versão mais recente disponível e fazer upgrade dela automaticamente quando novas versões forem disponibilizadas.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse arquivo está localizado na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file, por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar as VMs que corresponderem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa sinalização, a política vai segmentar todas as VMs na zona especificada do projeto.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

REST

Para atualizar uma política de extensão zonal com escopo de projeto, faça uma solicitação PATCH ao método zoneVmExtensionPolicies.update. Ao atualizar uma política usando REST, basta fornecer os campos que você quer atualizar. Os campos omitidos mantêm os valores atuais.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

{
"description": "DESCRIPTION",
"extensionPolicies": {
  "EXTENSION_NAME": {
    "pinnedVersion": "EXTENSION_NAME_VERSION",
    "stringConfig": "EXTENSION_NAME_CONFIG"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
      "inclusionLabels": {
        "KEY_1": "VALUE_1",
        "KEY_2": "VALUE_2"
      }
    }
  }
],
"priority": PRIORITY
}

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • ZONE: a Google Cloud zona em que a política de extensão de VM está localizada.
  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • DESCRIPTION: uma descrição da política de extensão de VM.
  • EXTENSION_NAME: o nome da extensão a ser atualizada, usada como uma chave no mapa extensionPolicies. Para atualizar várias extensões, inclua várias entradas no mapa extensionPolicies.
  • EXTENSION_NAME_VERSION: a versão da extensão da VM.
  • EXTENSION_NAME_CONFIG: configurações da extensão da VM, como uma string inline.
  • KEY_1:VALUE_1, KEY_2:VALUE_2: pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor para serem segmentadas. Para especificar vários seletores, inclua vários objetos na matriz instanceSelectors, cada um com um campo labelSelector. Nesse caso, o Gerenciador de Extensões de VM segmenta as VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir instanceSelectors, a política vai segmentar todas as VMs na zona especificada do projeto.
  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam prioridade mais alta. O valor padrão é 1000. Se várias políticas tiverem a mesma prioridade, o Gerenciador de Extensões de VM vai aplicar a política atualizada mais recentemente às VMs.

Desinstalar extensões excluindo uma política de extensão de VM

Quando você exclui uma política, o Gerenciador de Extensões de VM desinstala as extensões de todas as VMs gerenciadas por essa política. No entanto, se outra política ativa de menor prioridade for aplicada a uma VM e declarar a mesma extensão, ela vai permanecer instalada nessa VM com base na política de menor prioridade.

O Gerenciador de Extensões de VM remove as extensões de todas as VMs acessíveis em até um minuto após a exclusão da política. Se uma VM estiver inacessível porque o agente convidado foi removido ou a VM foi excluída, o Gerenciador de Extensões de VM vai pular a exclusão da extensão. Se uma VM assim ficar disponível novamente, o Gerenciador de extensões de VM vai remover as extensões nesse momento.

Desinstalar extensões de VM em todas as zonas de uma organização

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de organização, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da organização (roles/compute.orgVmExtensionPolicyAdmin) na sua organização. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.orgVmExtensionPolicies.delete, necessária para excluir uma política de extensão com escopo de organização.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão global com escopo de organização, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute global-vm-extension-policies delete com a flag --organization para excluir uma política global de extensão de VM no escopo da organização:

gcloud preview compute global-vm-extension-policies delete POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • ORGANIZATION_ID: a organização em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

REST

Para excluir uma política de extensão global com escopo de organização, faça uma solicitação POST ao método organizationGlobalVmExtensionPolicies.delete.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/global/vmExtensionPolicies/POLICY_NAME/delete

{
"retryUuid": "RETRY_UUID",
"predefinedRolloutPlan": "ROLLOUT_PLAN"
}

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ROLLOUT_PLAN: especifique SLOW_ROLLOUT ou FAST_ROLLOUT. Para usar um plano de lançamento personalizado, substitua predefinedRolloutPlan por "name": "organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME".
  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

Desinstalar extensões de VM em todas as zonas de uma pasta

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de pasta, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da pasta (roles/compute.folderVmExtensionPolicyAdmin) na sua pasta. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.folderVmExtensionPolicies.delete, que é necessária para excluir uma política de extensão com escopo de pasta.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão global com escopo de pasta, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute global-vm-extension-policies delete com a flag --folder para excluir uma política global de extensão de VM com escopo de pasta:

gcloud preview compute global-vm-extension-policies delete POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • FOLDER_ID: a pasta em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

REST

Para excluir uma política de extensão global com escopo de pasta, faça uma solicitação POST ao método folderGlobalVmExtensionPolicies.delete.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/global/vmExtensionPolicies/POLICY_NAME/delete

{
"retryUuid": "RETRY_UUID",
"predefinedRolloutPlan": "ROLLOUT_PLAN"
}

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ROLLOUT_PLAN: especifique SLOW_ROLLOUT ou FAST_ROLLOUT. Para usar um plano de lançamento personalizado, substitua predefinedRolloutPlan por "name": "folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME".
  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

Desinstalar extensões de VM em todas as zonas de um projeto

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de projeto, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute (roles/compute.vmExtensionPolicyAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.vmExtensionPolicies.delete, necessária para excluir uma política de extensão com escopo de projeto.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão global com escopo de projeto, selecione uma das seguintes opções:

Console

Para excluir uma política de extensão de VM global com escopo de projeto no console do Google Cloud , siga estas etapas:

  1. No console do Google Cloud , acesse a página Políticas de extensão de VM.

    Acessar as políticas de extensão de VM

  2. Clique em Políticas globais e selecione a política que você quer excluir.
  3. Clique em Excluir.
  4. Na caixa de diálogo de confirmação, insira o nome da política e clique em Excluir.

gcloud

Use o comando gcloud compute global-vm-extension-policies delete para excluir uma política global de extensão de VM com escopo de projeto:

gcloud compute global-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-retry-uuid=RETRY_UUID

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, especifique a flag --rollout-custom-plan em vez de --rollout-predefined-plan usando o seguinte formato:
    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • PROJECT_NUMBER: o projeto em que o plano de lançamento está definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu.

    Se você não especificar uma flag de plano de lançamento, o Gerenciador de Extensões de VM vai usar slow_rollout.

  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

REST

Para excluir uma política de extensão global com escopo de projeto, faça uma solicitação POST ao método globalVmExtensionPolicies.delete.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/vmExtensionPolicies/POLICY_NAME/delete

{
"retryUuid": "RETRY_UUID",
"predefinedRolloutPlan": "ROLLOUT_PLAN"
}

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • ROLLOUT_PLAN: especifique SLOW_ROLLOUT ou FAST_ROLLOUT. Para usar um plano de lançamento personalizado, substitua predefinedRolloutPlan por "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME".
  • RETRY_UUID: um UUID para tentar excluir uma política de extensão novamente. Defina esse campo apenas ao repetir uma solicitação de exclusão de uma política que está no estado DELETING. Definir esse campo quando a política não está no estado DELETING causa um erro. Para mais informações, consulte Repetir um lançamento.

Desinstalar extensões de VM em uma zona de uma organização

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de organização, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da organização (roles/compute.orgVmExtensionPolicyAdmin) na sua organização. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.orgVmExtensionPolicies.delete, necessária para excluir uma política de extensão com escopo de organização.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão zonal com escopo de organização, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute zone-vm-extension-policies delete com a flag --organization para excluir uma política de extensão de VM zonal no escopo da organização:

gcloud preview compute zone-vm-extension-policies delete POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --zone=ZONE

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

REST

Para excluir uma política de extensão zonal com escopo de organização, faça uma solicitação DELETE ao método organizationZoneVmExtensionPolicies.delete.

DELETE https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

Desinstalar extensões de VM em uma zona em uma pasta

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de pasta, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute no nível da pasta (roles/compute.folderVmExtensionPolicyAdmin) na sua pasta. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.folderVmExtensionPolicies.delete, que é necessária para excluir uma política de extensão com escopo de pasta.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão zonal com escopo de pasta, selecione uma das seguintes opções:

gcloud

Use o comando gcloud preview compute zone-vm-extension-policies delete com a flag --folder para excluir uma política de extensão de VM zonal com escopo de pasta:

gcloud preview compute zone-vm-extension-policies delete POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --zone=ZONE

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

REST

Para excluir uma política de extensão zonal com escopo de pasta, faça uma solicitação DELETE ao método folderZoneVmExtensionPolicies.delete.

DELETE https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • FOLDER_ID: o ID da pasta do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

Desinstalar extensões de VM em uma zona de um projeto

Permissões do IAM obrigatórias

Para receber a permissão necessária para excluir uma política de extensão com escopo de projeto, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM do Compute (roles/compute.vmExtensionPolicyAdmin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão compute.vmExtensionPolicies.delete, necessária para excluir uma política de extensão com escopo de projeto.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Para excluir uma política de extensão zonal com escopo de projeto, selecione uma das seguintes opções:

Console

Para excluir uma política de extensão de VM zonal com escopo de projeto no console do Google Cloud , siga estas etapas:

  1. No console do Google Cloud , acesse a página Políticas de extensão de VM.

    Acessar as políticas de extensão de VM

  2. Selecione a política que você quer excluir.
  3. Clique em Excluir.
  4. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Use o comando gcloud compute zone-vm-extension-policies delete para excluir uma política de extensão de VM zonal com escopo de projeto:

gcloud compute zone-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

REST

Para excluir uma política de extensão zonal com escopo de projeto, faça uma solicitação DELETE ao método zoneVmExtensionPolicies.delete.

DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/vmExtensionPolicies/POLICY_NAME

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • ZONE: a zona do Google Cloud em que a política está localizada.

A seguir