Como usar a API de instância em massa


Este documento descreve a API da instância em massa e como usá-la para criar várias VMs homogêneas independentes umas das outras.

O uso da API de instância em massa é diferente da agregação de várias solicitações de API de inserção de instâncias em uma solicitação HTTP usando o processamento de solicitações da API em lote. Além disso, as instâncias criadas com a API de instância em massa não são gerenciadas para você.

A tabela a seguir compara a API instances.insert com a API instances.bulkInsert.

Funcionalidade instances.insert instances.bulkInsert
Seleção de zona
Selecionada automaticamente com base em considerações como disponibilidade de recursos e cota
Manual Automático ao usar o endpoint regional
Validação antecipada
A solicitação falhará imediatamente se não for viável
Não Com capacidade e cota
Geração de nome de VM
Gerada automaticamente com base em um padrão de nome especificado
Manual Gerado automaticamente (opcional)
Reverter automaticamente
A solicitação é revertida automaticamente se o Compute Engine não puder criar o número de VMs de destino
Não Opcionalmente ativado
Limitação de taxa de API
Como as solicitações afetam a limitação da taxa da API
Por solicitação de instância Por solicitação de instância em massa

Se quiser permitir que o Compute Engine gerencie as VMs para você, use grupos gerenciados de instâncias.

Considerações

Ao seguir as instruções deste documento para usar a API da instância em massa, lembre-se do seguinte:

  • A API de instâncias em massa permite emitir solicitações regionais ou por zona. Se a solicitação for regional, o Compute Engine determinará a zona para criar as VMs com base nas zonas que têm hardware disponível, considerando a capacidade disponível em cada zona e em qualquer uma das suas reservas. Para essas solicitações regionais, o Compute Engine determina uma única zona para colocar as VMs. Para colocar as VMs em zonas diferentes, emita solicitações separadas para elas. Este documento contém um exemplo de pseudocódigo que mostra como fazer isso.

  • As solicitações para a API de instância em massa consomem o mesmo limite de taxa da API que as solicitações para criar VMs individuais. Para fins de limitação de taxa, cada solicitação de API em lote conta como uma única solicitação, independentemente do número de VMs sendo criadas. Se você não tiver cota suficiente, a solicitação falhará imediatamente, receberá um erro rateLimitExceeded e o Compute Engine não criará VMs.

  • Para simplificar a visualização das VMs no Console do Google Cloud ou usar o Cloud Monitoring, considere adicionar as VMs a um grupo de instâncias não gerenciadas. Esses grupos não fornecem o gerenciamento do ciclo de vida da VM ou do balanceamento de carga. Para agrupar as VMs sem usar um grupo de instâncias não gerenciadas, é possível usar rótulos.

Preços

Não há custo extra para seguir as instruções deste documento para usar a API da instância em massa. Assim como a criação de VMs únicas, o faturamento começa quando você cria as VMs.

Se, ao usar a API de instância em massa, o Compute Engine não criar nenhuma VM, você só será cobrado pelas VMs criadas pelo Compute Engine.

Antes de começar

Como criar VMs com a API de instância em massa

Seguindo os procedimentos abaixo, você pode usar a API de instância em massa para criar várias VMs em uma região ou zona.

Como criar várias VMs em uma região

Os procedimentos a seguir mostram como usar a API de instância em massa para criar várias VMs em uma região específica. Ao fazer isso, o Compute Engine determina a zona.

Se você especificar um tipo de máquina ou suporte para hardware adicional, como uma GPU ou um SSD local, o Compute Engine colocará as VMs em uma zona dentro da região que seja compatível com o tipo de máquina e o hardware extra.

gcloud

Use o comando gcloud compute instances bulk create com as sinalizações necessárias para criar várias VMs em uma região.

gcloud compute instances bulk create \
  ( --name-pattern="NAME_PATTERN" | --predefined-names=[PREDEFINED_NAMES] )\
  --region=REGION \
  --count=COUNT \
  [ --min-count=MIN_COUNT ]

Substitua:

  • NAME_PATTERN: o padrão de nome para as VMs. Use uma sequência de caracteres de hash (#) no Compute Engine para substituir por uma sequência de números. Por exemplo, usar vm-# para o padrão de nome gera VMs com nomes vm-1, vm-2 e assim por diante, até o número de VMs especificadas por --count, que precisa ser menor ou igual ao número de VMs que o padrão de nome permite.

    Ao usar um padrão de nome, o Compute Engine tenta evitar conflitos de nome verificando os nomes das VMs existentes criadas com base nas solicitações anteriores. Além disso, poderá haver conflitos de nome se você estiver usando o DNS global. Para evitar conflitos de nome ao usar o DNS global, alterne para DNS por zona. Se não for possível alternar para o DNS por zona, evite usar o mesmo padrão de nome em diferentes regiões.

  • PREDEFINED_NAMES: uma lista de nomes predefinidos das VMs a serem criadas. Se estiver usando essa sinalização e especificando COUNT, COUNT precisa ser igual ao número de nomes fornecidos.

  • REGION: a região em que as VMs serão criadas.

  • COUNT: o número de VMs a serem criadas. Precisa ser menor ou igual ao número de VMs permitidas por NAME_PATTERN. Ou, se estiver usando --predefined-names, não é necessário especificar COUNT, mas se fizer isso, ele precisará ser igual ao número de nomes fornecidos.

  • MIN_COUNT: uma sinalização opcional que especifica o número mínimo de VMs a serem criadas. A tabela a seguir descreve o comportamento da solicitação, dependendo de como você definir essa sinalização:

    Configuração Descrição
    Não definido O valor padrão é COUNT e, se o Compute Engine não conseguir criar VMs COUNT, a solicitação não será validada e nenhuma VM será criada.
    Defina como 1. O Compute Engine cria o máximo de VMs possível, até COUNT.
    Maior que 1 e menor que COUNT O Compute Engine tenta criar pelo menos MIN_COUNT VMs até, no máximo, COUNT VMs. A solicitação será bem-sucedida se o Compute Engine criar pelo menos MIN_COUNT VMs.

API

Use o método instances.bulkInsert com os parâmetros necessários para criar várias VMs em uma região.

POST https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert

{
  ...
  "namePattern": "NAME_PATTERN",
  "perInstanceProperties": {
    "PREDEFINED_NAME_1": {},
    "PREDEFINED_NAME_2": {},
    ...
  },
  "count": COUNT,
  "minCount": MIN_COUNT,
  ...
}

Substitua:

  • PROJECT_ID: o ID do projeto;

  • REGION: a região em que as VMs serão criadas.

  • NAME_PATTERN: o padrão de nome para as VMs. Especifique esse ou perInstanceProperties. Use uma sequência de caracteres de hash (#) no Compute Engine para substituir por uma sequência de números. Por exemplo, usar vm-# para o padrão de nome gera VMs com nomes vm-1, vm-2 e assim por diante, até o número de VMs especificadas por --count, que precisa ser menor ou igual ao número de VMs que o padrão de nome permite.

    Ao usar um padrão de nome, o Compute Engine tenta evitar conflitos de nome verificando os nomes das VMs existentes criadas com base nas solicitações anteriores. Além disso, poderá haver conflitos de nome se você estiver usando o DNS global. Para evitar conflitos de nome ao usar o DNS global, alterne para DNS por zona. Se não for possível alternar para o DNS por zona, evite usar o mesmo padrão de nome em diferentes regiões.

  • PREDEFINED_NAME_1, PREDEFINED_NAME_2, ...: uma lista de nomes predefinidos das VMs a serem criadas. Especifique esse ou namePattern. Se estiver usando essa sinalização e especificando COUNT, COUNT precisará ser igual ao número de nomes fornecidos.

  • COUNT: o número de VMs a serem criadas. Precisa ser menor ou igual ao número de VMs permitidas por NAME_PATTERN. Ou, se estiver usando perInstanceProperties, não é necessário especificar COUNT, mas se fizer isso, ele precisará ser igual ao número de nomes fornecidos.

  • MIN_COUNT: uma sinalização opcional que especifica o número mínimo de VMs a serem criadas. A tabela a seguir descreve o comportamento da solicitação, dependendo de como você definir essa sinalização:

    Configuração Descrição
    Não definido O valor padrão é COUNT e, se o Compute Engine não puder criar VMs COUNT, ele reverterá a solicitação.
    Defina como 1. O Compute Engine cria o máximo de VMs possível, até COUNT.
    Maior que 1 e menor que COUNT O Compute Engine tenta criar pelo menos MIN_COUNT VMs até, no máximo, COUNT VMs. A solicitação será bem-sucedida se o Compute Engine criar pelo menos MIN_COUNT VMs.

Como criar várias VMs em uma zona específica

Os procedimentos a seguir mostram como usar a API da instância em massa para criar várias VMs em uma zona.

gcloud

Use o comando gcloud compute instances bulk create com as sinalizações necessárias para criar várias VMs em uma zona.

gcloud compute instances bulk create \
  ( --name-pattern="NAME_PATTERN" | --predefined-names=[PREDEFINED_NAMES] )\
  --zone=ZONE \
  --count=COUNT \
  [ --min-count=MIN_COUNT ]

Substitua:

  • NAME_PATTERN: o padrão de nome para as VMs. Use uma sequência de caracteres de hash (#) no Compute Engine para substituir por uma sequência de números. Por exemplo, usar vm-# para o padrão de nome gera VMs com nomes vm-1, vm-2 e assim por diante, até o número de VMs especificadas por --count, que precisa ser menor ou igual ao número de VMs que o padrão de nome permite.

    Ao usar um padrão de nome, o Compute Engine tenta evitar conflitos de nome verificando os nomes das VMs existentes criadas com base nas solicitações anteriores. Além disso, poderá haver conflitos de nome se você estiver usando o DNS global. Para evitar conflitos de nome ao usar o DNS global, alterne para DNS por zona. Se não for possível alternar para o DNS por zona, evite usar o mesmo padrão de nome em diferentes regiões.

  • PREDEFINED_NAMES: uma lista de nomes predefinidos das VMs a serem criadas. Se estiver usando essa sinalização e especificando COUNT, COUNT precisa ser igual ao número de nomes fornecidos.

  • ZONE: zona em que as VMs serão criadas.

  • COUNT: o número de VMs a serem criadas. Precisa ser menor ou igual ao número de VMs permitidas por NAME_PATTERN. Ou, se estiver usando --predefined-names, não é necessário especificar COUNT, mas se fizer isso, ele precisará ser igual ao número de nomes fornecidos.

  • MIN_COUNT: uma sinalização opcional que especifica o número mínimo de VMs a serem criadas. A tabela a seguir descreve o comportamento da solicitação, dependendo de como você definir essa sinalização:

    Configuração Descrição
    Não definido O valor padrão é COUNT e, se o Compute Engine não puder criar VMs COUNT, ele reverterá a solicitação.
    Defina como 1. O Compute Engine cria o máximo de VMs possível, até COUNT.
    Maior que 1 e menor que COUNT O Compute Engine tenta criar pelo menos MIN_COUNT VMs até, no máximo, COUNT VMs. A solicitação será bem-sucedida se o Compute Engine criar pelo menos MIN_COUNT VMs.

API

Use o método instances.bulkInsert com os parâmetros necessários para criar várias VMs em uma zona.

POST https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert

{
  ...
  "namePattern": "NAME_PATTERN",
  "perInstanceProperties": {
    "PREDEFINED_NAME_1": {},
    "PREDEFINED_NAME_2": {},
    ...
  },
  "count": COUNT,
  "minCount": MIN_COUNT,
  ...
}

Substitua:

  • PROJECT_ID: o ID do projeto;

  • ZONE: zona em que as VMs serão criadas.

  • NAME_PATTERN: o padrão de nome para as VMs. Especifique esse ou perInstanceProperties. Use uma sequência de caracteres de hash (#) no Compute Engine para substituir por uma sequência de números. Por exemplo, usar vm-# para o padrão de nome gera VMs com nomes vm-1, vm-2 e assim por diante, até o número de VMs especificadas por --count, que precisa ser menor ou igual ao número de VMs que o padrão de nome permite.

    Ao usar um padrão de nome, o Compute Engine tenta evitar conflitos de nome verificando os nomes das VMs existentes criadas com base nas solicitações anteriores. Além disso, poderá haver conflitos de nome se você estiver usando o DNS global. Para evitar conflitos de nome ao usar o DNS global, alterne para DNS por zona. Se não for possível alternar para o DNS por zona, evite usar o mesmo padrão de nome em diferentes regiões.

  • PREDEFINED_NAME_1, PREDEFINED_NAME_2, ...: uma lista de nomes predefinidos das VMs a serem criadas. Especifique esse ou namePattern. Se estiver usando essa sinalização e especificando COUNT, COUNT precisará ser igual ao número de nomes fornecidos.

  • COUNT: o número de VMs a serem criadas. Precisa ser menor ou igual ao número de VMs permitidas por NAME_PATTERN. Ou, se estiver usando perInstanceProperties, não é necessário especificar COUNT, mas se fizer isso, ele precisará ser igual ao número de nomes fornecidos.

  • MIN_COUNT: uma sinalização opcional que especifica o número mínimo de VMs a serem criadas. A tabela a seguir descreve o comportamento da solicitação, dependendo de como você definir essa sinalização:

    Configuração Descrição
    Não definido O valor padrão é COUNT e, se o Compute Engine não puder criar VMs COUNT, ele reverterá a solicitação.
    Defina como 1. O Compute Engine cria o máximo de VMs possível, até COUNT.
    Maior que 1 e menor que COUNT O Compute Engine tenta criar pelo menos MIN_COUNT VMs até, no máximo, COUNT VMs. A solicitação será bem-sucedida se o Compute Engine criar pelo menos MIN_COUNT VMs.

Como verificar o status das VMs criadas com a API de instância em massa

Depois de usar a API da instância em massa para criar várias VMs, use os procedimentos a seguir para verificar o status da solicitação para a API de instância em massa ou o status de uma única VM que fazia parte da solicitação para o API de instância em massa.

Como verificar o status de uma solicitação de instância em massa

Ao verificar o status de uma solicitação para a API de instância em massa, a operação em massa só retornará DONE se o Compute Engine criar o número mínimo de VMs especificadas ou reverter a solicitação.

Para informações sobre como verificar o status de uma solicitação para a API de instância em massa, consulte Como processar respostas da API.

Como verificar o status de uma única VM

A API da instância em massa cria Operations para cada VM, que contém o nome da VM e o status de criação.

O procedimento a seguir mostra como verificar o status de uma única VM que o Compute Engine criou como parte de um grupo de VMs com base em uma solicitação enviada para a API da instância em massa.

gcloud

  1. No Operation retornado pela solicitação à API da instância em massa, veja o valor da propriedade operationGroupId.

  2. Use a propriedade operationGroupId como um filtro com o comando gcloud compute operations list para pesquisar em todas as operações e zonas do projeto nas VMs associadas à solicitação regional ou por zona feitas para a API da instância em massa:

    gcloud compute operations list \
      --filter=(operationGroupId=OPERATION_GROUP_ID)
    
  3. Consiga o restante das propriedades da VM seguindo um destes procedimentos:

    • Na lista de operações, o targetLink representa o caminho da VM. Use o método gcloud compute instances describe com este caminho como o nome da VM para conseguir as propriedades completas da VM:

      gcloud compute instances describe VM_NAME
      
    • Use o método gcloud compute instances list com um filtro que inclua os nomes das VMs da lista de operações:

      gcloud compute instances list VM_NAME \
        --filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      
    • Use o comando gcloud compute instances list para acessar as propriedades das VMs de todas as zonas e regiões e filtre por um rótulo exclusivo das instâncias ou por seus nomes:

      gcloud compute instances list \
        --filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      

API

  1. No Operation retornado pela solicitação à API da instância em massa, veja o valor da propriedade operationGroupId.

  2. Use a propriedade operationGroupId como um filtro para conseguir a lista de operações da VM associadas à solicitação regional ou por zona feitas para a API da instância em massa:

    • Se você enviou uma solicitação regional para a API de instância em massa, use o método globalOperations.aggregatedList para pesquisar todas as operações e todas as zonas no projeto:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/aggregated/operations?filter=(operationGroupId=OPERATION_GROUP_ID)
      
    • Se você enviou uma solicitação por zona à API de instância em massa, use o método zoneOperations.get para listar as operações nessa zona:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/bulkInsert?filter=(operationGroupId=OPERATION_GROUP_ID)
      
  3. Consiga o restante das propriedades da VM seguindo um destes procedimentos:

    • Na lista de operações, o targetLink representa o caminho da VM. Use o método instances.get com este caminho como o nome da VM para conseguir as propriedades completas da VM:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME
      
    • Use o método instances.get com um filtro que inclua os nomes das VMs da lista de operações:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances?filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      
    • Use o método instances.aggregatedList para acessar as propriedades das VMs de todas as zonas e regiões e filtre por um rótulo exclusivo das instâncias ou por seus nomes:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/aggregated/instances?filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      

Exemplos de pseudocódigo

Os exemplos de pseudocódigo a seguir mostram como personalizar solicitações para a API da instância em massa.

Como criar várias VMs em zonas diferentes de uma região

Por padrão, quando você usa a API de instância em massa para criar várias VMs, o Compute Engine coloca todas elas na mesma zona. O procedimento a seguir descreve o pseudocódigo que mostra como criar até mil VMs que podem estar em zonas diferentes de uma região.

  1. Especifique o número de VMs a serem criadas e inicialize um contador para acompanhar o número de VMs à medida que são criadas.

    nTarget = 1000
    nCreated = 0
    
  2. Inicialize uma estrutura de dados com as zonas disponíveis em uma região. Use o método zones.list para receber uma lista de zonas disponíveis para seu projeto.

    zones = list of zones in region
    
  3. Faça a iteração na lista de zonas. Em cada iteração, chame a API em massa com minCount igual a 1 e atualize a contagem do número total de VMs criadas. Com minCount igual a 1, o Compute Engine cria o máximo de VMs possível, até o nTarget.

    for each zone in zones:
      call bulk API: zone=zone, minCount=1, count=(nTarget - nCreated)
      nCreated += (# of VMs created)
      if (vmsCreated == targetN)
        break
    

Como criar várias VMs em uma zona de qualquer região

O pseudocódigo a seguir descreve como usar a API de instância em massa para criar até mil VMs em uma zona dentro da região especificada. Ao tentar criar várias VMs em uma região fora de um conjunto de regiões designado, a solicitação primeiro verifica a capacidade. Se não houver capacidade suficiente, a solicitação falhará imediatamente e será feita de novo com a próxima região do conjunto.

  1. Especifique o número de VMs para criar dentro de uma zona.

    nTarget = 1000
    
  2. Designe as regiões em que você quer criar as VMs.

    acceptableRegions = ["us-central1", "us-east1", "us-west1"]
    
  3. Faça a iteração nas regiões e tente criar as VMs em cada região até ter sucesso.

    for region in acceptableRegions:
      call bulk API: region=region, count=nTarget
      if request succeeds and the operation succeeds:
        break
    

Como criar várias VMs em uma zona em um tipo de máquina

O pseudocódigo a seguir descreve como usar a API de instância em massa para criar várias VMs em uma zona em um dos tipos de máquina especificados. Ao tentar criar várias VMs do mesmo tipo, a solicitação verifica primeiro a disponibilidade desses tipos. Se não houver uma quantidade suficiente do tipo de máquina disponível, a solicitação falhará imediatamente e tentará de novo com o próximo tipo de máquina.

  1. Especifique o número de VMs a serem criadas e a região para criá-las.

    nTarget = 1000
    region = "us-central1"
    
  2. Especifique as famílias de máquinas para tentar criar as VMs.

    acceptableMachineFamilies = ["n2","c2","e2","n1"]
    
  3. Faça a iteração pelo conjunto de tipos de máquina e tente criar as VMs no tipo de máquina até ser bem-sucedido.

    for family in acceptableMachineFamilies:
      call bulk APIs: region=region, count=nTarget, machineFamily=family
      if request succeeds and the operation succeeds:
        break
    

Como criar mais de mil VMs em uma zona

Ao usar a API de instância em massa para criar VMs, só é possível criar mil VMs com cada solicitação. O pseudocódigo a seguir descreve como criar mais de mil VMs em uma zona emitindo várias solicitações.

  1. Especifique o número de VMs para criar, um contador para rastrear o número total de VMs criadas, a região onde as VMs serão criadas e uma variável para armazenar a zona em que o Compute Engine cria as VMs.

    nTarget = 10000
    nCreated = 0
    region = "us-central1"
    targetZone = ""
    
  2. Emita uma solicitação inicial para criar mil VMs, salvar a zona retornada pela solicitação e atualizar o contador do número de VMs criadas.

    call bulk API: region=region, count=1000
    targetZone = zone chosen by bulk API
    nCreated += # of VMs created
    
  3. Continue enviando solicitações para criar até mil VMs por vez na zona até que o Compute Engine crie o número especificado de VMs.

    while(nTarget - nCreated > 0):
      call bulk API: zone=targetZone, count=1000
      nCreated += # of VMs created
    

Como visualizar informações detalhadas sobre várias VMs

No procedimento a seguir, descrevemos o pseudocódigo que você pode usar para receber os detalhes das instâncias criadas usando nomes predefinidos com a API de instância em massa:

  1. Especifique o número de VMs para criar, a zona onde criá-las e uma estrutura de dados para armazenar os nomes.

    nTarget = 1000
    targetZone = "us-central-1a"
    names = []
    
  2. Gere os nomes padronizados das VMs e adicione os nomes à estrutura de dados.

    for n in range(0,1000):
      names.push("instance-%d".format(n))
    
  3. Crie as VMs e use perInstanceProperties para especificar os nomes.

    call bulk API(zone=targetZone, count=nTarget, names=perInstanceProperties)
    
  4. Use o método instances.list com um filtro para os nomes das VMs para retornar os detalhes das VMs.

    instances.list(filter=(name = "instance-1") OR (name = "instance-2") ...)
    

Limitações

Consulte a seguinte lista de limitações antes de usar a API de instância em massa:

  • Para cada solicitação, o limite para o número de VMs que podem ser criadas é mil. Para ver um exemplo de como emitir várias solicitações para criar mais de mil VMs, consulte o pseudocódigo neste documento.

  • Não é possível criar mais de 1.200 VMs de uma vez. Esse limite é compartilhado entre instances.insert e instances.bulkInsert.

  • Todas as propriedades da VM, exceto os nomes, precisam ser idênticas.

  • Não é possível usar propriedades de VM que sejam mutuamente exclusivas entre VMs, incluindo, entre outros:

    • Nomes de host personalizados
    • IPs externos estáticos
    • IPs internos estáticos
  • Não é possível usar a API de instância em massa para criar VMs que usam o seguinte:

    • Discos protegidos por chaves de criptografia fornecidas pelo cliente
    • Imagens de máquina
    • Rótulos de afinidade de nó de locatário individual
  • Se você estiver usando o DNS global, pode haver conflitos de nomes porque a zona não está incluída no nome de domínio totalmente qualificado (FQDN, na sigla em inglês). Para evitar isso, use o DNS por zona. Se não for possível alternar para o DNS por zona, evite usar o mesmo padrão de nome em diferentes regiões.

  • Raramente, depois que o Compute Engine valida uma solicitação para a API de instância em massa, a solicitação poderá falhar, por exemplo, se o Compute Engine não puder criar as VMs porque outra solicitação consumiu a cota disponível. Nesse caso, o Compute Engine reverte a solicitação e exclui as VMs que já foram criadas.

Registros de auditoria

O Compute Engine registra informações sobre a API de instância em massa no registro de auditoria de atividade do administrador no início e no final da solicitação.

O Compute Engine também cria registros de auditoria separados para cada VM. É possível encontrar o registro de auditoria de uma única VM combinando o valor de protoPayload.resourceName com o nome da VM gerado pelo padrão de nomenclatura.

A seguir