Method: advice.capacity

Advice on making real-time decisions (such as choosing zone or machine types) during deployment to maximize your chances of obtaining capacity.

HTTP request

POST https://compute.googleapis.com/compute/beta/projects/{project}/regions/{region}/advice/capacity

The URL uses gRPC Transcoding syntax. To know more about valid error responses that can be thrown by this HTTP request, please refer to the service error catalog

Path parameters

Parameters
project

string

Project ID for this request.
region

string

Name of the region for this request.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "instanceProperties": {
    "scheduling": {
      "provisioningModel": enum
    }
  },
  "instanceFlexibilityPolicy": {
    "instanceSelections": {
      string: {
        "machineTypes": [
          string
        ],
        "guestAccelerators": [
          {
            "acceleratorType": string,
            "acceleratorCount": integer
          }
        ],
        "disks": [
          {
            "type": enum
          }
        ]
      },
      ...
    }
  },
  "size": integer,
  "distributionPolicy": {
    "zones": [
      {
        "zone": string
      }
    ],
    "targetShape": enum
  }
}
Fields
instanceProperties

object

Instance properties for this request.
instanceProperties.scheduling

object

Specifies the scheduling options.
instanceProperties.scheduling.provisioningModel

enum

Specifies the provisioning model.
instanceFlexibilityPolicy.instanceSelections[].key

string
instanceFlexibilityPolicy.instanceSelections[].value.machineTypes[]

string

Full machine-type names, e.g. "n1-standard-16".
instanceFlexibilityPolicy.instanceSelections[].value.guestAccelerators[].acceleratorType

string

Full or partial URL of the accelerator type resource to attach to this instance. For example: projects/my-project/zones/us-central1-c/acceleratorTypes/nvidia-tesla-p100 If you are creating an instance template, specify only the accelerator name. See GPUs on Compute Engine for a full list of accelerator types.
instanceFlexibilityPolicy.instanceSelections[].value.guestAccelerators[].acceleratorCount

integer

The number of the guest accelerator cards exposed to this instance.
instanceFlexibilityPolicy.instanceSelections[].value.disks[]

object

Local SSDs.
instanceFlexibilityPolicy.instanceSelections[].value.disks[].type

enum

Specifies the type of the disk. This field must be set to SCRATCH.
size

integer

The number of VM instances to request.
distributionPolicy

object

Policy specifying the distribution of instances across zones within the requested region.
distributionPolicy.zones[]

object

Zones where advice.capacity Advisor looks for capacity.
distributionPolicy.zones[].zone

string

The URL of the zone. It can be a partial or full URL. For example, the following are valid values:

distributionPolicy.targetShape

enum

Target distribution shape. You can specify the following values: ANY, ANY_SINGLE_ZONE, or BALANCED.

Response body

A response contains scoring recommendations.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "recommendations": [
    {
      "scores": {
        "obtainability": number,
        "estimatedUptime": string
      },
      "shards": [
        {
          "zone": string,
          "machineType": string,
          "instanceCount": integer,
          "provisioningModel": enum
        }
      ]
    }
  ]
}
Fields
recommendations[]

object

Initially the API will provide one recommendation which balances the individual scores according to the service provider's preference.
recommendations[].scores

object

Scores for the recommendation.
recommendations[].scores.obtainability

number

The obtainability score indicates the likelihood of successfully obtaining (provisioning) the requested number of VMs. The score range is 0.0 through 1.0. Higher is better.
recommendations[].scores.estimatedUptime

string (Duration format)

The estimated run time of the majority of Spot VMs in the request before preemption. The estimate is best-effort only. It is based on historical data and current conditions.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
recommendations[].shards[]

object

Shards represent blocks of uniform capacity in recommendations.
recommendations[].shards[].zone

string

Output only. The zone name for this shard.
recommendations[].shards[].machineType

string

The machine type corresponds to the instance selection in the request.
recommendations[].shards[].instanceCount

integer

The number of instances.
recommendations[].shards[].provisioningModel

enum

The provisioning model that you want to view recommendations for.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/compute
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

In addition to any permissions specified on the fields above, authorization requires one or more of the following IAM permissions:

  • compute.advice.capacity

To find predefined roles that contain those permissions, see Compute Engine IAM Roles.