Consumir reservas

Console

En el siguiente ejemplo, se muestra cómo crear una reserva automática en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma de CPU mínima Intel Cascade Lake. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva automática de ejemplo y consumirla, haz lo siguiente:

1. Para crear una reserva de ejemplo, completa los siguientes pasos:

   1. En la consola de Google Cloud , ve a la página Reservas.

      Ir a Reservas

      Los pasos restantes aparecen automáticamente en la consola deGoogle Cloud .

   2. En la pestaña Reserva según demanda (predeterminada), haz clic en add_box Crear reserva. Aparecerá la página Crear una reserva.

   3. En el campo Nombre, ingresa un nombre para la reserva. Por ejemplo, ingresa reservation-01.

   4. Selecciona la región y la zona en las que deseas reservar los recursos. Por ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

   5. En la sección Tipo de uso compartido, realiza una de las siguientes acciones:

      • Para crear una reserva de un solo proyecto, selecciona Local.

      • Para crear una reserva compartida, selecciona Compartido y, luego, especifica los proyectos con los que deseas compartir la reserva.

   6. En la sección Usar con instancia de VM, selecciona Usar reserva de forma automática si aún no está seleccionada.

   7. En el campo Cantidad de instancias de VM, ingresa 3.

   8. En la pestaña De uso general, selecciona N2.

   9. En la sección Tipo de máquina, en la pestaña Predeterminado (opción predeterminada), selecciona n2-standard-32.

   10. Expande Plataforma de CPU y GPU y, luego, en el campo Plataforma de CPU, selecciona Intel Cascade Lake o una versión posterior.

   11. Haz clic en Crear.

2. Para crear una instancia que consuma la reserva de ejemplo, completa los siguientes pasos:

   1. En la consola de Google Cloud , ve a la página Crear una instancia.

      Ir a Crear una instancia

      Aparecerá la página Crear una instancia y se mostrará el panel Configuración de la máquina.

   2. En el panel Configuración de la máquina, haz lo siguiente:

      1. En el campo Nombre, ingresa un nombre para el instancia. En este ejemplo, ingresa instance-01.

      2. Especifica la región y la zona en las que deseas reservar los recursos. Para este ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

      3. En la pestaña De uso general, selecciona N2.

      4. En la sección Tipo de máquina, en la pestaña Predeterminado (opción predeterminada), selecciona n2-standard-32.

      5. Expande la sección Opciones avanzadas y, luego, en el campo Plataforma de CPU, selecciona Intel Cascade Lake o una versión posterior.

   3. Opcional: El consumo automático de una reserva coincidente es el parámetro de configuración predeterminado. Sin embargo, si quieres especificar este parámetro de configuración, haz lo siguiente:

      1. En el menú de navegación, haz clic en Opciones avanzadas. Aparecerá el panel Avanzado.

      2. En la sección Reservas, selecciona Usar la selección automática.

   4. Haz clic en Crear.

gcloud

En el siguiente ejemplo, se muestra cómo crear una reserva automática en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma de CPU mínima Intel Cascade Lake. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva automática de ejemplo y consumirla, haz lo siguiente:

1. Para crear la reserva de ejemplo, usa el 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 crear una instancia que consuma la reserva de ejemplo, usa el comando gcloud compute instances create con la marca --reservation-affinity establecida en any. Dado que any es la configuración predeterminada, también puedes omitir esta marca.

   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 crear la reserva automática de ejemplo con una plantilla de instancias y crear una instancia para consumir la reserva con la misma plantilla, usa el siguiente muestra 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

En el siguiente ejemplo, se muestra cómo crear una instancia N1 con cuatro CPU virtuales y la plataforma de CPU mínima Intel Skylake en la zona us-central1-a. La instancia consume automáticamente una reserva coincidente.

Para crear la instancia de ejemplo, usa el siguiente muestra 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

En el siguiente ejemplo, se muestra cómo crear una instancia N1 con cuatro CPU virtuales y la plataforma de CPU mínima Intel Skylake en la zona us-central1-a. La instancia consume automáticamente una reserva coincidente.

Para crear la instancia de ejemplo, usa el siguiente muestra 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

En el siguiente ejemplo, se muestra cómo crear una reserva automática en la zona us-central1-a para tres instancias N1 con una CPU virtual y la plataforma de CPU mínima Intel Ivy. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva automática de ejemplo y consumirla, haz lo siguiente:

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

En el siguiente ejemplo, se muestra cómo crear una reserva automática en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma de CPU mínima Intel Cascade Lake. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva automática de ejemplo y consumirla, haz lo siguiente:

1. Para crear la reserva de ejemplo, realiza una solicitud POST al 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 crear una instancia que consuma la reserva de ejemplo, realiza una solicitud POST al método instances.insert. En el cuerpo de la solicitud, incluye el campo consumeReservationType configurado como ANY_RESERVATION. Sin embargo, como ANY_RESERVATION es la configuración predeterminada, también puedes omitir el 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"
     }
   }
   

Console

En el siguiente ejemplo, se muestra cómo crear una reserva específica en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma Intel Cascade Lake como la plataforma de CPU mínima. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva específica de ejemplo y consumirla, haz lo siguiente:

1. Para crear una reserva de ejemplo, completa los siguientes pasos:

   1. En la consola de Google Cloud , ve a la página Reservas.

      Ir a Reservas

      Los pasos restantes aparecen automáticamente en la consola deGoogle Cloud .

   2. En la pestaña Reserva según demanda (predeterminada), haz clic en add_box Crear reserva. Aparecerá la página Crear una reserva.

   3. En el campo Nombre, ingresa un nombre para la reserva. Por ejemplo, ingresa reservation-02.

   4. Especifica la región y la zona en las que deseas reservar los recursos. Para este ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

   5. En la sección Tipo de uso compartido, realiza una de las siguientes acciones:

      • Para crear una reserva de un solo proyecto, selecciona Local.

      • Para crear una reserva compartida, selecciona Compartido y, luego, especifica los proyectos con los que deseas compartir la reserva.

   6. En la sección Usar con instancia de VM, selecciona Seleccionar reserva específica.

   7. En el campo Cantidad de instancias de VM, ingresa 3.

   8. En la pestaña De uso general, selecciona N2.

   9. En la sección Tipo de máquina, en la pestaña Predeterminado (opción predeterminada), selecciona n2-standard-32.

   10. Expande Plataforma de CPU y GPU y, luego, en el campo Plataforma de CPU, selecciona Intel Cascade Lake o una versión posterior.

   11. Haz clic en Crear.

2. Para crear una instancia que consuma la reserva de ejemplo, completa los siguientes pasos:

   1. En la consola de Google Cloud , ve a la página Crear una instancia.

      Ir a Crear una instancia

      Aparecerá la página Crear una instancia y se mostrará el panel Configuración de la máquina.

   2. En el panel Configuración de la máquina, haz lo siguiente:

      1. En el campo Nombre, ingresa un nombre para el instancia. En este ejemplo, ingresa instance-02.

      2. Especifica la región y la zona en las que deseas reservar los recursos. Para este ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

      3. En la pestaña De uso general, selecciona N2.

      4. En la sección Tipo de máquina, en la pestaña Predeterminado (opción predeterminada), selecciona n2-standard-32.

      5. Expande la sección Opciones avanzadas y, luego, en el campo Plataforma de CPU, selecciona Intel Cascade Lake o una versión posterior.

   3. En el menú de navegación, haz clic en Opciones avanzadas. Aparecerá el panel Avanzado.

   4. En la sección Reservas, selecciona Elegir una reserva y, luego, haz clic en Elegir reserva.

   5. En el panel Elige una reserva que aparece, haz lo siguiente:

      1. Selecciona la reserva específica que creaste en los pasos anteriores. Si deseas consumir una reserva compartida que existe en otro proyecto, en la lista Proyecto, selecciona el proyecto en el que existe la reserva.

      2. Haz clic en Elegir.

   6. Haz clic en Crear.

gcloud

En el siguiente ejemplo, se muestra cómo crear una reserva específica en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma Intel Cascade Lake como la plataforma de CPU mínima. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva específica de ejemplo y consumirla, haz lo siguiente:

1. Para crear la reserva de ejemplo, usa el comando gcloud compute reservations create con la marca --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 crear una instancia que consuma la reserva de ejemplo, usa el comando gcloud compute instances create con las marcas --reservation y --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
   

   Reemplaza RESERVATION_URL por la URL de la reserva. Especifica uno de los siguientes valores:

   • Si creaste la reserva en el mismo proyecto, haz lo siguiente: reservation-02

   • Si la reserva está en otro proyecto, haz lo siguiente: projects/PROJECT_ID/reservations/reservation-02

Go

En los siguientes ejemplos, se muestra cómo crear una instancia N2 con 32 CPU virtuales y la plataforma de CPU mínima Intel Cascade Lake en la zona us-central1-a para consumir una reserva específica coincidente:

• Para crear la instancia de ejemplo y consumir una reserva específica de un solo proyecto, usa el siguiente muestra 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 crear la instancia de ejemplo y consumir una reserva compartida específica, usa el siguiente muestra 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

En los siguientes ejemplos, se muestra cómo crear una instancia N1 con cuatro CPU virtuales y la plataforma de CPU mínima Intel Skylake en la zona us-central1-a para consumir una reserva específica coincidente:

• Para crear una reserva de ejemplo como una reserva de un solo proyecto y crear una instancia para consumirla, usa el siguiente muestra 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 crear una reserva de ejemplo como reserva compartida y crear una instancia para consumirla, usa el siguiente muestra 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

En los siguientes ejemplos, se muestra cómo crear una instancia N1 con 4 CPU virtuales y la plataforma de CPU mínima Intel Skylake en la zona us-central1-a para consumir una reserva específica que coincida:

// 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

En los siguientes ejemplos, se muestra cómo crear una instancia N2 con 32 CPU virtuales y la plataforma de CPU mínima Intel Cascade Lake en la zona us-central1-a para consumir una reserva específica coincidente:

Para crear la reserva específica de ejemplo y consumirla, haz lo siguiente:

• Para crear y consumir la reserva de ejemplo como una reserva de un solo proyecto, usa el siguiente muestra 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 crear y consumir la reserva de ejemplo como una reserva compartida, usa el siguiente muestra 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

En el siguiente ejemplo, se muestra cómo crear una reserva específica en la zona us-central1-a para tres instancias N2 con 32 CPU virtuales y la plataforma Intel Cascade Lake como la plataforma de CPU mínima. También se muestra cómo crear una sola instancia para consumir la reserva.

Para crear la reserva específica de ejemplo y consumirla, haz lo siguiente:

1. Para crear la reserva de ejemplo, realiza una solicitud POST al método instances.insert. En el cuerpo de la solicitud, incluye el campo specificReservationRequired configurado 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 crear una instancia que consuma la reserva de ejemplo, realiza una solicitud POST al método instances.insert. En el cuerpo de la solicitud, en el campo reservationAffinity, incluye lo siguiente:

   • El campo consumeReservationType configurado como SPECIFIC_RESERVATION.

   • El campo key configurado como compute.googleapis.com/reservation-name.

   • El campo values configurado en la URL de la reserva.

   La solicitud es similar a la siguiente:

   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"
       ]
     }
   }
   

   Reemplaza RESERVATION_URL por la URL de la reserva. Especifica uno de los siguientes valores:

   • Si creaste la reserva en el mismo proyecto, haz lo siguiente: reservation-02

   • Si la reserva está en otro proyecto, haz lo siguiente: projects/PROJECT_ID/reservations/reservation-02

Console

1. Crea una solicitud de ejemplo para cinco instancias de A3 Ultra y envíala para su revisión:

   1. En la consola de Google Cloud , ve a la página Reservas.

      Ir a Reservas

   2. Haz clic en la pestaña Reservas futuras.

   3. Haz clic en add_boxCrear reserva futura. Aparecerá la página Crear una reserva futura.

   4. En la sección Configuración de hardware, selecciona Especificar tipo de máquina y, luego, especifica una instancia de A3 Ultra.

   5. En la sección Método de obtención, completa los siguientes pasos:

      1. Selecciona Buscar capacidad para hasta 90 días.

      2. En las listas Región y Zona, especifica la región y la zona en las que se reservarán los recursos. Para este ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

      3. En el campo Capacidad total necesaria, ingresa 5.

      4. En la sección Período de reserva, especifica el período de reserva.

   6. Especifica los campos restantes y, luego, haz clic en Enviar.

2. En la hora de inicio de la solicitud, para crear una instancia A3 Ultra que consuma la reserva de ejemplo creada automáticamente, haz lo siguiente:

   1. En la consola de Google Cloud , ve a la página Crear una instancia.

      Ir a Crear una instancia

   2. En el campo Nombre, ingresa un nombre para el instancia. En este ejemplo, ingresa example-instance.

   3. Especifica la región y la zona en las que deseas reservar los recursos. Para este ejemplo, selecciona us-central1 y us-central1-a, respectivamente.

   4. Haz clic en la pestaña GPUs y, luego, en la lista Tipo de GPU, selecciona NVIDIA H200 141 GB. Esta acción especifica una instancia A3 Ultra y establece el modelo de aprovisionamiento en Vinculado a la reserva.

   5. En el menú de navegación, haz clic en Opciones avanzadas.

   6. En la sección Reservas, selecciona Elegir una reserva y, luego, haz clic en Elegir reserva.

   7. En el panel Elige una reserva, haz lo siguiente:

      1. Selecciona una reserva específica. Si deseas consumir una reserva compartida que existe en un proyecto diferente, en la lista Proyecto, selecciona el proyecto en el que existe la reserva.

      2. Haz clic en Elegir.

   8. En la sección Modelo de aprovisionamiento, expande la sección Configuración avanzada del modelo de aprovisionamiento de VMs.

   9. En la lista Finalización de VM, selecciona Detener (predeterminado) o Borrar.

   10. Haz clic en Crear.

gcloud

1. Para crear una solicitud de ejemplo de cinco VMs A3 Ultra y enviarla para su revisión, usa el 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
   

   Supongamos que Google Cloud aprueba la solicitud y Compute Engine crea automáticamente una reserva vacía. A la hora de inicio de la solicitud, el 5 de octubre de 2025, Compute Engine aumenta la cantidad de VMs con GPU reservadas en la reserva. Luego, puedes consumir la reserva.

2. A la hora de inicio de la solicitud, para crear una instancia A3 Ultra que consuma la reserva de ejemplo creada automáticamente, usa el comando gcloud compute instances create con las siguientes marcas:

   • La marca --instance-termination-action

   • La marca --provisioning-model configurada como RESERVATION_BOUND.

   • La marca --reservation

   • La marca --reservation-affinity configurada como specific.

   El comando es similar al siguiente. Para conocer todos los requisitos para crear una instancia de A3 Ultra, consulta Crea una instancia de A3 Ultra o 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 \
       ...
   

   El comando incluye los siguientes valores:

   • TERMINATION_ACTION: Indica si Compute Engine detiene (STOP) o borra (DELETE) la VM al final del período de reserva.

   • RESERVATION_URL: Es la URL de la reserva, con el siguiente formato:

     • Si la reserva creada automáticamente existe en tu proyecto, example-reservation.

     • Si la reserva creada automáticamente existe en un proyecto diferente, usa projects/PROJECT_ID/reservations/example-reservation.

REST

1. Para crear una solicitud de ejemplo de cinco instancias de A3 Ultra y enviarla para su revisión, realiza una solicitud POST al método futureReservations.insert beta:

   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"
     }
   }
   

   Supongamos que Google Cloud aprueba la solicitud y Compute Engine crea automáticamente una reserva vacía. A la hora de inicio de la solicitud, el 5 de octubre de 2025, Compute Engine aumenta la cantidad de VMs con GPU reservadas en la reserva. Luego, puedes consumir la reserva.

2. En la hora de inicio de la solicitud, para crear una instancia de A3 Ultra que consuma la reserva de ejemplo creada automáticamente, realiza una solicitud POST al método instances.insert. En el cuerpo de la solicitud, incluye los siguientes campos:

   • El campo reservationAffinity.consumeReservationType configurado como SPECIFIC_RESERVATION.

   • El campo reservationAffinity.key configurado como compute.googleapis.com/reservation-name.

   • El campo reservationAffinity.values configurado en la URL de la reserva.

   • El campo scheduling.instanceTerminationAction

   • El campo scheduling.provisioningModel configurado como RESERVATION_BOUND.

   La solicitud es similar a la siguiente. Para conocer todos los requisitos para crear una instancia de A3 Ultra, consulta Crea una instancia de A3 Ultra o 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"
       },
       ...
     }
   }
   

   El cuerpo de la solicitud incluye los siguientes valores:

   • RESERVATION_URL: Es la URL de la reserva, con el siguiente formato:

     • Si la reserva creada automáticamente existe en tu proyecto, example-reservation.

     • Si la reserva creada automáticamente existe en un proyecto diferente, usa projects/PROJECT_ID/reservations/example-reservation.

   • TERMINATION_ACTION: Indica si Compute Engine detiene (STOP) o borra (DELETE) la VM al final del período de reserva.