Consuma reservas

Este documento explica como consumir reservas no Compute Engine. Para saber como usar reservas noutros Google Cloud produtos, consulte a seguinte documentação:

Depois de criar uma reserva ou o Compute Engine criar automaticamente uma reserva para si para satisfazer uma reserva futura, o Compute Engine retém os recursos reservados para si. Em seguida, pode usar esses recursos reservados para criar instâncias do Compute Engine que correspondam às propriedades da reserva. Esta ação é conhecida como consumir uma reserva. Pode usar a capacidade reservada para criar instâncias até que a reserva seja totalmente consumida.

Limitações

Não pode consumir uma reserva para criar os seguintes recursos do Compute Engine:

  • VMs do Spot ou instâncias preemptivas

  • Nós de inquilino único

Antes de começar

  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-se no Compute Engine selecionando uma das seguintes opções:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    Go

    Para usar os Go exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    Java

    Para usar os Java exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    Node.js

    Para usar os Node.js exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    Python

    Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

Funções necessárias

Para receber as autorizações de que precisa para consumir reservas, peça ao seu administrador para lhe conceder a função de IAM Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para consumir reservas. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para consumir reservas:

  • Para criar reservas: compute.reservations.create no projeto
  • Para criar instâncias:
    • compute.instances.create no projeto
    • Para usar uma imagem personalizada para criar a VM: compute.images.useReadOnly na imagem
    • Para usar um instantâneo para criar a VM: compute.snapshots.useReadOnly no instantâneo
    • Para usar um modelo de instância para criar a VM: compute.instanceTemplates.useReadOnly no modelo de instância
    • Para atribuir uma rede antiga à VM: compute.networks.use no projeto
    • Para especificar um endereço IP estático para a VM: compute.addresses.use no projeto
    • Para atribuir um endereço IP externo à VM quando usar uma rede antiga: compute.networks.useExternalIp no projeto
    • Para especificar uma sub-rede para a VM: compute.subnetworks.use no projeto ou na sub-rede escolhida
    • Para atribuir um endereço IP externo à VM quando usar uma rede VPC: compute.subnetworks.useExternalIp no projeto ou na sub-rede escolhida
    • Para definir os metadados da instância de VM para a VM: compute.instances.setMetadata no projeto
    • Para definir etiquetas para a VM: compute.instances.setTags na VM
    • Para definir etiquetas para a VM: compute.instances.setLabels na VM
    • Para definir uma conta de serviço para a VM usar: compute.instances.setServiceAccount na VM
    • Para criar um novo disco para a VM: compute.disks.create no projeto
    • Para anexar um disco existente no modo de leitura ou leitura/escrita: compute.disks.use no disco
    • Para anexar um disco existente no modo de leitura: compute.disks.useReadOnly no disco
  • Para criar modelos de instâncias: compute.instanceTemplates.create no projeto

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Consuma uma reserva

Os exemplos nas secções seguintes mostram como consumir uma reserva através da criação de uma única instância de computação. Também pode consumir reservas criando instâncias que correspondam às propriedades das reservas através de uma opção de implementação diferente ou atualizando as propriedades das instâncias existentes para corresponderem às reservas consumidas automaticamente.

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

Use uma reserva consumida automaticamente

As reservas consumidas automaticamente permitem que quaisquer instâncias de computação que correspondam às propriedades da reserva a consumam automaticamente. Este comportamento de consumo aplica-se a instâncias em execução novas e existentes. Quando cria reservas ou o Compute Engine cria automaticamente uma reserva para satisfazer uma reserva futura, este tipo de reserva é a predefinição.

Se as propriedades de uma reserva automática de projeto único e de uma reserva automática partilhada corresponderem, as instâncias no seu projeto consomem primeiro a reserva de projeto único e, em seguida, consomem a reserva partilhada. Para mais informações, consulte a ordem de consumo das reservas.

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

Consola

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

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

  1. Para criar uma reserva de exemplo, conclua os seguintes passos:

    1. Na Google Cloud consola, aceda à página Reservas.

      Aceda a Reservas

      Os passos restantes aparecem automaticamente na consolaGoogle Cloud .

    2. No separador Reserva a pedido (predefinição), clique em Criar reserva. É apresentada a página Criar uma reserva.

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

    4. Selecione a Região e a Zona onde reservar recursos. Por exemplo, selecione us-central1 e us-central1-a, respetivamente.

    5. Na secção Tipo de partilha, faça uma das seguintes ações:

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

      • Para criar uma reserva partilhada, selecione Partilhada e, de seguida, especifique os projetos com os quais quer partilhar a reserva.

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

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

    8. No separador Utilização geral, selecione N2.

    9. Na secção Tipo de máquina, no separador Predefinição (predefinição), selecione n2-standard-32.

    10. Expanda Plataforma da CPU e GPU e, de seguida, no campo Plataforma da CPU, selecione Intel Cascade Lake ou posterior.

    11. Clique em Criar.

  2. Para criar uma instância que consuma a reserva de exemplo, conclua os seguintes passos:

    1. Na Google Cloud consola, aceda à página Criar uma instância.

      Aceda a Criar uma instância

      É apresentada a página Criar uma instância, que mostra o painel Configuração da máquina.

    2. No painel Configuração do computador, faça o seguinte:

      1. No campo Nome, introduza um nome para a instância. Para este exemplo, introduza instance-01.

      2. Especifique a região e a zona onde reservar recursos. Para este exemplo, selecione us-central1 e us-central1-a, respetivamente.

      3. No separador Utilização geral, selecione N2.

      4. Na secção Tipo de máquina, no separador Predefinição (predefinição), selecione n2-standard-32.

      5. Expanda a secção Opções avançadas e, de seguida, no campo Plataforma da CPU, selecione Intel Cascade Lake ou posterior.

    3. Opcional: consumir automaticamente uma reserva correspondente é a predefinição. No entanto, se quiser especificar esta definição, faça o seguinte:

      1. No menu de navegação, clique em Avançadas. É apresentado o painel Avançadas.

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

    4. Clique em Criar.

gcloud

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

Para criar a reserva automática de exemplo e usá-la, 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. Uma vez que any é a configuração predefinida, também pode omitir esta 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 através de um modelo de instância e criar uma instância para consumir a reserva através do 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 seguinte mostra como criar uma instância N1 com quatro vCPUs e o 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 seguinte mostra como criar uma instância N1 com quatro vCPUs e o 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 seguinte mostra como criar uma reserva automática na zona us-central1-a para três instâncias N1 com 1 vCPU e o Intel Ivy como a plataforma de CPU mínima. Também mostra como criar uma única instância para consumir a reserva.

Para criar a reserva automática de exemplo e usá-la, 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 seguinte mostra como criar uma reserva automática na zona us-central1-a para três instâncias N2 com 32 vCPUs e o Intel Cascade Lake como a plataforma de CPU mínima. Também mostra como criar uma única instância para consumir a reserva.

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

  1. Para criar a reserva de exemplo, faça um pedido POST ao 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 um pedido POST ao método instances.insert. No corpo do pedido, inclua o campo consumeReservationType definido como ANY_RESERVATION. No entanto, uma vez que ANY_RESERVATION é a configuração predefinida, também pode 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"
  }
}

Consuma uma reserva especificamente segmentada

As reservas especificamente segmentadas permitem que novas instâncias de computação correspondam às propriedades da reserva e segmentem a reserva para a consumir. As instâncias só são criadas com êxito se as respetivas propriedades corresponderem às propriedades de reserva. Caso contrário, ocorrem erros.

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

Método de criação Quando cria uma reserva Quando cria instâncias
Google Cloud consola Na secção Usar com instância de VM, selecione Selecionar reserva específica. No painel Avançadas, na secçã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 está definida como specific.
  • O sinalizador --reservation está definido para o URL da reserva.
Go Inclua o campo SpecificReservationRequired definido como true. No campo ReservationAffinity, inclua os seguintes campos:
  • O campo ConsumeReservationType está definido como SPECIFIC_RESERVATION.
  • O campo Key está definido como compute.googleapis.com/reservation-name.
  • O campo Values está definido como o URL da reserva.
Java Inclua o campo setSpecificReservationRequired definido como true. No campo ReservationAffinity, inclua os seguintes campos:
  • O campo setConsumeReservationType está definido como SPECIFIC_RESERVATION.
  • O campo setKey está definido como compute.googleapis.com/reservation-name.
  • O campo addValues está definido como o URL da reserva.
Node.js e API REST Inclua o campo specificReservationRequired definido como true. No campo reservationAffinity, inclua os seguintes campos:
  • O campo consumeReservationType está definido como SPECIFIC_RESERVATION.
  • O campo key está definido como compute.googleapis.com/reservation-name.
  • O campo values está definido como o URL da reserva.
Python e Terraform Inclua o campo specific_reservation_required definido como true. No campo reservation_affinity, inclua os seguintes campos:
  • O campo consume_reservation_type está definido como SPECIFIC_RESERVATION.
  • O campo key está definido como compute.googleapis.com/reservation-name.
  • O campo values está definido como o URL da reserva.

Para criar uma reserva específica de exemplo e uma instância para a consumir, selecione uma das seguintes opções:

Consola

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

Para criar a reserva específica do exemplo e consumi-la, faça o seguinte:

  1. Para criar uma reserva de exemplo, conclua os seguintes passos:

    1. Na Google Cloud consola, aceda à página Reservas.

      Aceda a Reservas

      Os passos restantes aparecem automaticamente na consolaGoogle Cloud .

    2. No separador Reserva a pedido (predefinição), clique em Criar reserva. É apresentada a página Criar uma reserva.

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

    4. Especifique a região e a zona onde reservar recursos. Para este exemplo, selecione us-central1 e us-central1-a, respetivamente.

    5. Na secção Tipo de partilha, faça uma das seguintes ações:

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

      • Para criar uma reserva partilhada, selecione Partilhada e, de seguida, especifique os projetos com os quais quer partilhar a reserva.

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

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

    8. No separador Utilização geral, selecione N2.

    9. Na secção Tipo de máquina, no separador Predefinição (predefinição), selecione n2-standard-32.

    10. Expanda Plataforma da CPU e GPU e, de seguida, no campo Plataforma da CPU, selecione Intel Cascade Lake ou posterior.

    11. Clique em Criar.

  2. Para criar uma instância que consuma a reserva de exemplo, conclua os seguintes passos:

    1. Na Google Cloud consola, aceda à página Criar uma instância.

      Aceda a Criar uma instância

      É apresentada a página Criar uma instância, que mostra o painel Configuração da máquina.

    2. No painel Configuração do computador, faça o seguinte:

      1. No campo Nome, introduza um nome para a instância. Para este exemplo, introduza instance-02.

      2. Especifique a região e a zona onde reservar recursos. Para este exemplo, selecione us-central1 e us-central1-a, respetivamente.

      3. No separador Utilização geral, selecione N2.

      4. Na secção Tipo de máquina, no separador Predefinição (predefinição), selecione n2-standard-32.

      5. Expanda a secção Opções avançadas e, de seguida, no campo Plataforma da CPU, selecione Intel Cascade Lake ou posterior.

    3. No menu de navegação, clique em Avançadas. O painel Avançadas é apresentado.

    4. Na secção Reservas, selecione Escolher uma reserva e, de seguida, clique em Escolher reserva.

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

      1. Selecione a reserva específica que criou nos passos anteriores. Se quiser consumir uma reserva partilhada existente num projeto diferente, na lista Projeto, selecione o projeto no qual a reserva existe.

      2. Clique em Escolher.

    6. Clique em Criar.

gcloud

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

Para criar a reserva específica do exemplo e consumi-la, 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 criou a reserva no mesmo projeto: reservation-02

    • Se a reserva estiver num projeto diferente: projects/PROJECT_ID/reservations/reservation-02

Go

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

  • Para criar a instância de exemplo para consumir uma reserva específica de um único projeto, 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 para consumir uma reserva específica partilhada, 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 seguintes mostram como criar uma instância N1 com quatro vCPUs e o Intel Skylake como a plataforma de CPU mínima, na zona us-central1-a, para consumir uma reserva específica correspondente:

  • Para criar uma reserva de exemplo como uma reserva de projeto único e criar uma instância para a consumir, 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 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 uma reserva de exemplo como uma reserva partilhada e criar uma instância para a consumir, 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 seguintes mostram como criar uma instância N1 com 4 vCPUs e Intel Skylake como a plataforma de CPU mínima, 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 seguintes mostram como criar uma instância N2 com 32 vCPUs e Intel Cascade Lake como a plataforma de CPU mínima, na zona us-central1-a para consumir uma reserva específica correspondente:

Para criar a reserva específica do exemplo e consumi-la, faça o seguinte:

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

    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 partilhada, use o seguinte exemplo de código:

    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 seguinte mostra como criar uma reserva específica na zona us-central1-a para três instâncias N2 com 32 vCPUs e o Intel Cascade Lake como a plataforma de CPU mínima. Também mostra como criar uma única instância para consumir a reserva.

Para criar a reserva específica do exemplo e consumi-la, faça o seguinte:

  1. Para criar a reserva de exemplo, faça um pedido POST ao método instances.insert. No corpo do pedido, inclua o conjunto de campos 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 um pedido POST ao método instances.insert. No corpo do pedido, no campo reservationAffinity, inclua o seguinte:

    • O campo consumeReservationType está definido como SPECIFIC_RESERVATION.

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

    • O campo values está definido como o URL da reserva.

    O pedido é semelhante ao seguinte:

    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 criou a reserva no mesmo projeto: reservation-02

    • Se a reserva estiver num projeto diferente: projects/PROJECT_ID/reservations/reservation-02

Consuma uma reserva criada automaticamente para um pedido no modo de calendário

Este tipo de reserva permite que novas instâncias de computação consumam uma reserva que o Compute Engine cria automaticamente para cumprir uma reserva futura no modo de calendário.

Para consumir este tipo de reserva, tem de criar uma instância da seguinte forma:

O exemplo seguinte cria um pedido de reserva futuro no modo de calendário para instâncias A3 Ultra. O exemplo também mostra os campos a especificar quando cria uma instância A3 Ultra autónoma para consumir a reserva criada automaticamente para o pedido.

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

Consola

  1. Crie um pedido de exemplo para cinco instâncias A3 Ultra e envie-o para revisão:

    1. Na Google Cloud consola, aceda à página Reservas.

      Aceda a Reservas

    2. Clique no separador Reservas futuras.

    3. Clique em Criar reserva futura. É apresentada a página Crie uma reserva futura.

    4. Na secção Configuração de hardware, selecione Especificar tipo de máquina e, em seguida, especifique uma instância A3 Ultra.

    5. Na secção Método de obtenção, conclua os seguintes passos:

      1. Selecione Pesquisar capacidade durante um período máximo de 90 dias.

      2. Nas listas Região e Zona, especifique a região e a zona onde reservar recursos. Para este exemplo, selecione us-central1 e us-central1-a, respetivamente.

      3. No campo Capacidade total necessária, introduza 5.

      4. Na secção Período de reserva, especifique o período de reserva para a reserva.

    6. Especifique os restantes campos e, de seguida, clique em Enviar.

  2. Na hora de início do pedido, para criar uma instância A3 Ultra para consumir a reserva criada automaticamente de exemplo, faça o seguinte:

    1. Na Google Cloud consola, aceda à página Criar uma instância.

      Aceda a Criar uma instância

    2. No campo Nome, introduza um nome para a instância. Para este exemplo, introduza example-instance.

    3. Especifique a Região e a Zona onde quer reservar recursos. Para este exemplo, selecione us-central1 e us-central1-a, respetivamente.

    4. Clique no separador GPUs e, de seguida, na lista Tipo de GPU, selecione NVIDIA H200 141 GB. Esta ação especifica uma instância A3 Ultra e define o modelo de aprovisionamento como Associado à reserva.

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

    6. Na secção Reservas, selecione Escolher uma reserva e, de seguida, clique em Escolher uma reserva.

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

      1. Selecione uma reserva específica. Se quiser consumir uma reserva partilhada que exista num projeto diferente, na lista Projeto, selecione o projeto no qual a reserva existe.

      2. Clique em Escolher.

    8. Na secção Modelo de aprovisionamento, expanda a secção Definições avançadas do modelo de aprovisionamento de VMs.

    9. Na lista No encerramento da VM, selecione Parar (predefinição) ou Eliminar.

    10. Clique em Criar.

gcloud

  1. Para criar um pedido de exemplo de cinco VMs A3 Ultra e enviá-lo para revisão, use o comando gcloud beta compute future-reservations create:

    gcloud beta 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-type=local \
    --start-time=2025-10-05T00:00:00Z \
    --end-time=2025-10-19T00:00:00Z \
    --machine-type=a3-ultragpu-8g \
    --total-count=5 \
    --zone=us-central1-a

    Suponha que Google Cloud aprova o pedido e o Compute Engine cria automaticamente uma reserva vazia. Na hora de início do pedido, a 5 de outubro de 2025, o Compute Engine aumenta o número de VMs de GPU reservadas na reserva. Em seguida, pode usar a reserva.

  2. Na hora de início do pedido, para criar uma instância A3 Ultra para consumir a reserva criada automaticamente de exemplo, use o comando gcloud compute instances create com as seguintes flags:

    • A bandeira de --instance-termination-action.

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

    • A bandeira de --reservation.

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

    O comando é semelhante ao seguinte. Para ver os requisitos completos para criar uma instância A3 Ultra, consulte o artigo Crie uma instância A3 Ultra ou A4.

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

    O comando inclui os seguintes valores:

    • TERMINATION_ACTION: se o Compute Engine para (STOP) ou elimina (DELETE) a VM no final do período de reserva.

    • RESERVATION_URL: o URL da reserva, que está formatado da seguinte forma:

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

      • Se a reserva criada automaticamente existir num projeto diferente: projects/PROJECT_ID/reservations/example-reservation.

REST

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

    POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/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": "2025-10-05T00:00:00Z",
    "endTime": "2025-10-19T00:00:00Z"
  }
}

    Suponha que Google Cloud aprova o pedido e o Compute Engine cria automaticamente uma reserva vazia. Na hora de início do pedido, a 5 de outubro de 2025, o Compute Engine aumenta o número de VMs de GPU reservadas na reserva. Em seguida, pode usar a reserva.

  2. À hora de início do pedido, para criar uma instância A3 Ultra para consumir a reserva criada automaticamente de exemplo, faça um pedido POST para o método instances.insert. No corpo do pedido, inclua os seguintes campos:

    • O campo reservationAffinity.consumeReservationType está definido como SPECIFIC_RESERVATION.

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

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

    • O campo scheduling.instanceTerminationAction.

    • O campo scheduling.provisioningModel está definido como RESERVATION_BOUND.

    O pedido é semelhante ao seguinte. Para ver os requisitos completos para criar uma instância A3 Ultra, consulte o artigo Crie uma instância A3 Ultra ou A4.

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

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

    O corpo do pedido inclui os seguintes valores:

    • RESERVATION_URL: o URL da reserva, que está formatado da seguinte forma:

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

      • Se a reserva criada automaticamente existir num projeto diferente: projects/PROJECT_ID/reservations/example-reservation.

    • TERMINATION_ACTION: se o Compute Engine para (STOP) ou elimina (DELETE) a VM no final do período de reserva.

Teste 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 especificamente segmentada para uma única instância.

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

Se conseguir criar a instância de teste, as respetivas propriedades correspondem às propriedades da reserva de teste. Caso contrário, ocorrem erros.

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

Valide o consumo de reservas

Para validar o consumo de reservas, pode fazer uma ou mais das seguintes ações:

  • Para ver o número atual de instâncias de computação que estão a consumir as suas reservas e quantas mais instâncias as podem consumir, veja as reservas.

  • Para monitorizar os dados de consumo de reservas atualizados a cada 30 minutos e receber alertas quando as reservas são consumidas ou não consumidas, monitorize o consumo de reservas.

  • Para ver os dados de consumo de reservas atualizados a cada 24 horas, faça uma das seguintes ações:

    • Para ver o consumo de reservas passado e previsto para analisar as tendências de consumo e planear as necessidades de capacidade futuras, use o Planeador de capacidade.

O que se segue?