使用批量实例 API


本文档介绍了批量实例 API 以及如何使用它来创建彼此独立的多个同构虚拟机。

使用批量实例 API 不同于通过批处理 API 请求将多个实例插入 API 请求汇总到一个 HTTP 请求中。此外,使用批量实例 API 创建的实例不会为您代管。

下表将 instances.insert APIinstances.bulkInsert API 进行了比较。

功能 instances.insert instances.bulkInsert
可用区选择
根据诸如资源可用性和配额之类的考虑自动选择
手动 使用区域级端点时自动运行
预先验证
如果无法执行请求,请求会立即失败
包含容量和配额
虚拟机名称生成
根据指定的名称模式自动生成
手动 (可选)自动生成
自动回滚
如果 Compute Engine 无法创建目标虚拟机数量,请求将自动回滚
(可选)启用
API 速率限制
请求如何影响 API 速率限制
每个实例请求 每个批量实例请求

如果您希望 Compute Engine 为您管理虚拟机,请使用代管式实例组


注意事项

按照本文档中的说明使用批量实例 API 时,请注意以下几点:

  • 批量实例 API 让您可以发出区域级请求或可用区级请求。如果请求是区域性的,Compute Engine 会根据可用硬件所在的可用区确定要创建虚拟机的可用区,并将每个可用区的可用容量以及任何保留考虑在内。对于这些区域级请求,Compute Engine 会确定一个可用区来放置虚拟机。如需将虚拟机放在不同可用区,请向这些可用区发出单独的请求。本文档包含展示如何完成此操作的伪代码示例。

  • 向批量实例 API 发出的请求消耗的 API 速率限制与创建单个虚拟机的请求相同。为了速率限制,不论要创建多少个虚拟机,每个批量实例 API 请求算作单个请求。如果您没有足够的配额,请求会立即失败,您会收到 rateLimitExceeded 错误,并且 Compute Engine 不会创建任何虚拟机。

  • 如需简化在 Google Cloud Console 中查看虚拟机或使用 Cloud Monitoring 的情况,请考虑将虚拟机添加到非代管式实例组。非代管式实例组不提供虚拟机生命周期或负载平衡的管理。如需在不使用非代管式实例组的情况下对虚拟机进行分组,您可以使用标签。


价格

按照本文档中的说明使用批量实例 API 不收取额外费用。与创建单个虚拟机一样,在您创建虚拟机时开始计费。

如果使用批量实例 API 时 Compute Engine 未能创建任何虚拟机,您只需为 Compute Engine 成功创建的虚拟机付费。


准备工作


使用批量实例 API 创建虚拟机

按照以下过程使用批量实例 API 在一个区域或可用区中创建多个虚拟机。

在一个区域中创建多个虚拟机

以下步骤展示了如何使用批量实例 API 在特定区域中创建多个虚拟机。执行此操作时,Compute Engine 会确定可用区。

如果指定机器类型或支持其他硬件(如 GPU 或本地 SSD),则 Compute Engine 会将虚拟机放置在支持机器类型和其他硬件的区域的可用区中。

gcloud

使用带有必需标志的 gcloud compute instances bulk create 命令可在一个区域中创建多个虚拟机。

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

请替换以下内容:

  • NAME_PATTERN:虚拟机的名称模式。请使用哈希值 (#) 字符序列让 Compute Engine 将其替换为数字序列。例如,使用名称模式的 vm-# 可以生成名为 vm-1vm-2 等的虚拟机,最多为 --count 指定的虚拟机数量,必须小于或等于名称模式允许的虚拟机数量。

    使用名称模式时,Compute Engine 会尝试通过检查根据先前请求创建的现有虚拟机的名称来避免名称冲突。此外,如果您使用全球级 DNS,则可能会出现名称冲突。为避免使用全球级 DNS 产生的名称冲突,请切换到可用区级 DNS。如果您无法切换到可用区级 DNS,请避免在不同区域中使用相同名称模式。

  • PREDEFINED_NAMES:待创建虚拟机的预定义名称列表。如果使用此标志并指定 COUNT,则 COUNT 必须等于提供的名称数量。

  • REGION:要在其中创建虚拟机的区域。

  • COUNT:要创建的虚拟机数量。此值必须小于或等于 NAME_PATTERN 允许的虚拟机数量。或者,如果使用 --predefined-names,则无需指定 COUNT,但一旦使用,则必须等于提供的名称的数量。

  • MIN_COUNT:可选标志,用于指定要创建的虚拟机数下限。下表根据您设置此标志的方式介绍了请求的行为:

    设置 说明
    未设置 默认值为 COUNT,如果 Compute Engine 无法创建 COUNT 虚拟机,则不会验证请求,也不会创建虚拟机。
    设置为 1 Compute Engine 会创建尽可能多的虚拟机,最多 COUNT 个。
    大于 1 且小于 COUNT Compute Engine 会尝试创建至少 MIN_COUNT 个虚拟机(最多不超过 COUNT 个虚拟机)。如果 Compute Engine 至少创建了 MIN_COUNT 个虚拟机,则请求将成功。

API

使用带有必需参数的 instances.bulkInsert 方法可在一个区域中创建多个虚拟机。

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,
  ...
}

请替换以下内容:

  • PROJECT_ID:项目 ID。

  • REGION:要在其中创建虚拟机的区域。

  • NAME_PATTERN:虚拟机的名称模式。指定此值或 perInstanceProperties。请使用哈希值 (#) 字符序列让 Compute Engine 将其替换为数字序列。例如,使用名称模式的 vm-# 可以生成名为 vm-1vm-2 等的虚拟机,最多为 --count 指定的虚拟机数量,必须小于或等于名称模式允许的虚拟机数量。

    使用名称模式时,Compute Engine 会尝试通过检查根据先前请求创建的现有虚拟机的名称来避免名称冲突。此外,如果您使用全球级 DNS,则可能会出现名称冲突。为避免使用全球级 DNS 产生的名称冲突,请切换到可用区级 DNS。如果您无法切换到可用区级 DNS,请避免在不同区域中使用相同名称模式。

  • PREDEFINED_NAME_1PREDEFINED_NAME_2、...:待创建虚拟机的预定义名称列表。指定此值或 namePattern。如果使用此标志并指定 COUNT,则 COUNT 必须等于提供的名称数量。

  • COUNT:要创建的虚拟机数量。此值必须小于或等于 NAME_PATTERN 允许的虚拟机数量。或者,如果使用 perInstanceProperties,则无需指定 COUNT,但一旦使用,则必须等于提供的名称的数量。

  • MIN_COUNT:可选标志,用于指定要创建的虚拟机数下限。下表根据您设置此标志的方式介绍了请求的行为:

    设置 说明
    未设置 默认值为 COUNT,而且,如果 Compute Engine 无法创建 COUNT 虚拟机,它会回滚请求。
    设置为 1 Compute Engine 会创建尽可能多的虚拟机,最多 COUNT 个。
    大于 1 且小于 COUNT Compute Engine 会尝试创建至少 MIN_COUNT 个虚拟机(最多不超过 COUNT 个虚拟机)。如果 Compute Engine 至少创建了 MIN_COUNT 个虚拟机,则请求将成功。

在特定可用区创建多个虚拟机

以下过程介绍如何使用批量实例 API 在一个可用区创建多个虚拟机。

gcloud

使用带有必需标志的 gcloud compute instances bulk create 命令可在一个可用区中创建多个虚拟机。

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

请替换以下内容:

  • NAME_PATTERN:虚拟机的名称模式。请使用哈希值 (#) 字符序列让 Compute Engine 将其替换为数字序列。例如,使用名称模式的 vm-# 可以生成名为 vm-1vm-2 等的虚拟机,最多为 --count 指定的虚拟机数量,必须小于或等于名称模式允许的虚拟机数量。

    使用名称模式时,Compute Engine 会尝试通过检查根据先前请求创建的现有虚拟机的名称来避免名称冲突。此外,如果您使用全球级 DNS,则可能会出现名称冲突。为避免使用全球级 DNS 产生的名称冲突,请切换到可用区级 DNS。如果您无法切换到可用区级 DNS,请避免在不同区域中使用相同名称模式。

  • PREDEFINED_NAMES:待创建虚拟机的预定义名称列表。如果使用此标志并指定 COUNT,则 COUNT 必须等于提供的名称数量。

  • ZONE:要在其中创建虚拟机的可用区。

  • COUNT:要创建的虚拟机数量。此值必须小于或等于 NAME_PATTERN 允许的虚拟机数量。或者,如果使用 --predefined-names,则无需指定 COUNT,但一旦使用,则必须等于提供的名称的数量。

  • MIN_COUNT:可选标志,用于指定要创建的虚拟机数下限。下表根据您设置此标志的方式介绍了请求的行为:

    设置 说明
    未设置 默认值为 COUNT,而且,如果 Compute Engine 无法创建 COUNT 虚拟机,它会回滚请求。
    设置为 1 Compute Engine 会创建尽可能多的虚拟机,最多 COUNT 个。
    大于 1 且小于 COUNT Compute Engine 会尝试创建至少 MIN_COUNT 个虚拟机(最多不超过 COUNT 个虚拟机)。如果 Compute Engine 至少创建了 MIN_COUNT 个虚拟机,则请求将成功。

API

使用带有必需参数的 instances.bulkInsert 方法可在一个可用区中创建多个虚拟机。

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,
  ...
}

请替换以下内容:

  • PROJECT_ID:项目 ID。

  • ZONE:要在其中创建虚拟机的可用区。

  • NAME_PATTERN:虚拟机的名称模式。指定此值或 perInstanceProperties。请使用哈希值 (#) 字符序列让 Compute Engine 将其替换为数字序列。例如,使用名称模式的 vm-# 可以生成名为 vm-1vm-2 等的虚拟机,最多为 --count 指定的虚拟机数量,必须小于或等于名称模式允许的虚拟机数量。

    使用名称模式时,Compute Engine 会尝试通过检查根据先前请求创建的现有虚拟机的名称来避免名称冲突。此外,如果您使用全球级 DNS,则可能会出现名称冲突。为避免使用全球级 DNS 产生的名称冲突,请切换到可用区级 DNS。如果您无法切换到可用区级 DNS,请避免在不同区域中使用相同名称模式。

  • PREDEFINED_NAME_1PREDEFINED_NAME_2、...:待创建虚拟机的预定义名称列表。指定此值或 namePattern。如果使用此标志并指定 COUNT,则 COUNT 必须等于提供的名称数量。

  • COUNT:要创建的虚拟机数量。此值必须小于或等于 NAME_PATTERN 允许的虚拟机数量。或者,如果使用 perInstanceProperties,则无需指定 COUNT,但一旦使用,则必须等于提供的名称的数量。

  • MIN_COUNT:可选标志,用于指定要创建的虚拟机数下限。下表根据您设置此标志的方式介绍了请求的行为:

    设置 说明
    未设置 默认值为 COUNT,而且,如果 Compute Engine 无法创建 COUNT 虚拟机,它会回滚请求。
    设置为 1 Compute Engine 会创建尽可能多的虚拟机,最多 COUNT 个。
    大于 1 且小于 COUNT Compute Engine 会尝试创建至少 MIN_COUNT 个虚拟机(最多不超过 COUNT 个虚拟机)。如果 Compute Engine 至少创建了 MIN_COUNT 个虚拟机,则请求将成功。

检查使用批量实例 API 创建的虚拟机的状态

使用批量实例 API 创建多个虚拟机后,请按照以下步骤检查对批量实例 API 的请求的状态,或检查属于对批量实例 API 的请求的单个虚拟机的状态。

检查批量实例请求的状态

检查对批量实例 API 的请求的状态时,只有在 Compute Engine 成功创建最小数量的指定虚拟机或者回滚该请求后,批量操作才会返回 DONE

如需了解如何检查对批量实例 API 请求的状态,请参阅处理 API 响应

检查单个虚拟机的状态

批量实例 API 为每个虚拟机创建 Operations,其中包含虚拟机名称和创建状态。

以下过程介绍了如何根据发送到批量实例 API 的请求,检查 Compute Engine 作为一组虚拟机的一部分创建的单个虚拟机的状态。

gcloud

  1. 从对批量实例 API 的请求返回的 Operation 中获取 operationGroupId 属性的值。

  2. 使用 operationGroupId 属性作为过滤条件执行 gcloud compute operations list 命令,以搜索与区域或可用区请求关联的虚拟机项目的所有操作和所有可用区批量实例 API:

    gcloud compute operations list \
      --filter=(operationGroupId=OPERATION_GROUP_ID)
    
  3. 执行以下任一操作,以获取虚拟机的其余属性:

    • 在操作列表中,targetLink 表示虚拟机的路径。使用 gcloud compute instances describe 方法(以该路径作为虚拟机的名称)来获取虚拟机的完整属性:

      gcloud compute instances describe VM_NAME
      
    • gcloud compute instances list 方法与包含操作列表中虚拟机名称的过滤条件结合使用:

      gcloud compute instances list VM_NAME \
        --filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      
    • 使用 gcloud compute instances list 命令获取所有可用区和区域中的虚拟机属性,并按实例独有的标签进行过滤,或者他们的姓名:

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

API

  1. 从对批量实例 API 的请求返回的 Operation 中获取 operationGroupId 属性的值。

  2. 使用 operationGroupId 属性作为过滤条件,以获取与批量实例 API 的区域级或可用区级请求关联的虚拟机操作列表:

    • 如果您向批量实例 API 发送区域请求,请使用 globalOperations.aggregatedList 方法搜索项目中的所有操作和所有可用区:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/aggregated/operations?filter=(operationGroupId=OPERATION_GROUP_ID)
      
    • 如果您向批量实例 API 发送可用区请求,请使用 zoneOperations.get 方法列出该可用区中的操作:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/bulkInsert?filter=(operationGroupId=OPERATION_GROUP_ID)
      
  3. 执行以下任一操作,以获取虚拟机的其余属性:

    • 在操作列表中,targetLink 表示虚拟机的路径。使用 instances.get 方法(以该路径作为虚拟机的名称)来获取虚拟机的完整属性:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME
      
    • instances.get 方法与包含操作列表中虚拟机名称的过滤条件结合使用:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances?filter=(name=VM_NAME_1) OR (name=VM_NAME_2)
      
    • 使用 instances.aggregatedList 方法可从所有可用区和区域获取虚拟机属性,并按实例独有的标签进行过滤,或者他们的姓名:

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

伪代码示例

以下伪代码示例显示了如何自定义对批量实例 API 的请求。

在同一区域内的不同可用区创建多个虚拟机

默认情况下,当您使用批量实例 API 创建多个虚拟机时,Compute Engine 会将这些虚拟机放在同一个可用区。以下过程描述了伪代码,说明如何创建最多 1000 个可在同一区域内的不同可用区的虚拟机。

  1. 指定要创建的虚拟机数量,然后初始化计数器以跟踪所创建的虚拟机数量。

    nTarget = 1000
    nCreated = 0
    
  2. 使用区域内的可用可用区初始化数据结构。使用 zones.list 方法获取您的项目可用的可用区列表。

    zones = list of zones in region
    
  3. 迭代可用区列表。在每次迭代时,调用 minCount 等于 1 的批量 API,并更新已创建的虚拟机总数的计数。minCount 等于 1 时,Compute Engine 会创建尽可能多的虚拟机,最多 nTarget 个。

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

在任意区域的一个可用区创建多个虚拟机

以下伪代码介绍了如何使用批量实例 API 在指定区域内的可用区中创建最多 1000 个虚拟机。尝试在一组指定区域的一个区域中创建多个虚拟机时,请求会先检查容量。如果容量不足,则请求会立即失败,并会再次尝试提供该组区域中的下一个区域。

  1. 指定要在可用区内创建的虚拟机数量。

    nTarget = 1000
    
  2. 指定要在其中创建虚拟机的区域。

    acceptableRegions = ["us-central1", "us-east1", "us-west1"]
    
  3. 迭代这些区域,并尝试在每个区域中创建虚拟机,直到成功。

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

在机器类型的可用区中创建多个虚拟机

以下伪代码介绍了如何使用批量实例 API 在一个指定的机器类型的可用区中创建多个虚拟机。在尝试创建同一机器类型的所有多个虚拟机时,请求会先检查这些机器类型的可用性。如果没有足够的可用机器类型,则请求将立即失败,然后尝试使用下一个机器类型。

  1. 指定要创建的虚拟机数量以及创建它们的区域。

    nTarget = 1000
    region = "us-central1"
    
  2. 指定要在其上创建虚拟机的机器系列。

    acceptableMachineFamilies = ["n2","c2","e2","n1"]
    
  3. 迭代该组机器类型,并尝试在机器类型上创建虚拟机,直到成功为止。

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

在一个可用区中创建超过 1000 个虚拟机

使用批量实例 API 创建虚拟机时,每个请求只能创建 1000 个虚拟机。以下伪代码介绍了如何通过发出多个请求在一个可用区中创建超过 1000 个虚拟机。

  1. 指定要创建的虚拟机的数量,用于跟踪已创建的虚拟机总数的计数器、要在其中创建虚拟机的区域以及用于存储 Compute Engine 在其中创建虚拟机的区域的变量。

    nTarget = 10000
    nCreated = 0
    region = "us-central1"
    targetZone = ""
    
  2. 发出创建 1000 个虚拟机的初始请求,保存请求返回的可用区,并更新所创建虚拟机数量的计数器。

    call bulk API: region=region, count=1000
    targetZone = zone chosen by bulk API
    nCreated += # of VMs created
    
  3. 继续发出一个可用区内最多创建 1000 个虚拟机的请求,直到 Compute Engine 创建指定的虚拟机数量。

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

查看有关多个虚拟机的详细信息

以下过程介绍了伪代码,您可以利用它们来获取通过批量实例 API 使用预定义名称创建的实例的详细信息:

  1. 指定要创建的虚拟机数量、要在其中创建虚拟机的可用区,以及用于存储名称的数据结构。

    nTarget = 1000
    targetZone = "us-central-1a"
    names = []
    
  2. 为虚拟机生成带模式的名称,并将名称添加到数据结构。

    for n in range(0,1000):
      names.push("instance-%d".format(n))
    
  3. 创建虚拟机,并使用 perInstanceProperties 指定名称。

    call bulk API(zone=targetZone, count=nTarget, names=perInstanceProperties)
    
  4. 使用 instances.list 方法和用于返回其详细信息的虚拟机名称的过滤条件来获取虚拟机的详细信息。

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

限制

在使用实例批量 API 之前,请先参阅以下限制列表:

  • 对于每个项目,使用批量实例 API 的并发运行操作数上限为 10。

  • 对于每个请求,您可以创建的虚拟机的数量限额为 1000。如需查看如何发出多个请求以创建 1000 个以上虚拟机的请求示例,请参阅本文档中的伪代码。

  • 所有虚拟机属性(名称除外)都必须相同。

  • 您不能使用虚拟机之间互斥的任何虚拟机属性,这些属性包括但不限于:

    • 自定义主机名
    • 静态外部 IP 地址
    • 静态内部 IP 地址
  • 您无法使用实例批量 API 创建使用以下各项的虚拟机:

    • 受客户管理的加密密钥 (CMEK) 保护的磁盘
    • 受客户提供的加密密钥 (CSEK) 保护的磁盘
    • 机器映像
    • 单租户节点亲和性标签
  • 如果您使用的是全局 DNS,则可能会出现名称冲突,因为可用区未包含在完全限定域名 (FQDN) 中。为了避免出现这种情况,请使用可用区级 DNS。如果您无法切换到可用区级 DNS,请避免在不同区域中使用相同名称模式。

  • 在极少数情况下,当 Compute Engine 验证对实例批量 API 的请求后,如果 Compute Engine 因另一个请求占用可用的配额而无法创建虚拟机,该请求可能会失败。在这种情况下,Compute Engine 会回滚该请求并删除其已创建的所有虚拟机。


审核日志

Compute Engine 会在发出请求时和请求结束时,将有关批量实例 API 的信息记录到管理员活动审核日志中。

Compute Engine 还会为每个虚拟机创建单独的审核日志。您可以通过将 protoPayload.resourceName 的值与命名模式生成的虚拟机名称进行匹配,查找单个虚拟机的审核日志。


后续步骤