- HTTP request
- Path parameters
- Request body
- Response body
- Authorization scopes
- IAM Permissions
- Try it!
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
|
Project ID for this request. |
region
|
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 } } |
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:
-
https://www.googleapis.com/compute/v1/projects/ project /zones/ zone -
projects/ project /zones/ zone -
zones/ zone
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[]
|
Initially the API will provide one recommendation which balances the individual scores according to the service provider's preference. |
recommendations[].scores
|
Scores for the recommendation. |
recommendations[].scores.obtainability
|
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
|
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 ' |
recommendations[].shards[]
|
Shards represent blocks of uniform capacity in recommendations. |
recommendations[].shards[].zone
|
Output only. The zone name for this shard. |
recommendations[].shards[].machineType
|
The machine type corresponds to the instance selection in the request. |
recommendations[].shards[].instanceCount
|
The number of instances. |
recommendations[].shards[].provisioningModel
|
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 .
