Consumir reservas

Neste documento, explicamos como consumir reservas no Compute Engine. Para saber como consumir reservas em outros produtos do Google Cloud , consulte a seguinte documentação:

Depois que você cria uma reserva ou o Compute Engine cria automaticamente uma reserva para atender a uma reserva adiantada, o Compute Engine retém os recursos reservados para você. Em seguida, use esses recursos reservados para criar instâncias do Compute Engine que correspondam às propriedades da reserva. Essa ação é conhecida como consumir uma reserva. Você pode usar a capacidade reservada para criar instâncias até que a reserva seja totalmente consumida.

Limitações

Não é possível consumir uma reserva para criar os seguintes recursos do Compute Engine:

  • VMs de início flexível

  • VMs spot ou instâncias preemptivas

  • Nós de locatário individual

Antes de começar

Funções exigidas

Para receber as permissões necessárias para consumir reservas, peça ao administrador que conceda a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para consumir reservas. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para consumir reservas:

  • Para criar reservas: compute.reservations.create no projeto
  • Para criar instâncias:
    • compute.instances.create no projeto
    • Usar uma imagem personalizada para criar a VM: compute.images.useReadOnly na imagem
    • Utilizar um snapshot para criar a VM: compute.snapshots.useReadOnly no snapshot
    • Usar um modelo de instância para criar a VM: compute.instanceTemplates.useReadOnly no modelo de instância
    • Atribuir uma rede legada à VM: compute.networks.use no projeto
    • Especificar um endereço IP estático para a VM: compute.addresses.use no projeto
    • Atribuir um endereço IP externo à VM ao usar uma rede legada: compute.networks.useExternalIp no projeto
    • Especificar uma sub-rede para a VM: compute.subnetworks.use no projeto ou na sub-rede escolhida
    • Atribuir um endereço IP externo à VM ao usar uma rede VPC: compute.subnetworks.useExternalIp no projeto ou na sub-rede escolhida
    • Definir os metadados da instância da VM: compute.instances.setMetadata no projeto
    • Definir tags para a VM: compute.instances.setTags na VM
    • Definir rótulos para a VM: compute.instances.setLabels na VM
    • Definir uma conta de serviço para a VM usar: compute.instances.setServiceAccount na VM
    • Criar um disco para a VM: compute.disks.create no projeto
    • Anexar um disco atual no modo somente leitura ou de leitura e gravação: compute.disks.use no disco
    • Anexar um disco atual no modo somente leitura: compute.disks.useReadOnly no disco
  • Para criar modelos de instância: compute.instanceTemplates.create no projeto

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Efetivar uma reserva

Os exemplos nas seções a seguir mostram como consumir uma reserva criando uma única instância de computação. Também é possível consumir reservas criando instâncias que correspondam às propriedades das reservas usando uma opção de implantação diferente ou atualizando as propriedades das instâncias atuais para corresponder às reservas consumidas automaticamente.

Para consumir uma reserva, use um dos seguintes métodos:

Efetivar uma reserva consumida automaticamente

As reservas consumidas automaticamente permitem que qualquer instância de computação que corresponda às propriedades da reserva a consuma automaticamente. Esse comportamento de consumo se aplica a instâncias novas e em execução. Quando você cria reservas ou o Compute Engine cria automaticamente uma reserva para atender a uma reserva adiantada, esse tipo de reserva é a configuração padrão.

Se as propriedades de uma reserva automática de projeto único e uma reserva automática compartilhada forem iguais, as instâncias no seu projeto vão consumir primeiro a reserva de projeto único e depois a reserva compartilhada. Para mais informações, consulte a ordem de consumo de reservas.

Para criar e consumir uma reserva automática de exemplo, selecione uma das seguintes opções:

Console

O exemplo a seguir mostra como criar uma reserva automática na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma mínima de CPU. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva automática, faça o seguinte:

  1. Para criar um exemplo de reserva, siga estas etapas:

    1. No console do Google Cloud , acesse a página Reservas.

      Acessar "Reservas"

      As etapas restantes aparecem automaticamente no console doGoogle Cloud .

    2. Na guia Reserva imediata (padrão), clique em Criar reserva. A página Criar uma reserva é exibida.

    3. No campo Nome, insira um nome para a reserva. Por exemplo, digite reservation-01.

    4. Selecione a Região e a Zona em que você quer reservar recursos. Por exemplo, selecione us-central1 e us-central1-a, respectivamente.

    5. Na seção Tipo de compartilhamento, faça o seguinte:

      • Para criar uma reserva de projeto único, selecione Local.

      • Para criar uma reserva compartilhada, selecione Compartilhada e especifique os projetos com que você quer compartilhar a reserva.

    6. Na seção Usar com instância de VM, selecione Usar reserva automaticamente, se ainda não estiver selecionado.

    7. No campo Número de instâncias de VM, digite 3.

    8. Na guia Uso geral, selecione N2.

    9. Na seção Tipo de máquina, na guia Predefinido (padrão), selecione n2-standard-32.

    10. Expanda Plataforma de CPU e GPU e, no campo Plataforma de CPU, selecione Intel Cascade Lake ou mais recente.

    11. Clique em Criar.

  2. Para criar uma instância que consuma o exemplo de reserva, siga estas etapas:

    1. No console do Google Cloud , acesse a página Criar uma instância.

      Acesse "Criar uma instância"

      A página Criar uma instância aparece e mostra o painel Configuração da máquina.

    2. No painel "Configuração da máquina", faça o seguinte:

      1. No campo Nome, dê um nome para a instância. Neste exemplo, digite instance-01.

      2. Especifique a Região e a Zona em que os recursos serão reservados. Para este exemplo, selecione us-central1 e us-central1-a, respectivamente.

      3. Na guia Uso geral, selecione N2.

      4. Na seção Tipo de máquina, na guia Predefinido (padrão), selecione n2-standard-32.

      5. Abra a seção Opções avançadas e, no campo Plataforma de CPU, selecione Intel Cascade Lake ou mais recente.

    3. Opcional: o consumo automático de uma reserva correspondente é a configuração padrão. No entanto, se você quiser especificar essa configuração, faça o seguinte:

      1. No menu de navegação, clique em Avançado. O painel Avançado aparece.

      2. Na seção Reservas, selecione Usar seleção automática.

    4. Clique em Criar.

gcloud

O exemplo a seguir mostra como criar uma reserva automática na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma mínima de CPU. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva automática, faça o seguinte:

  1. Para criar a reserva de exemplo, use o comando gcloud compute reservations create:

    gcloud compute reservations create reservation-01 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --vm-count=3 \
    --zone=us-central1-a

  2. Para criar uma instância que consuma a reserva de exemplo, use o comando gcloud compute instances create com a flag --reservation-affinity definida como any. Como any é a configuração padrão, você também pode omitir essa flag.

    gcloud compute instances create instance-01 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --reservation-affinity=any \
    --zone=us-central1-a

Go

Para criar o exemplo de reserva automática usando um modelo de instância e criar uma instância para consumir a reserva usando o mesmo modelo, use o seguinte exemplo de código:

import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// consumeAnyReservation creates instance, consuming any available reservation
func consumeAnyReservation(w io.Writer, projectID, zone, instanceName, sourceTemplate string) error {
	// projectID := "your_project_id"
	// zone := "us-west3-a"
	// instanceName := "your_instance_name"
	// sourceTemplate: existing template path. Following formats are allowed:
	//  	- projects/{project_id}/global/instanceTemplates/{template_name}
	//  	- projects/{project_id}/regions/{region}/instanceTemplates/{template_name}
	//  	- https://www.googleapis.com/compute/v1/projects/{project_id}/global/instanceTemplates/instanceTemplate
	//  	- https://www.googleapis.com/compute/v1/projects/{project_id}/regions/{region}/instanceTemplates/instanceTemplate

	ctx := context.Background()

	instancesClient, err := compute.NewInstancesRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewInstancesRESTClient: %w", err)
	}
	defer instancesClient.Close()

	req := &computepb.InsertInstanceRequest{
		Project:                projectID,
		Zone:                   zone,
		SourceInstanceTemplate: proto.String(sourceTemplate),
		InstanceResource: &computepb.Instance{
			Name: proto.String(instanceName),
			// specifies that any matching reservation should be consumed
			ReservationAffinity: &computepb.ReservationAffinity{
				ConsumeReservationType: proto.String("ANY_RESERVATION"),
			},
		},
	}

	op, err := instancesClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create instance: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}
	fmt.Fprintf(w, "Instance created from reservation\n")

	return nil
}

Java

O exemplo a seguir mostra como criar uma instância N1 com quatro vCPUs e Intel Skylake como a plataforma de CPU mínima na zona us-central1-a. A instância consome automaticamente uma reserva correspondente.

Para criar a instância de exemplo, use o seguinte exemplo de código:

import static com.google.cloud.compute.v1.ReservationAffinity.ConsumeReservationType.ANY_RESERVATION;

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.compute.v1.AttachedDisk;
import com.google.cloud.compute.v1.AttachedDiskInitializeParams;
import com.google.cloud.compute.v1.InsertInstanceRequest;
import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.InstancesClient;
import com.google.cloud.compute.v1.NetworkInterface;
import com.google.cloud.compute.v1.Operation;
import com.google.cloud.compute.v1.ReservationAffinity;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ConsumeAnyMatchingReservation {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Zone where the VM instance will be created.
    String zone = "us-central1-a";
    // Name of the VM instance you want to query.
    String instanceName = "YOUR_INSTANCE_NAME";
    // machineType: machine type of the VM being created.
    // *   For a list of machine types, see https://cloud.google.com/compute/docs/machine-types
    String machineTypeName = "n1-standard-4";
    // sourceImage: path to the operating system image to mount.
    // *   For details about images you can mount, see https://cloud.google.com/compute/docs/images
    String sourceImage = "projects/debian-cloud/global/images/family/debian-11";
    // diskSizeGb: storage size of the boot disk to attach to the instance.
    long diskSizeGb = 10L;
    // networkName: network interface to associate with the instance.
    String networkName = "default";
    // Minimum CPU platform of the instances.
    String minCpuPlatform = "Intel Skylake";

    createInstanceAsync(projectId, zone, instanceName, machineTypeName, sourceImage,
        diskSizeGb, networkName, minCpuPlatform);
  }

  // Create a virtual machine targeted with the reserveAffinity field.
  // In this consumption model, existing and new VMs automatically consume a reservation
  // if their properties match the VM properties specified in the reservation.
  public static Instance createInstanceAsync(String projectId, String zone,
      String instanceName, String machineTypeName, String sourceImage,
      long diskSizeGb, String networkName, String minCpuPlatform)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    String machineType = String.format("zones/%s/machineTypes/%s", zone, machineTypeName);
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (InstancesClient instancesClient = InstancesClient.create()) {
      AttachedDisk disk =
          AttachedDisk.newBuilder()
              .setBoot(true)
              .setAutoDelete(true)
              .setType(AttachedDisk.Type.PERSISTENT.toString())
              .setDeviceName("disk-1")
              .setInitializeParams(
                  AttachedDiskInitializeParams.newBuilder()
                      .setSourceImage(sourceImage)
                      .setDiskSizeGb(diskSizeGb)
                      .build())
              .build();

      NetworkInterface networkInterface = NetworkInterface.newBuilder()
          .setName(networkName)
          .build();

      ReservationAffinity reservationAffinity =
          ReservationAffinity.newBuilder()
              .setConsumeReservationType(ANY_RESERVATION.toString())
              .build();

      Instance instanceResource =
          Instance.newBuilder()
              .setName(instanceName)
              .setMachineType(machineType)
              .addDisks(disk)
              .addNetworkInterfaces(networkInterface)
              .setMinCpuPlatform(minCpuPlatform)
              .setReservationAffinity(reservationAffinity)
              .build();

      InsertInstanceRequest insertInstanceRequest = InsertInstanceRequest.newBuilder()
          .setProject(projectId)
          .setZone(zone)
          .setInstanceResource(instanceResource)
          .build();

      OperationFuture<Operation, Operation> operation = instancesClient.insertAsync(
          insertInstanceRequest);

      Operation response = operation.get(3, TimeUnit.MINUTES);

      if (response.hasError()) {
        return null;
      }
      return instancesClient.get(projectId, zone, instanceName);
    }
  }
}

Node.js

O exemplo a seguir mostra como criar uma instância N1 com quatro vCPUs e Intel Skylake como a plataforma de CPU mínima na zona us-central1-a. A instância consome automaticamente uma reserva correspondente.

Para criar a instância de exemplo, use o seguinte exemplo de código:

// Import the Compute library
const computeLib = require('@google-cloud/compute');
const compute = computeLib.protos.google.cloud.compute.v1;

// Instantiate a reservationsClient
const instancesClient = new computeLib.InstancesClient();
// Instantiate a zoneOperationsClient
const zoneOperationsClient = new computeLib.ZoneOperationsClient();

/**
 * TODO(developer): Update/uncomment these variables before running the sample.
 */
// The ID of the project where you want to create instance.
const projectId = await instancesClient.getProjectId();
// The zone in which to create instance.
const zone = 'us-central1-a';
// The name of the instance to create.
// const instanceName = 'instance-01';
// Machine type to use for VM.
const machineType = 'n1-standard-4';

// Create instance to consume reservation if their properties match the VM properties
async function callCreateInstanceToConsumeAnyReservation() {
  // Describe the size and source image of the boot disk to attach to the instance.
  const disk = new compute.Disk({
    boot: true,
    autoDelete: true,
    type: 'PERSISTENT',
    initializeParams: {
      diskSizeGb: '10',
      sourceImage: 'projects/debian-cloud/global/images/family/debian-12',
    },
  });

  //  Define networkInterface
  const networkInterface = new compute.NetworkInterface({
    name: 'global/networks/default',
  });

  // Define reservationAffinity
  const reservationAffinity = new compute.ReservationAffinity({
    consumeReservationType: 'ANY_RESERVATION',
  });

  // Create an instance
  const instance = new compute.Instance({
    name: instanceName,
    machineType: `zones/${zone}/machineTypes/${machineType}`,
    minCpuPlatform: 'Intel Skylake',
    disks: [disk],
    networkInterfaces: [networkInterface],
    reservationAffinity,
  });

  const [response] = await instancesClient.insert({
    project: projectId,
    instanceResource: instance,
    zone,
  });

  let operation = response.latestResponse;

  // Wait for the create instance operation to complete.
  while (operation.status !== 'DONE') {
    [operation] = await zoneOperationsClient.wait({
      operation: operation.name,
      project: projectId,
      zone: operation.zone.split('/').pop(),
    });
  }

  console.log(`Instance ${instanceName} created.`);
}

await callCreateInstanceToConsumeAnyReservation();

Python

O exemplo a seguir mostra como criar uma reserva automática na zona us-central1-a para três instâncias N1 com uma vCPU e Intel Ivy como a plataforma de CPU mínima. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva automática, faça o seguinte:

from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def consume_any_project_reservation(
    project_id: str,
    zone: str,
    reservation_name: str,
    instance_name: str,
    machine_type: str = "n1-standard-1",
    min_cpu_platform: str = "Intel Ivy Bridge",
) -> compute_v1.Instance:
    """
    Creates a specific reservation in a single project and launches a VM
    that consumes the newly created reservation.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone to create the reservation.
        reservation_name (str): The name of the reservation to create.
        instance_name (str): The name of the instance to create.
        machine_type (str): The machine type for the instance.
        min_cpu_platform (str): The minimum CPU platform for the instance.
    """
    instance_properties = (
        compute_v1.AllocationSpecificSKUAllocationReservedInstanceProperties(
            machine_type=machine_type,
            min_cpu_platform=min_cpu_platform,
        )
    )

    reservation = compute_v1.Reservation(
        name=reservation_name,
        specific_reservation=compute_v1.AllocationSpecificSKUReservation(
            count=3,
            instance_properties=instance_properties,
        ),
    )

    # Create a reservation client
    client = compute_v1.ReservationsClient()
    operation = client.insert(
        project=project_id,
        zone=zone,
        reservation_resource=reservation,
    )
    wait_for_extended_operation(operation, "Reservation creation")

    instance = compute_v1.Instance()
    instance.name = instance_name
    instance.machine_type = f"zones/{zone}/machineTypes/{machine_type}"
    instance.min_cpu_platform = min_cpu_platform
    instance.zone = zone

    # Set the reservation affinity to target any matching reservation
    instance.reservation_affinity = compute_v1.ReservationAffinity(
        consume_reservation_type="ANY_RESERVATION",  # Type of reservation to consume
    )
    # Define the disks for the instance
    instance.disks = [
        compute_v1.AttachedDisk(
            boot=True,  # Indicates that this is a boot disk
            auto_delete=True,  # The disk will be deleted when the instance is deleted
            initialize_params=compute_v1.AttachedDiskInitializeParams(
                source_image="projects/debian-cloud/global/images/family/debian-11",
                disk_size_gb=10,
            ),
        )
    ]
    instance.network_interfaces = [
        compute_v1.NetworkInterface(
            network="global/networks/default",  # The network to use
            access_configs=[
                compute_v1.AccessConfig(
                    name="External NAT",  # Name of the access configuration
                    type="ONE_TO_ONE_NAT",  # Type of access configuration
                )
            ],
        )
    ]
    # Create a request to insert the instance
    request = compute_v1.InsertInstanceRequest()
    request.zone = zone
    request.project = project_id
    request.instance_resource = instance

    vm_client = compute_v1.InstancesClient()
    operation = vm_client.insert(request)
    wait_for_extended_operation(operation, "instance creation")
    print(f"Instance {instance_name} that targets any open reservation created.")

    return vm_client.get(project=project_id, zone=zone, instance=instance_name)

REST

O exemplo a seguir mostra como criar uma reserva automática na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma mínima de CPU. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva automática, faça o seguinte:

  1. Para criar a reserva de exemplo, faça uma solicitação POST para o método reservations.insert:

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations

{
  "name": "reservation-01",
  "specificReservation": {
    "count": "3",
    "instanceProperties": {
      "machineType": "n2-standard-32",
      "minCpuPlatform": "Intel Cascade Lake",
    }
  }
}

  2. Para criar uma instância que consuma a reserva de exemplo, faça uma solicitação POST para o método instances.insert. No corpo da solicitação, inclua o campo consumeReservationType definido como ANY_RESERVATION. No entanto, como ANY_RESERVATION é a configuração padrão, também é possível omitir o campo.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances

{
  "name": "instance-01",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "minCpuPlatform": "Intel Cascade Lake",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-12"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "ANY_RESERVATION"
  }
}

Consumir uma reserva com segmentação específica

As reservas com direcionamento específico permitem que novas instâncias de computação que correspondam às propriedades da reserva e a segmentem para consumo. As instâncias só serão criadas se as propriedades delas corresponderem às propriedades da reserva. Caso contrário, você vai encontrar erros.

Com base no método de criação que você quer usar, crie reservas específicas e instâncias que as segmentam da seguinte maneira:

Método de criação Ao criar uma reserva Ao criar instâncias para consumir a reserva
Console doGoogle Cloud Na seção Usar com instância de VM, selecione Selecionar reserva específica. No painel Avançado, na seção Reservas, selecione Escolher uma reserva. Em seguida, siga as instruções para selecionar uma reserva.
CLI do Google Cloud Inclua a flag --require-specific-reservation. Inclua as seguintes flags:
  • A flag --reservation-affinity definida como specific.
  • A flag --reservation definida como o caminho do recurso para a reserva, formatada como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.
Go Inclua o campo SpecificReservationRequired definido como true. No campo ReservationAffinity, inclua os seguintes campos:
  • O campo ConsumeReservationType definido como SPECIFIC_RESERVATION.
  • O campo Key definido como compute.googleapis.com/reservation-name.
  • O campo Values definido como o caminho do recurso para a reserva, formatado como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.
Java Inclua o campo setSpecificReservationRequired definido como true. No campo ReservationAffinity, inclua os seguintes campos:
  • O campo setConsumeReservationType definido como SPECIFIC_RESERVATION.
  • O campo setKey definido como compute.googleapis.com/reservation-name.
  • O campo addValues definido como o caminho do recurso para a reserva, formatado como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.
Node.js e API REST Inclua o campo specificReservationRequired definido como true. No campo reservationAffinity, inclua os seguintes campos:
  • O campo consumeReservationType definido como SPECIFIC_RESERVATION.
  • O campo key definido como compute.googleapis.com/reservation-name.
  • O campo values definido como uma lista que contém um único item com o caminho do recurso para a reserva, formatado como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.
Python Inclua o campo specific_reservation_required definido como true. No campo reservation_affinity, inclua os seguintes campos:
  • O campo consume_reservation_type definido como SPECIFIC_RESERVATION.
  • O campo key definido como compute.googleapis.com/reservation-name.
  • O campo values definido como o caminho do recurso para a reserva, formatado como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.
Terraform Inclua o campo specific_reservation_required definido como true. No campo reservation_affinity, inclua os seguintes campos:
  • O campo type definido como SPECIFIC_RESERVATION.
  • O campo specific_reservation, que inclui os seguintes campos:
    • O campo key definido como compute.googleapis.com/reservation-name.
    • O campo values definido como uma lista que contém um único item com o caminho do recurso para a reserva, formatado como projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME.

Para criar um exemplo de reserva específica e uma instância para consumi-la, selecione uma das seguintes opções:

Console

O exemplo a seguir mostra como criar uma reserva específica na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma de CPU mínima. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva específica, faça o seguinte:

  1. Para criar um exemplo de reserva, siga estas etapas:

    1. No console do Google Cloud , acesse a página Reservas.

      Acessar "Reservas"

      As etapas restantes aparecem automaticamente no console doGoogle Cloud .

    2. Na guia Reserva imediata (padrão), clique em Criar reserva. A página Criar uma reserva é exibida.

    3. No campo Nome, insira um nome para a reserva. Por exemplo, digite reservation-02.

    4. Especifique a Região e a Zona em que os recursos serão reservados. Para este exemplo, selecione us-central1 e us-central1-a, respectivamente.

    5. Na seção Tipo de compartilhamento, faça o seguinte:

      • Para criar uma reserva de projeto único, selecione Local.

      • Para criar uma reserva compartilhada, selecione Compartilhada e especifique os projetos com que você quer compartilhar a reserva.

    6. Na seção Usar com instância de VM, selecione Selecionar reserva específica.

    7. No campo Número de instâncias de VM, digite 3.

    8. Na guia Uso geral, selecione N2.

    9. Na seção Tipo de máquina, na guia Predefinido (padrão), selecione n2-standard-32.

    10. Expanda Plataforma de CPU e GPU e, no campo Plataforma de CPU, selecione Intel Cascade Lake ou mais recente.

    11. Clique em Criar.

  2. Para criar uma instância que consuma o exemplo de reserva, siga estas etapas:

    1. No console do Google Cloud , acesse a página Criar uma instância.

      Acesse "Criar uma instância"

      A página Criar uma instância aparece e mostra o painel Configuração da máquina.

    2. No painel "Configuração da máquina", faça o seguinte:

      1. No campo Nome, dê um nome para a instância. Neste exemplo, digite instance-02.

      2. Especifique a Região e a Zona em que os recursos serão reservados. Para este exemplo, selecione us-central1 e us-central1-a, respectivamente.

      3. Na guia Uso geral, selecione N2.

      4. Na seção Tipo de máquina, na guia Predefinido (padrão), selecione n2-standard-32.

      5. Abra a seção Opções avançadas e, no campo Plataforma de CPU, selecione Intel Cascade Lake ou mais recente.

    3. No menu de navegação, clique em Avançado. O painel Avançado vai aparecer.

    4. Na seção Reservas, selecione Escolher uma reserva e clique em Escolher reserva.

    5. No painel Escolher uma reserva, faça o seguinte:

      1. Selecione a reserva específica que você criou nas etapas anteriores. Se você quiser consumir uma reserva compartilhada que existe em um projeto diferente, na lista Projeto, selecione o projeto em que a reserva está.

      2. Clique em Escolher.

    6. Clique em Criar.

gcloud

O exemplo a seguir mostra como criar uma reserva específica na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma de CPU mínima. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva específica, faça o seguinte:

  1. Para criar a reserva de exemplo, use o comando gcloud compute reservations create com a flag --require-specific-reservation:

    gcloud compute reservations create reservation-02 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --require-specific-reservation \
    --vm-count=3 \
    --zone=us-central1-a

  2. Para criar uma instância que consuma a reserva de exemplo, use o comando gcloud compute instances create com as flags --reservation e --reservation-affinity=specific:

    gcloud compute instances create instance-02 \
    --machine-type=n2-standard-32 \
    --min-cpu-platform="Intel Cascade Lake" \
    --reservation-affinity=specific \
    --reservation=RESERVATION_URL \
    --zone=us-central1-a

    Substitua RESERVATION_URL pelo URL da reserva. Especifique um dos seguintes valores:

    • Se você criou a reserva no mesmo projeto: reservation-02

    • Se a reserva estiver em outro projeto: projects/PROJECT_ID/reservations/reservation-02

Go

Os exemplos a seguir mostram como criar uma instância N2 com 32 vCPUs e Intel Cascade Lake como a plataforma mínima de CPU na zona us-central1-a para consumir uma reserva específica correspondente:

  • Para criar a instância de exemplo e consumir uma reserva específica de projeto único, use o seguinte exemplo de código:

    import (
	"context"
	"fmt"
	"io"

	compute "cloud.google.com/go/compute/apiv1"
	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// consumeSpecificReservation creates instance, consuming specific reservation
// Note: respective reservation should have SpecificReservationRequired: true
func consumeSpecificReservation(w io.Writer, projectID, zone, instanceName, reservationName string) error {
	// projectID := "your_project_id"
	// zone := "us-west3-a"
	// reservationName := "your_reservation_name"
	// instanceName := "your_instance_name"

	ctx := context.Background()
	machineType := fmt.Sprintf("zones/%s/machineTypes/%s", zone, "n2-standard-32")
	sourceImage := "projects/debian-cloud/global/images/family/debian-12"

	instancesClient, err := compute.NewInstancesRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewInstancesRESTClient: %w", err)
	}
	defer instancesClient.Close()

	req := &computepb.InsertInstanceRequest{
		Project: projectID,
		Zone:    zone,
		InstanceResource: &computepb.Instance{
			Disks: []*computepb.AttachedDisk{
				{
					InitializeParams: &computepb.AttachedDiskInitializeParams{
						DiskSizeGb:  proto.Int64(10),
						SourceImage: proto.String(sourceImage),
					},
					AutoDelete: proto.Bool(true),
					Boot:       proto.Bool(true),
					Type:       proto.String(computepb.AttachedDisk_PERSISTENT.String()),
				},
			},
			MachineType:    proto.String(machineType),
			MinCpuPlatform: proto.String("Intel Cascade Lake"),
			Name:           proto.String(instanceName),
			NetworkInterfaces: []*computepb.NetworkInterface{
				{
					Name: proto.String("global/networks/default"),
				},
			},
			// specifies particular reservation, which should be consumed
			ReservationAffinity: &computepb.ReservationAffinity{
				ConsumeReservationType: proto.String("SPECIFIC_RESERVATION"),
				Key:                    proto.String("compute.googleapis.com/reservation-name"),
				Values:                 []string{reservationName},
			},
		},
	}

	op, err := instancesClient.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create instance: %w", err)
	}

	if err = op.Wait(ctx); err != nil {
		return fmt.Errorf("unable to wait for the operation: %w", err)
	}
	fmt.Fprintf(w, "Instance created from reservation\n")

	return nil
}

  • Para criar a instância de exemplo e consumir uma reserva compartilhada e específica, use o seguinte exemplo de código:

    import (
	"context"
	"fmt"
	"io"

	computepb "cloud.google.com/go/compute/apiv1/computepb"
	"google.golang.org/protobuf/proto"
)

// consumeSpecificSharedReservation consumes specific shared reservation in particular zone
func consumeSpecificSharedReservation(w io.Writer, client InstanceClientInterface, projectID, baseProjectId, zone, instanceName, reservationName string) error {
	// client, err := compute.NewInstancesRESTClient(ctx)
	// projectID := "your_project_id". Project where reservation is created.
	// baseProjectId := "shared_project_id". Project where instance will be consumed and created.
	// zone := "us-west3-a"
	// reservationName := "your_reservation_name"
	// instanceName := "your_instance_name"

	ctx := context.Background()
	machineType := fmt.Sprintf("zones/%s/machineTypes/%s", zone, "n2-standard-32")
	sourceImage := "projects/debian-cloud/global/images/family/debian-12"
	sharedReservation := fmt.Sprintf("projects/%s/reservations/%s", baseProjectId, reservationName)

	req := &computepb.InsertInstanceRequest{
		Project: projectID,
		Zone:    zone,
		InstanceResource: &computepb.Instance{
			Disks: []*computepb.AttachedDisk{
				{
					InitializeParams: &computepb.AttachedDiskInitializeParams{
						DiskSizeGb:  proto.Int64(10),
						SourceImage: proto.String(sourceImage),
					},
					AutoDelete: proto.Bool(true),
					Boot:       proto.Bool(true),
					Type:       proto.String(computepb.AttachedDisk_PERSISTENT.String()),
				},
			},
			MachineType:    proto.String(machineType),
			MinCpuPlatform: proto.String("Intel Cascade Lake"),
			Name:           proto.String(instanceName),
			NetworkInterfaces: []*computepb.NetworkInterface{
				{
					Name: proto.String("global/networks/default"),
				},
			},
			// specifies particular reservation, which should be consumed
			ReservationAffinity: &computepb.ReservationAffinity{
				ConsumeReservationType: proto.String("SPECIFIC_RESERVATION"),
				Key:                    proto.String("compute.googleapis.com/reservation-name"),
				Values:                 []string{sharedReservation},
			},
		},
	}

	op, err := client.Insert(ctx, req)
	if err != nil {
		return fmt.Errorf("unable to create instance: %w", err)
	}

	if op != nil {
		if err = op.Wait(ctx); err != nil {
			return fmt.Errorf("unable to wait for the operation: %w", err)
		}
	}
	fmt.Fprintf(w, "Instance created from shared reservation\n")

	return nil
}

Java

Os exemplos a seguir mostram como criar uma instância N1 com quatro vCPUs e Intel Skylake como a plataforma de CPU mínima na zona us-central1-a para consumir uma reserva específica correspondente:

  • Para criar um exemplo de reserva como uma reserva de projeto único e criar uma instância para consumi-la, use o exemplo de código a seguir:

    import static com.google.cloud.compute.v1.ReservationAffinity.ConsumeReservationType.SPECIFIC_RESERVATION;

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.compute.v1.AttachedDisk;
import com.google.cloud.compute.v1.AttachedDiskInitializeParams;
import com.google.cloud.compute.v1.InsertInstanceRequest;
import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.InstancesClient;
import com.google.cloud.compute.v1.NetworkInterface;
import com.google.cloud.compute.v1.Operation;
import com.google.cloud.compute.v1.ReservationAffinity;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ConsumeSingleProjectReservation {
  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Name of the zone where the reservation is located.
    String zone = "us-central1-a";
    // Name of the reservation you want to query.
    String reservationName = "YOUR_RESERVATION_NAME";
    // Name of the VM instance you want to query.
    String instanceName = "YOUR_INSTANCE_NAME";
    // machineType: machine type of the VM being created.
    // *   For a list of machine types, see https://cloud.google.com/compute/docs/machine-types
    String machineTypeName = "n1-standard-4";
    // sourceImage: path to the operating system image to mount.
    // *   For details about images you can mount, see https://cloud.google.com/compute/docs/images
    String sourceImage = "projects/debian-cloud/global/images/family/debian-11";
    // diskSizeGb: storage size of the boot disk to attach to the instance.
    long diskSizeGb = 10L;
    // networkName: network interface to associate with the instance.
    String networkName = "default";
    // Minimum CPU platform of the instances.
    String minCpuPlatform = "Intel Skylake";

    createInstanceAsync(projectId, zone, instanceName, reservationName, machineTypeName,
        sourceImage, diskSizeGb, networkName, minCpuPlatform);
  }

  // Create a virtual machine targeted with the reserveAffinity field.
  // Ensure that the VM's properties match the reservation's VM properties.
  public static Instance createInstanceAsync(String projectId, String zone, String instanceName,
      String reservationName, String machineTypeName, String sourceImage, long diskSizeGb,
      String networkName, String minCpuPlatform)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    String machineType = String.format("zones/%s/machineTypes/%s", zone, machineTypeName);
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (InstancesClient instancesClient = InstancesClient.create()) {
      AttachedDisk disk =
          AttachedDisk.newBuilder()
              .setBoot(true)
              .setAutoDelete(true)
              .setType(AttachedDisk.Type.PERSISTENT.toString())
              .setDeviceName("disk-1")
              .setInitializeParams(
                  AttachedDiskInitializeParams.newBuilder()
                      .setSourceImage(sourceImage)
                      .setDiskSizeGb(diskSizeGb)
                      .build())
              .build();

      NetworkInterface networkInterface = NetworkInterface.newBuilder()
          .setName(networkName)
          .build();

      ReservationAffinity reservationAffinity =
          ReservationAffinity.newBuilder()
              .setConsumeReservationType(SPECIFIC_RESERVATION.toString())
              .setKey("compute.googleapis.com/reservation-name")
              // Set specific reservation
              .addValues(reservationName)
              .build();

      Instance instanceResource =
          Instance.newBuilder()
              .setName(instanceName)
              .setMachineType(machineType)
              .addDisks(disk)
              .addNetworkInterfaces(networkInterface)
              .setMinCpuPlatform(minCpuPlatform)
              .setReservationAffinity(reservationAffinity)
              .build();

      InsertInstanceRequest insertInstanceRequest = InsertInstanceRequest.newBuilder()
          .setProject(projectId)
          .setZone(zone)
          .setInstanceResource(instanceResource)
          .build();

      OperationFuture<Operation, Operation> operation = instancesClient.insertAsync(
          insertInstanceRequest);
      Operation response = operation.get(3, TimeUnit.MINUTES);

      if (response.hasError()) {
        return null;
      }
      return instancesClient.get(projectId, zone, instanceName);
    }
  }
}

  • Para criar um exemplo de reserva como uma reserva compartilhada e criar uma instância para consumi-la, use o seguinte exemplo de código:

    import static com.google.cloud.compute.v1.ReservationAffinity.ConsumeReservationType.SPECIFIC_RESERVATION;

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.compute.v1.AttachedDisk;
import com.google.cloud.compute.v1.AttachedDiskInitializeParams;
import com.google.cloud.compute.v1.InsertInstanceRequest;
import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.InstancesClient;
import com.google.cloud.compute.v1.NetworkInterface;
import com.google.cloud.compute.v1.Operation;
import com.google.cloud.compute.v1.ReservationAffinity;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ConsumeSpecificSharedReservation {
  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "YOUR_PROJECT_ID";
    // Name of the zone the reservation is located.
    String zone = "us-central1-a";
    // Name of the reservation you want to query.
    String reservationName = "YOUR_RESERVATION_NAME";
    // Name of the VM instance you want to query.
    String instanceName = "YOUR_INSTANCE_NAME";
    // machineType: machine type of the VM being created.
    // *   For a list of machine types, see https://cloud.google.com/compute/docs/machine-types
    String machineTypeName = "n1-standard-4";
    // sourceImage: path to the operating system image to mount.
    // *   For details about images you can mount, see https://cloud.google.com/compute/docs/images
    String sourceImage = "projects/debian-cloud/global/images/family/debian-11";
    // diskSizeGb: storage size of the boot disk to attach to the instance.
    long diskSizeGb = 10L;
    // networkName: network interface to associate with the instance.
    String networkName = "default";
    // Minimum CPU platform of the instances.
    String minCpuPlatform = "Intel Skylake";

    createInstanceAsync(projectId, zone, instanceName, reservationName, machineTypeName,
        sourceImage, diskSizeGb, networkName, minCpuPlatform);
  }

  // Create a virtual machine targeted with the reserveAffinity field.
  // Ensure that the VM's properties match the reservation's VM properties.
  public static Instance createInstanceAsync(String projectId, String zone, String instanceName,
      String reservationName, String machineTypeName, String sourceImage, long diskSizeGb,
      String networkName, String minCpuPlatform)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    String machineType = String.format("zones/%s/machineTypes/%s", zone, machineTypeName);
    // To consume this reservation from any consumer projects that this reservation is shared with,
    // you must also specify the owner project of the reservation - the path to the reservation.
    String reservationPath =
        String.format("projects/%s/reservations/%s", projectId, reservationName);
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (InstancesClient instancesClient = InstancesClient.create()) {
      AttachedDisk disk =
          AttachedDisk.newBuilder()
              .setBoot(true)
              .setAutoDelete(true)
              .setType(AttachedDisk.Type.PERSISTENT.toString())
              .setDeviceName("disk-1")
              .setInitializeParams(
                  AttachedDiskInitializeParams.newBuilder()
                      .setSourceImage(sourceImage)
                      .setDiskSizeGb(diskSizeGb)
                      .build())
              .build();

      NetworkInterface networkInterface = NetworkInterface.newBuilder()
          .setName(networkName)
          .build();

      ReservationAffinity reservationAffinity =
          ReservationAffinity.newBuilder()
              .setConsumeReservationType(SPECIFIC_RESERVATION.toString())
              .setKey("compute.googleapis.com/reservation-name")
              // Set specific reservation
              .addValues(reservationPath)
              .build();

      Instance instanceResource =
          Instance.newBuilder()
              .setName(instanceName)
              .setMachineType(machineType)
              .addDisks(disk)
              .addNetworkInterfaces(networkInterface)
              .setMinCpuPlatform(minCpuPlatform)
              .setReservationAffinity(reservationAffinity)
              .build();

      InsertInstanceRequest insertInstanceRequest = InsertInstanceRequest.newBuilder()
          .setProject(projectId)
          .setZone(zone)
          .setInstanceResource(instanceResource)
          .build();

      OperationFuture<Operation, Operation> operation = instancesClient.insertAsync(
          insertInstanceRequest);
      Operation response = operation.get(3, TimeUnit.MINUTES);

      if (response.hasError()) {
        return null;
      }
      return instancesClient.get(projectId, zone, instanceName);
    }
  }
}

Node.js

Os exemplos a seguir mostram como criar uma instância N1 com 4 vCPUs e Intel Skylake como a plataforma mínima de CPU na zona us-central1-a para consumir uma reserva específica correspondente:

// Import the Compute library
const computeLib = require('@google-cloud/compute');
const compute = computeLib.protos.google.cloud.compute.v1;

// Instantiate a reservationsClient
const instancesClient = new computeLib.InstancesClient();
// Instantiate a zoneOperationsClient
const zoneOperationsClient = new computeLib.ZoneOperationsClient();

/**
 * TODO(developer): Update/uncomment these variables before running the sample.
 */
// The ID of the project where you want to create instance.
const projectId = await instancesClient.getProjectId();
// The zone in which to create instance.
const zone = 'us-central1-a';
// The name of the instance to create.
// const instanceName = 'instance-01';
// The name of the reservation to consume.
// Ensure that the specificReservationRequired field in reservation properties is set to true.
// const reservationName = 'reservation-01';
// Machine type to use for VM.
const machineType = 'n1-standard-4';

// Create instance to consume a specific single-project reservation
async function callCreateInstanceToConsumeSingleProjectReservation() {
  // Describe the size and source image of the boot disk to attach to the instance.
  // Ensure that the VM's properties match the reservation's VM properties,
  // including the zone, machine type (machine family, vCPUs, and memory),
  // minimum CPU platform, GPU amount and type, and local SSD interface and size
  const disk = new compute.Disk({
    boot: true,
    autoDelete: true,
    type: 'PERSISTENT',
    initializeParams: {
      diskSizeGb: '10',
      sourceImage: 'projects/debian-cloud/global/images/family/debian-12',
    },
  });

  //  Define networkInterface
  const networkInterface = new compute.NetworkInterface({
    name: 'global/networks/default',
  });

  // Define reservationAffinity
  const reservationAffinity = new compute.ReservationAffinity({
    consumeReservationType: 'SPECIFIC_RESERVATION',
    key: 'compute.googleapis.com/reservation-name',
    values: [reservationName],
  });

  // Create an instance
  const instance = new compute.Instance({
    name: instanceName,
    machineType: `zones/${zone}/machineTypes/${machineType}`,
    minCpuPlatform: 'Intel Skylake',
    disks: [disk],
    networkInterfaces: [networkInterface],
    reservationAffinity,
  });

  const [response] = await instancesClient.insert({
    project: projectId,
    instanceResource: instance,
    zone,
  });

  let operation = response.latestResponse;

  // Wait for the create instance operation to complete.
  while (operation.status !== 'DONE') {
    [operation] = await zoneOperationsClient.wait({
      operation: operation.name,
      project: projectId,
      zone: operation.zone.split('/').pop(),
    });
  }

  console.log(`Instance ${instanceName} created.`);
}

await callCreateInstanceToConsumeSingleProjectReservation();

Python

Os exemplos a seguir mostram como criar uma instância N2 com 32 vCPUs e Intel Cascade Lake como a plataforma mínima de CPU na zona us-central1-a para consumir uma reserva específica correspondente:

Para criar e consumir o exemplo de reserva específica, faça o seguinte:

  • Para criar e consumir a reserva de exemplo como uma reserva de projeto único, use o exemplo de código a seguir:

    from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def consume_specific_single_project_reservation(
    project_id: str,
    zone: str,
    reservation_name: str,
    instance_name: str,
    machine_type: str = "n1-standard-1",
    min_cpu_platform: str = "Intel Ivy Bridge",
) -> compute_v1.Instance:
    """
    Creates a specific reservation in a single project and launches a VM
    that consumes the newly created reservation.
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone to create the reservation.
        reservation_name (str): The name of the reservation to create.
        instance_name (str): The name of the instance to create.
        machine_type (str): The machine type for the instance.
        min_cpu_platform (str): The minimum CPU platform for the instance.
    """
    instance_properties = (
        compute_v1.AllocationSpecificSKUAllocationReservedInstanceProperties(
            machine_type=machine_type,
            min_cpu_platform=min_cpu_platform,
        )
    )

    reservation = compute_v1.Reservation(
        name=reservation_name,
        specific_reservation=compute_v1.AllocationSpecificSKUReservation(
            count=3,
            instance_properties=instance_properties,
        ),
        # Only VMs that target the reservation by name can consume from this reservation
        specific_reservation_required=True,
    )

    # Create a reservation client
    client = compute_v1.ReservationsClient()
    operation = client.insert(
        project=project_id,
        zone=zone,
        reservation_resource=reservation,
    )
    wait_for_extended_operation(operation, "Reservation creation")

    instance = compute_v1.Instance()
    instance.name = instance_name
    instance.machine_type = f"zones/{zone}/machineTypes/{machine_type}"
    instance.min_cpu_platform = min_cpu_platform
    instance.zone = zone

    # Set the reservation affinity to target the specific reservation
    instance.reservation_affinity = compute_v1.ReservationAffinity(
        consume_reservation_type="SPECIFIC_RESERVATION",  # Type of reservation to consume
        key="compute.googleapis.com/reservation-name",  # Key for the reservation
        values=[reservation_name],  # Reservation name to consume
    )
    # Define the disks for the instance
    instance.disks = [
        compute_v1.AttachedDisk(
            boot=True,  # Indicates that this is a boot disk
            auto_delete=True,  # The disk will be deleted when the instance is deleted
            initialize_params=compute_v1.AttachedDiskInitializeParams(
                source_image="projects/debian-cloud/global/images/family/debian-11",
                disk_size_gb=10,
            ),
        )
    ]
    instance.network_interfaces = [
        compute_v1.NetworkInterface(
            network="global/networks/default",  # The network to use
            access_configs=[
                compute_v1.AccessConfig(
                    name="External NAT",  # Name of the access configuration
                    type="ONE_TO_ONE_NAT",  # Type of access configuration
                )
            ],
        )
    ]
    # Create a request to insert the instance
    request = compute_v1.InsertInstanceRequest()
    request.zone = zone
    request.project = project_id
    request.instance_resource = instance

    vm_client = compute_v1.InstancesClient()
    operation = vm_client.insert(request)
    wait_for_extended_operation(operation, "instance creation")
    print(f"Instance {instance_name} with specific reservation created successfully.")

    return vm_client.get(project=project_id, zone=zone, instance=instance_name)

  • Para criar e consumir o exemplo de reserva como uma reserva compartilhada, use o exemplo de código a seguir:

    from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def consume_specific_shared_project_reservation(
    owner_project_id: str,
    shared_project_id: str,
    zone: str,
    reservation_name: str,
    instance_name: str,
    machine_type: str = "n1-standard-1",
    min_cpu_platform: str = "Intel Ivy Bridge",
) -> compute_v1.Instance:
    """
    Creates a specific reservation in a single project and launches a VM
    that consumes the newly created reservation.
    Args:
        owner_project_id (str): The ID of the Google Cloud project.
        shared_project_id: The ID of the owner project of the reservation in the same zone.
        zone (str): The zone to create the reservation.
        reservation_name (str): The name of the reservation to create.
        instance_name (str): The name of the instance to create.
        machine_type (str): The machine type for the instance.
        min_cpu_platform (str): The minimum CPU platform for the instance.
    """
    instance_properties = (
        compute_v1.AllocationSpecificSKUAllocationReservedInstanceProperties(
            machine_type=machine_type,
            min_cpu_platform=min_cpu_platform,
        )
    )

    reservation = compute_v1.Reservation(
        name=reservation_name,
        specific_reservation=compute_v1.AllocationSpecificSKUReservation(
            count=3,
            instance_properties=instance_properties,
        ),
        # Only VMs that target the reservation by name can consume from this reservation
        specific_reservation_required=True,
        share_settings=compute_v1.ShareSettings(
            share_type="SPECIFIC_PROJECTS",
            project_map={
                shared_project_id: compute_v1.ShareSettingsProjectConfig(
                    project_id=shared_project_id
                )
            },
        ),
    )

    # Create a reservation client
    client = compute_v1.ReservationsClient()
    operation = client.insert(
        project=owner_project_id,
        zone=zone,
        reservation_resource=reservation,
    )
    wait_for_extended_operation(operation, "Reservation creation")

    instance = compute_v1.Instance()
    instance.name = instance_name
    instance.machine_type = f"zones/{zone}/machineTypes/{machine_type}"
    instance.min_cpu_platform = min_cpu_platform
    instance.zone = zone

    # Set the reservation affinity to target the specific reservation
    instance.reservation_affinity = compute_v1.ReservationAffinity(
        consume_reservation_type="SPECIFIC_RESERVATION",  # Type of reservation to consume
        key="compute.googleapis.com/reservation-name",
        # To consume this reservation from any consumer projects, specify the owner project of the reservation
        values=[f"projects/{owner_project_id}/reservations/{reservation_name}"],
    )
    # Define the disks for the instance
    instance.disks = [
        compute_v1.AttachedDisk(
            boot=True,  # Indicates that this is a boot disk
            auto_delete=True,  # The disk will be deleted when the instance is deleted
            initialize_params=compute_v1.AttachedDiskInitializeParams(
                source_image="projects/debian-cloud/global/images/family/debian-11",
                disk_size_gb=10,
            ),
        )
    ]
    instance.network_interfaces = [
        compute_v1.NetworkInterface(
            network="global/networks/default",  # The network to use
            access_configs=[
                compute_v1.AccessConfig(
                    name="External NAT",  # Name of the access configuration
                    type="ONE_TO_ONE_NAT",  # Type of access configuration
                )
            ],
        )
    ]
    # Create a request to insert the instance
    request = compute_v1.InsertInstanceRequest()
    request.zone = zone
    # The instance will be created in the shared project
    request.project = shared_project_id
    request.instance_resource = instance

    vm_client = compute_v1.InstancesClient()
    operation = vm_client.insert(request)
    wait_for_extended_operation(operation, "instance creation")
    print(f"Instance {instance_name} from project {owner_project_id} created.")
    # The instance is created in the shared project, so we return it from there.
    return vm_client.get(project=shared_project_id, zone=zone, instance=instance_name)

REST

O exemplo a seguir mostra como criar uma reserva específica na zona us-central1-a para três instâncias N2 com 32 vCPUs e Intel Cascade Lake como a plataforma de CPU mínima. Ele também mostra como criar uma única instância para consumir a reserva.

Para criar e consumir o exemplo de reserva específica, faça o seguinte:

  1. Para criar a reserva de exemplo, faça uma solicitação POST para o método instances.insert. No corpo da solicitação, inclua o campo specificReservationRequired definido como true:

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations

{
  "name": "reservation-02",
  "specificReservation": {
    "count": "3",
    "instanceProperties": {
      "machineType": "n2-standard-32",
      "minCpuPlatform": "Intel Cascade Lake",
    }
  },
  "specificReservationRequired": true
}

  2. Para criar uma instância que consuma a reserva de exemplo, faça uma solicitação POST para o método instances.insert. No corpo da solicitação, no campo reservationAffinity, inclua o seguinte:

    • O campo consumeReservationType definido como SPECIFIC_RESERVATION.

    • O campo key definido como compute.googleapis.com/reservation-name.

    • O campo values definido como o URL da reserva.

    A solicitação é semelhante a esta:

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances

{
  "name": "instance-02",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-32",
  "minCpuPlatform": "Intel Cascade Lake",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-12"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "SPECIFIC_RESERVATION",
    "key": "compute.googleapis.com/reservation-name",
    "values": [
      "RESERVATION_URL"
    ]
  }
}

    Substitua RESERVATION_URL pelo URL da reserva. Especifique um dos seguintes valores:

    • Se você criou a reserva no mesmo projeto: reservation-02

    • Se a reserva estiver em outro projeto: projects/PROJECT_ID/reservations/reservation-02

Efetivar uma reserva criada automaticamente para uma solicitação no modo de agenda

Esse tipo de reserva permite que novas instâncias de computação consumam uma reserva que o Compute Engine cria automaticamente (criação automática) para atender a uma reserva adiantada no modo de calendário.

Para consumir esse tipo de reserva, crie uma instância da seguinte maneira:

O exemplo a seguir cria uma solicitação de reserva adiantada no modo de calendário para instâncias A3 Ultra. O exemplo também mostra os campos a serem especificados ao criar uma instância independente do A3 Ultra para consumir a reserva criada automaticamente para a solicitação.

Para consumir o exemplo de reserva criada automaticamente, selecione uma das seguintes opções:

Console

  1. Crie um exemplo de solicitação para cinco instâncias A3 Ultra e envie para análise:

    1. No console do Google Cloud , acesse a página Reservas.

      Acesse "Reservas"

    2. Clique na guia Reservas adiantadas.

    3. Clique em Criar reserva adiantada. A página Criar uma reserva adiantada é exibida.

    4. Clique na guia GPUs e, na lista Tipo de GPU, selecione NVIDIA H200 141 GB. Essa ação especifica uma instância A3 Ultra.

    5. No campo Capacidade total necessária, insira 5.

    6. Na seção Período de reserva, especifique o horário de início e a duração do período de reserva.

    7. Clique em Pesquisar capacidade e, na seção Capacidade disponível, selecione uma das máquinas disponíveis.

    8. Clique em Criar.

  2. No horário de início da solicitação, para criar uma instância A3 Ultra e consumir a reserva de exemplo criada automaticamente, faça o seguinte:

    1. No console do Google Cloud , acesse a página Criar uma instância.

      Acesse "Criar uma instância"

    2. No campo Nome, dê um nome para a instância. Neste exemplo, digite example-instance.

    3. Especifique a Região e a Zona em que a reserva criada automaticamente está. Para este exemplo, selecione us-central1 e us-central1-b, respectivamente.

    4. Clique na guia GPUs e, na lista Tipo de GPU, selecione NVIDIA H200 141 GB. Essa ação especifica uma instância A3 Ultra e define o modelo de provisionamento como Vinculado à reserva.

    5. No menu de navegação, clique em Avançado.

    6. Na seção Reservas, selecione Escolher uma reserva e clique em Escolher reserva.

    7. No painel Escolher uma reserva, faça o seguinte:

      1. Selecione o exemplo de reserva criada automaticamente.

      2. Clique em Escolher.

    8. Na seção Modelo de provisionamento, abra a seção Configurações avançadas do modelo de provisionamento de VM.

    9. Na lista No encerramento da VM, selecione Parar (padrão) ou Excluir.

    10. Clique em Criar.

gcloud

  1. Para criar um exemplo de solicitação de cinco VMs A3 Ultra e enviar para análise, use o comando gcloud compute future-reservations create:

    gcloud compute future-reservations create example-fr \
    --auto-delete-auto-created-reservations \
    --deployment-type=DENSE \
    --planning-status=SUBMITTED \
    --require-specific-reservation \
    --reservation-mode=CALENDAR \
    --reservation-name=example-reservation \
    --share-setting=local \
    --start-time=2026-03-05T00:00:00Z \
    --end-time=2026-03-19T00:00:00Z \
    --machine-type=a3-ultragpu-8g \
    --total-count=5 \
    --zone=us-central1-b

    Suponha que Google Cloud aprove a solicitação e o Compute Engine crie automaticamente uma reserva vazia. No horário de início da solicitação, em 5 de março de 2026, o Compute Engine aumenta o número de VMs de GPU reservadas na reserva. Depois, você pode consumir a reserva.

  2. No horário de início da solicitação, para criar uma instância A3 Ultra e consumir a reserva de exemplo criada automaticamente, use o comando gcloud compute instances create com as seguintes flags:

    • A sinalização --instance-termination-action

    • A flag --provisioning-model definida como RESERVATION_BOUND.

    • A sinalização --reservation

    • A flag --reservation-affinity definida como specific.

    O comando é semelhante a este: Para conferir todos os requisitos para criar uma instância A3 Ultra, consulte Criar uma instância A3 Ultra ou A4.

    gcloud compute instance create example-a3ultra-instance  \
    --machine-type=a3-ultragpu-8g \
    --instance-termination-action=TERMINATION_ACTION \
    --provisioning-model=RESERVATION_BOUND \
    --reservation-affinity=specific \
    --reservation=RESERVATION_URL \
    --zone=us-central1-b \
    ...

    O comando inclui os seguintes valores:

    • TERMINATION_ACTION: se o Compute Engine interrompe (STOP) ou exclui (DELETE) a VM ao final do período de reserva.

    • RESERVATION_URL: o URL da reserva, formatado da seguinte maneira:

      • Se a reserva criada automaticamente existir no seu projeto: example-reservation.

      • Se a reserva criada automaticamente estiver em outro projeto: projects/PROJECT_ID/reservations/example-reservation.

REST

  1. Para criar um exemplo de solicitação de cinco instâncias A3 Ultra e enviá-lo para revisão, faça uma solicitação POST para o método futureReservations.insert:

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-b/futureReservations

{
  "name": "example-request-calendar-mode",
  "autoDeleteAutoCreatedReservations": true,
  "deploymentType": "DENSE",
  "planningStatus": "SUBMITTED",
  "reservationMode": "CALENDAR",
  "reservationName": "example-reservation",
  "shareSettings": {
    "shareType": "LOCAL"
  },
  "specificReservationRequired": true,
  "specificSkuProperties": {
    "machineType": "a3-ultragpu-8g",
    "totalCount": 5
  },
  "timeWindow": {
    "startTime": "2026-03-05T00:00:00Z",
    "endTime": "2026-03-19T00:00:00Z"
  }
}

    Suponha que Google Cloud aprove a solicitação e o Compute Engine crie automaticamente uma reserva vazia. No horário de início da solicitação, em 5 de março de 2026, o Compute Engine aumenta o número de VMs de GPU reservadas na reserva. Depois, você pode consumir a reserva.

  2. No horário de início da solicitação, para criar uma instância A3 Ultra e consumir a reserva de exemplo criada automaticamente, faça uma solicitação POST para o método instances.insert. No corpo da solicitação, inclua estes campos:

    • O campo reservationAffinity.consumeReservationType definido como SPECIFIC_RESERVATION.

    • O campo reservationAffinity.key definido como compute.googleapis.com/reservation-name.

    • O campo reservationAffinity.values definido como o URL da reserva.

    • O campo scheduling.instanceTerminationAction.

    • O campo scheduling.provisioningModel definido como RESERVATION_BOUND.

    A solicitação é semelhante a esta. Para conferir todos os requisitos para criar uma instância A3 Ultra, consulte Criar uma instância A3 Ultra ou A4.

    POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-b/

{
  {
    "machineType": "projects/example-project/zones/us-central1-b/machineTypes/a3-ultragpu-8g",
    "name": "example-a3ultra-instance",
    "reservationAffinity": {
      "consumeReservationType": "SPECIFIC_RESERVATION",
      "key": "compute.googleapis.com/reservation-name",
      "values":[
        "RESERVATION_URL"
      ],
    },
    "scheduling": {
      "instanceTerminationAction": "TERMINATION_ACTION",
      "provisioningModel": "RESERVATION_BOUND"
    },
    ...
  }
}

    O corpo da solicitação inclui os seguintes valores:

    • RESERVATION_URL: o URL da reserva, formatado da seguinte maneira:

      • Se a reserva criada automaticamente existir no seu projeto: example-reservation.

      • Se a reserva criada automaticamente estiver em outro projeto: projects/PROJECT_ID/reservations/example-reservation.

    • TERMINATION_ACTION: se o Compute Engine interrompe (STOP) ou exclui (DELETE) a VM ao final do período de reserva.

Testar se as propriedades da instância correspondem a uma reserva consumida automaticamente

Para testar se as propriedades de uma instância de computação correspondem a uma reserva consumida automaticamente, faça o seguinte:

  1. Crie uma cópia da reserva como uma reserva com segmentação específica para uma única instância.

  2. Crie uma instância de teste para consumir a reserva.

Se você conseguir criar a instância de teste, as propriedades dela vão corresponder às da reserva de teste. Caso contrário, você vai encontrar erros.

Depois de confirmar que as propriedades da instância e da reserva de teste correspondem, exclua a reserva e a instância de teste.

Verificar o consumo das reservas

Para verificar o consumo de reservas, use um dos seguintes métodos:

A seguir