Instalar extensões de VM criando políticas de extensão

Neste documento, descrevemos como criar políticas de extensão de VM, que permitem instalar e gerenciar automaticamente extensões em uma frota de máquinas virtuais (VMs) do Compute Engine. Ao definir uma política, você garante que extensões específicas sejam instaladas e mantidas em todas as VMs que correspondam aos critérios especificados, como rótulos de VM. É possível criar políticas de extensão de VM zonais ou globais no nível do projeto ou nos níveis da organização e da pasta (disponível em pré-lançamento).

Antes de começar

Limitações de criação de políticas

Só é possível criar 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.

Prioridade de políticas e resolução de conflitos

Quando várias políticas em diferentes níveis de hierarquia (organização, pasta ou projeto) se aplicam à mesma VM, o nível de hierarquia não determina a precedência. Em vez disso, o Gerenciador de Extensões de VM usa a prioridade da política e os carimbos de data/hora de atualização para resolver conflitos.

Quando duas políticas entram em conflito para a mesma extensão, aquela com a prioridade mais alta tem precedência. Os valores de prioridade variam de 0 a 65535, em que um número menor significa uma prioridade mais alta. A prioridade 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. A exclusão de uma política não remove a extensão se uma política de prioridade mais baixa ainda se aplicar à VM.

Instalar extensões de VM criando uma política global de extensão de VM

É possível criar uma política global de extensão de VM para instalar extensões em VMs em várias zonas de acordo com um plano de lançamento. É possível definir uma política global no nível do projeto, da pasta ou da organização (disponível em pré-lançamento).

O Gerenciador de Extensões de VM não aplica uma política global de extensão de VM diretamente às VMs. Em vez disso, conforme a política é lançada, o Gerenciador de Extensões de VM replica automaticamente a definição global nas políticas zonais correspondentes em cada zona com base no plano de lançamento. Depois que uma política replicada fica disponível em uma zona, o Gerenciador de extensões de VM avalia as VMs nessa zona em relação aos rótulos de inclusão da política e instala ou atualiza as extensões designadas. Quando você cria novas VMs, o Gerenciador de Extensões de VM as avalia e configura automaticamente.

Planos de lançamento para políticas globais

As políticas globais de extensão de VM usam planos de lançamento para gerenciar a implantação de extensões em diferentes locais. É possível usar um dos planos de lançamento predefinidos ou criar um plano de lançamento personalizado.

Planos de lançamento predefinidos

Você pode selecionar um dos seguintes planos de lançamento predefinidos:

  • slow_rollout: lança a política ao longo de cinco dias. O lançamento lento é o plano de lançamento padrão.
  • fast_rollout: lança a política imediatamente em todas as zonas.

Planos de lançamento personalizados

É possível criar planos de lançamento personalizados usando o método rolloutPlans.insert. Por exemplo, o JSON a seguir define um plano de lançamento chamado test-rollout-plan que segmenta duas zonas:

{
  "name": "test-rollout-plan",
  "waves": [
    {
      "selectors": [
        {
          "locationSelector": {
            "includedLocations": [
              "us-central1-a",
              "us-west1-a"
            ]
          }
        }
      ],
      "validation": {
        "type": "time",
        "timeBasedValidationMetadata": {
          "waitDuration": "0s"
        }
      },
      "orchestrationOptions": {
        "maxConcurrentResourcesPerLocation": "10",
        "maxConcurrentLocations": "10"
      }
    }
  ]
}

Em seguida, use esse plano de lançamento personalizado ao criar uma política global.

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

Crie uma política de extensão global com escopo de organização para instalar e manter extensões de VM em todas as zonas de todos os projetos descendentes da sua organização.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão global com escopo de organização, selecione uma das seguintes opções:

gcloud

Para criar uma política global de extensão de VM no escopo da organização, use o comando gcloud preview compute global-vm-extension-policies create com a flag --organization:

gcloud preview compute global-vm-extension-policies create 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

Substitua:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • ORGANIZATION_ID: o ID da organização para a política com escopo de organização. O formato do recurso é organizations/{organization}/global/vmExtensionPolicies/{name}.
  • 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.

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

O comando a seguir cria uma política global de alta prioridade chamada prod-frontend-policy no nível da organização (organizations/123456789) para cargas de trabalho de front-end de produção (env=prod,workload=frontend), fixando uma versão específica para a extensão ops-agent com um plano de lançamento lento:

gcloud preview compute global-vm-extension-policies create prod-frontend-policy \
  --organization=organizations/123456789 \
  --description="Standard monitoring policy for production frontend VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config=ops-agent="some-monitoring-config" \
  --inclusion-labels="env=prod,workload=frontend" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Para criar uma política de extensão de VM global com escopo de organização, envie uma solicitação POST ao método organizationGlobalVmExtensionPolicies.insert:

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • ORGANIZATION_ID: o ID da organização.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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.

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

O exemplo a seguir cria uma política global chamada org-global-extension-policy que instala a extensão ops-agent para a organização 123456789 em VMs com o rótulo env=prod, com prioridade 100 e um plano de lançamento predefinido SLOW_ROLLOUT:

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

{
"name": "org-global-extension-policy",
"description": "Standard monitoring policy for organization VMs",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

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

Crie uma política de extensão global com escopo de pasta para instalar e manter extensões de VM em todas as zonas de todos os projetos descendentes da sua pasta.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão global com escopo de pasta, selecione uma das seguintes opções:

gcloud

Para criar uma política de extensão de VM global com escopo de pasta, use o comando gcloud preview compute global-vm-extension-policies create com a flag --folder:

gcloud preview compute global-vm-extension-policies create 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

Substitua:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • FOLDER_ID: o ID da pasta para a política com escopo de pasta. O formato do recurso é folders/{folder}/global/vmExtensionPolicies/{name}.
  • 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.

Exemplo: criar uma política global com escopo de pasta

O comando a seguir cria uma política global chamada folder-global-extension-policy no nível da pasta (folders/123456) que instala a extensão ops-agent em VMs com o rótulo env=prod usando um plano de lançamento lento:

gcloud preview compute global-vm-extension-policies create folder-global-extension-policy \
  --folder=folders/123456 \
  --description="Standard monitoring policy for folder VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --inclusion-labels="env=prod" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Para criar uma política de extensão de VM global com escopo de pasta, envie uma solicitação POST ao método folderGlobalVmExtensionPolicies.insert:

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • FOLDER_ID: o ID da pasta.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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.

Exemplo: criar uma política global com escopo de pasta

O exemplo a seguir cria uma política global chamada folder-global-extension-policy que instala a extensão ops-agent para a pasta 123456 em VMs com o rótulo env=prod, com prioridade 500 e um plano de lançamento predefinido SLOW_ROLLOUT:

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

{
"name": "folder-global-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

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

Crie uma política de extensão global com escopo de projeto para instalar e manter extensões de VM em todas as zonas do projeto.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão global com escopo de projeto, selecione uma das seguintes opções:

Console

Para criar 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 Criar política de extensão.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. 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.
  6. Na seção Escopo, selecione Lançamento global.
  7. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte para cada extensão que você quer instalar nas VMs de destino:
    1. Na lista Extensão, selecione uma opção. Para mais informações, consulte Extensões compatíveis.
    2. Na lista Versão, especifique o número da versão da extensão. Deixe em branco para selecionar a versão mais recente.
      • Para o Agente de Operações, especifique a versão 2.58.0 ou mais recente.
      • Para a extensão para SAP e a extensão para cargas de trabalho de computação, deixe o campo em branco para selecionar a versão mais recente.
    3. Opcional: no campo Conteúdo do arquivo de configuração, insira os parâmetros de configuração da extensão.
  8. No campo Plano de lançamento, selecione um plano de lançamento entre as seguintes opções:
    • Lançamento lento: instala extensões gradualmente em toda a frota de VMs ao longo de um período. Esse plano de lançamento é a opção padrão.
    • Lançamento rápido: instala extensões em todas as VMs segmentadas em todas as zonas e regiões imediatamente.

    Para mais informações sobre planos de lançamento, consulte Planos de lançamento.

  9. Na seção Instâncias de VM de destino, selecione as VMs para a política. Para selecionar VMs com rótulos específicos, clique em Adicionar rótulos e inclua o par de chave-valor.
  10. Clique em Criar.

gcloud

Para criar uma política de extensão de VM global com escopo de projeto, use o comando gcloud compute global-vm-extension-policies create:

gcloud compute global-vm-extension-policies create 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

Substitua:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o ID do projeto da política com escopo de projeto.
  • 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 do projeto em todas as zonas.
  • 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.

Exemplo: criar uma política global com escopo de projeto

O comando a seguir cria uma política chamada global-test-extension-policy que instala a extensão ops-agent para o projeto test-project. A flag --config-from-file especifica o caminho para um arquivo local que contém uma configuração YAML para o Agente de Operações, e --rollout-predefined-plan especifica o plano slow_rollout.

gcloud compute global-vm-extension-policies create global-test-extension-policy \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --rollout-predefined-plan=slow_rollout

Exemplo: criar uma política global com escopo de projeto com um plano de lançamento personalizado

O comando a seguir cria uma política chamada global-test-extension-policy-2 que instala a extensão ops-agent para o projeto test-project em VMs com o rótulo env=prod. A prioridade da política é definida como 500, e a sinalização --config-from-file especifica o caminho para um arquivo local que contém uma configuração YAML para o Agente de Operações. A flag --rollout-custom-plan especifica um plano de lançamento personalizado.

gcloud compute global-vm-extension-policies create global-test-extension-policy-2 \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod \
  --rollout-custom-plan=projects/12345678/locations/global/rolloutPlans/test-rollout-plan

REST

Para criar uma política de extensão de VM global com escopo de projeto, envie uma solicitação POST ao método globalVmExtensionPolicies.insert.

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Substitua:

  • PROJECT_ID: o ID do projeto.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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 do projeto em todas as zonas.
  • 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.

Exemplo: criar uma política global com escopo de projeto

O exemplo a seguir cria uma política chamada global-test-extension-policy que instala a extensão ops-agent para o projeto 12345678 em VMs com o rótulo env=prod. A prioridade da política é definida como 500 e usa o plano de lançamento test-rollout-plan.

POST https://compute.googleapis.com/compute/v1/projects/12345678/global/vmExtensionPolicies

{
"name": "global-test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "name": "projects/12345678/locations/global/rolloutPlans/test-rollout-plan"
  }
}
}

Instalar extensões de VM criando uma política de extensão de VM zonal

É possível criar uma política de extensão de VM zonal para definir quais extensões instalar e em quais VMs em uma zona específica. É possível definir uma política zonal no nível do projeto, da pasta ou da organização (disponível em pré-lançamento).

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

Crie uma política de extensão zonal com escopo de organização para instalar e manter extensões de VM em uma zona específica em todos os projetos descendentes da sua organização.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão zonal com escopo de organização, selecione uma das seguintes opções:

gcloud

Para criar uma política de extensão de VM zonal com escopo de organização e lançar a política para VMs em uma zona específica, use o comando gcloud preview compute zone-vm-extension-policies create com a flag --organization:

gcloud preview compute zone-vm-extension-policies create 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: um nome para a política de extensão de VM.
  • ORGANIZATION_ID: o ID da organização para a política com escopo de organização. O formato do recurso é organizations/{organization}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: a zona em que essa 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.

O comando vai falhar se já houver uma política com o nome especificado na zona.

Exemplo: criar uma política zonal com escopo de organização

O comando a seguir cria uma política zonal chamada org-test-extension-policy que instala a extensão ops-agent na zona us-central1-f para a organização organizations/123456789 em VMs com o rótulo env=prod:

gcloud preview compute zone-vm-extension-policies create org-test-extension-policy \
  --organization=organizations/123456789 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=100 \
  --inclusion-labels=env=prod

REST

Para criar uma política de extensão de VM zonal com escopo de organização, envie uma solicitação POST ao método organizationZoneVmExtensionPolicies.insert. Esse método define quais extensões instalar e em quais VMs em uma zona específica da organização.

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Substitua:

  • ORGANIZATION_ID: o ID da organização.
  • ZONE: a zona em que essa política se aplica.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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 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.

Exemplo: criar uma política zonal com escopo de organização

O exemplo a seguir cria uma política chamada org-test-extension-policy que instala a extensão ops-agent na zona us-central1-f para a organização 123456789.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/123456789/zones/us-central1-f/vmExtensionPolicies

{
"name": "org-test-extension-policy",
"description": "Test extension policy for Ops Agent at organization level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100"
}

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

Crie uma política de extensão zonal com escopo de pasta para instalar e manter extensões de VM em uma zona específica em todos os projetos descendentes da sua pasta.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão zonal com escopo de pasta, selecione uma das seguintes opções:

gcloud

Para criar uma política de extensão de VM zonal com escopo de pasta e implantar a política em VMs em uma zona específica, use o comando gcloud preview compute zone-vm-extension-policies create com a flag --folder:

gcloud preview compute zone-vm-extension-policies create 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: um nome para a política de extensão de VM.
  • FOLDER_ID: o ID da pasta para a política com escopo de pasta. O formato do recurso é folders/{folder}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: a zona em que essa 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.

O comando vai falhar se já houver uma política com o nome especificado na zona.

Exemplo: criar uma política zonal com escopo de pasta

O comando a seguir cria uma política zonal chamada folder-test-extension-policy que instala a extensão ops-agent na zona us-central1-f para a pasta folders/123456 em VMs com o rótulo env=prod:

gcloud preview compute zone-vm-extension-policies create folder-test-extension-policy \
  --folder=folders/123456 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Para criar uma política de extensão de VM zonal com escopo de pasta, envie uma solicitação POST ao método folderZoneVmExtensionPolicies.insert. Esse método define quais extensões instalar e em quais VMs em uma zona específica na pasta.

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Substitua:

  • FOLDER_ID: o ID da pasta.
  • ZONE: a zona em que essa política se aplica.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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.

Exemplo: criar uma política zonal com escopo de pasta

O exemplo a seguir cria uma política chamada folder-test-extension-policy que instala a extensão ops-agent na zona us-central1-f para a pasta 123456.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/123456/zones/us-central1-f/vmExtensionPolicies

{
"name": "folder-test-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

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

Crie uma política de extensão zonal com escopo de projeto para instalar e manter extensões de VM em uma zona específica do projeto.

Permissões do IAM obrigatórias

Para receber a permissão necessária para criar 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.create, que é necessária para criar 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 criar uma política de extensão zonal com escopo de projeto, selecione uma das seguintes opções:

Console

Para criar 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. Clique em Criar política de extensão.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. 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.
  6. Na seção Escopo, selecione Lançamento por zona.
  7. Nas listas Região e Zona, selecione a região e a zona em que as VMs estão localizadas. O Gerenciador de extensões de VM aplica a política às VMs na região e na zona selecionadas.
  8. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte para cada extensão que você quer instalar nas VMs de destino:
    1. Na lista Extensão, selecione uma opção. Para mais informações, consulte Extensões compatíveis.
    2. Na lista Versão, especifique o número da versão da extensão. Deixe em branco para selecionar a versão mais recente.
      • Para o Agente de Operações, especifique a versão 2.58.0 ou mais recente.
      • Para a extensão para SAP e a extensão para cargas de trabalho de computação, deixe o campo em branco para selecionar a versão mais recente.
    3. Opcional: no campo Conteúdo do arquivo de configuração, insira os parâmetros de configuração da extensão.
  9. Na seção Instâncias de VM de destino, selecione as VMs para a política. Para selecionar VMs com rótulos específicos, clique em Adicionar rótulos e inclua o par de chave-valor.
  10. Clique em Criar.

gcloud

Para criar uma política de extensão de VM zonal com escopo de projeto e implementá-la em VMs em uma zona específica, use o comando gcloud compute zone-vm-extension-policies create:

gcloud compute zone-vm-extension-policies create 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: um nome para a política de extensão de VM.
  • PROJECT_ID: o ID do projeto da política com escopo de projeto.
  • ZONE: a zona em que essa 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.

O comando vai falhar se já houver uma política com o nome especificado na zona.

Exemplo: criar uma política zonal com escopo de projeto

O comando a seguir cria uma política chamada test-extension-policy que instala a extensão ops-agent na zona us-central1-f para o projeto test-project. A flag --config-from-file especifica o caminho para um arquivo local que contém uma configuração YAML para o Agente de Operações.

gcloud compute zone-vm-extension-policies create test-extension-policy \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

Exemplo: criar uma política zonal com escopo de projeto com rótulos de inclusão e prioridade

O comando a seguir cria uma política chamada test-extension-policy-2 que instala a extensão ops-agent na zona us-central1-f para o projeto test-project em VMs com o rótulo env=prod. A prioridade da política é definida como 500, e a sinalização --config-from-file especifica o caminho para um arquivo local que contém uma configuração YAML para o Agente de Operações.

gcloud compute zone-vm-extension-policies create test-extension-policy-2 \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Para criar uma política de extensão de VM zonal com escopo de projeto, envie uma solicitação POST ao método zoneVmExtensionPolicies.insert. Esse método define quais extensões instalar e em quais VMs em uma zona específica.

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

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Substitua:

  • PROJECT_ID: o ID do projeto.
  • ZONE: a zona em que essa política se aplica.
  • POLICY_NAME: um nome para a política de extensão de VM.
  • DESCRIPTION: uma descrição opcional da política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: o nome da extensão a ser adicionada à 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_CONFIG, EXTENSION_NAME_2_CONFIG: a configuração da extensão, fornecida como uma string inline.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: 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.
  • KEY_1: VALUE_1: um par de chave-valor que define 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 vários instanceSelectors, a política vai segmentar 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.

Exemplo: criar uma política zonal com escopo de projeto

O exemplo a seguir cria uma política chamada test-extension-policy que instala a extensão ops-agent na zona us-central1-f para my-project.

POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/vmExtensionPolicies

{
"name": "test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

A seguir