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.

Antes de começar

Papéis necessários do IAM

Para receber a permissão necessária para criar uma política de extensão, peça ao administrador para conceder a você o papel do IAM de Administrador de políticas de extensão de VM (roles/compute.vmExtensionPolicyAdmin). 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, necessária para criar uma política de extensão.

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

Para mais informações sobre papéis e permissões do IAM no Compute Engine, consulte Papéis e permissões do Compute Engine.

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

Quando várias políticas são aplicadas à mesma VM, o VM Extension Manager usa a prioridade da política para resolver conflitos.

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

Criar 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 do projeto de acordo com um plano de lançamento. Uma política global de extensão de VM não é aplicada diretamente às VMs. Em vez disso, à medida que a política é lançada, o VM Extension Manager cria políticas em cada zona com base no plano de lançamento. Essas políticas gerenciam a instalação de extensões em VMs nas respectivas zonas.

É possível usar o gcloud ou o método globalVmExtensionPolicies.insert para criar políticas de extensão global.

Sobre os planos de lançamento

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. Você pode usar um dos planos de lançamento predefinidos ou criar um personalizado.

Planos de lançamento predefinidos

  • slow_rollout: implanta a política em cinco dias. O lançamento lento é o plano padrão.
  • fast_rollout: implanta 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 tem como destino 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, como mostrado no Exemplo 2.

Criar uma política global

Use o comando gcloud beta compute global-vm-extension-policies create para criar uma política global de extensão de VM:

  gcloud beta compute global-vm-extension-policies create POLICY_NAME 

      --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.
  • 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. É preciso especificar pelo menos uma extensão. Os valores válidos para as extensões são:
    • 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 dela. 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 automático quando novas versões forem lançadas.

  • 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". Você pode 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 VMs que correspondem 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 que define a prioridade da política. Números maiores indicam prioridade mais alta. O valor padrão é 0. Se várias políticas tiverem a mesma prioridade, a que foi atualizada mais recentemente será aplicada às VMs.

  • ROLLOUT_PLAN: especifique slow_rollout ou fast_rollout. Se você precisar usar um plano de lançamento personalizado, use a flag --rollout-custom-plan em vez de --rollout-predefined-plan e especifique o nome do plano, por exemplo:

      --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Substitua:

    • PROJECT_NUMBER: o projeto em que o plano de lançamento é definido.
    • ROLLOUT_PLAN_NAME: o nome do plano de lançamento personalizado que você definiu. Se nenhuma flag de plano de lançamento for especificada, slow_rollout será usada.

  • ROLLOUT_CONFLICT_BEHAVIOR: especifica o comportamento quando um conflito é detectado entre uma política zonal e uma global. Os valores possíveis são:

    • "" (string vazia): o valor da política zonal é usado.

    • overwrite: a política global substitui a política zonal.

      Para mais detalhes, consulte a flag --rollout-conflict-behavior.

    Exemplo 1

    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 do Agente de operações, e --rollout-predefined-plan especifica o plano slow_rollout.

    gcloud beta 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 2

    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 flag --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 beta 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

Criar uma política de extensão de VM zonal

Use um dos métodos a seguir para criar uma política de extensão de VM zonal. Essa política zonal define quais extensões instalar e em quais VMs em uma zona específica.

Console

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

    Acessar políticas de extensão de VM

  2. Clique em Criar política de extensão.
  3. No campo Nome, digite 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 maior prioridade. O valor padrão é 1000.
  6. Na lista Zona, selecione a zona em que você quer aplicar essa política.
  7. Na seção 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. 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. 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.
  9. Clique em Criar.

gcloud

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

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
    --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.
  • 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. É preciso especificar pelo menos uma extensão. Os valores válidos para as extensões são:
    • 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 automático quando novas versões forem lançadas.

  • 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 caminho está 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 VMs que correspondem 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.

  • PRIORITY: um número inteiro de 0 a 65535 que define a prioridade da política. Números menores indicam maior prioridade. O valor padrão é 1000.

    O comando falha se já existir uma política com o nome especificado na zona.

Exemplo 1

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 do Agente de operações.

gcloud beta 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 2

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 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 beta 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

A seguir