Utilizzare le prenotazioni


Questo documento spiega come utilizzare Compute Engine per:

  • Utilizza istanze di macchine virtuali (VM) riservate.

  • Verifica il consumo delle prenotazioni.

  • Visualizza i report sull'utilizzo delle prenotazioni.

Per ulteriori informazioni sull'utilizzo delle prenotazioni in altri prodotti Google Cloud che utilizzano le VM, consulta la documentazione delle prenotazioni per i seguenti prodotti:

Prima di iniziare

  • Esamina i requisiti e le limitazioni per le prenotazioni.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione è la procedura mediante la quale la tua identità viene verificata per l'accesso alle API e ai servizi Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    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. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.
    3. Vai

      Per utilizzare gli Go esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

      1. Install the Google Cloud CLI.
      2. To initialize the gcloud CLI, run the following command:

        gcloud init
      3. 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.

      Per ulteriori informazioni, consulta Set up authentication for a local development environment.

      Java

      Per utilizzare gli Java esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

      1. Install the Google Cloud CLI.
      2. To initialize the gcloud CLI, run the following command:

        gcloud init
      3. 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.

      Per ulteriori informazioni, consulta Set up authentication for a local development environment.

      Node.js

      Per utilizzare gli Node.js esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

      1. Install the Google Cloud CLI.
      2. To initialize the gcloud CLI, run the following command:

        gcloud init
      3. 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.

      Per ulteriori informazioni, consulta Set up authentication for a local development environment.

      Python

      Per utilizzare gli Python esempi in questa pagina in un ambiente di sviluppo locale, installa e inizializza l'interfaccia alla gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

      1. Install the Google Cloud CLI.
      2. To initialize the gcloud CLI, run the following command:

        gcloud init
      3. 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.

      Per ulteriori informazioni, consulta Set up authentication for a local development environment.

      REST

      Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

        Install the Google Cloud CLI, then initialize it by running the following command:

        gcloud init

      Per ulteriori informazioni, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare le prenotazioni, chiedi all'amministratore di concederti il ruolo IAM Amministratore istanze Compute (v1) (roles/compute.instanceAdmin.v1) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per utilizzare le prenotazioni. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per utilizzare le prenotazioni sono necessarie le seguenti autorizzazioni:

  • Per creare le prenotazioni: compute.reservations.create nel progetto
  • Per creare le VM:
    • compute.instances.create sul progetto
    • Per utilizzare un'immagine personalizzata per creare la VM: compute.images.useReadOnly sull'immagine
    • Per utilizzare uno snapshot per creare la VM: compute.snapshots.useReadOnly nello snapshot
    • Per utilizzare un modello di istanza per creare la VM: compute.instanceTemplates.useReadOnly nel modello di istanza
    • Per assegnare una rete legacy alla VM: compute.networks.use nel progetto
    • Per specificare un indirizzo IP statico per la VM: compute.addresses.use nel progetto
    • Per assegnare un indirizzo IP esterno alla VM quando nel progetto viene utilizzata una rete precedente: compute.networks.useExternalIp
    • Per specificare una subnet per la VM: compute.subnetworks.use nel progetto o nella subnet scelta
    • Per assegnare un indirizzo IP esterno alla VM quando utilizzi una rete VPC: compute.subnetworks.useExternalIp nel progetto o nella subnet scelta
    • Per impostare i metadati dell'istanza VM per la VM: compute.instances.setMetadata nel progetto
    • Per impostare i tag per la VM: compute.instances.setTags sulla VM
    • Per impostare le etichette per la VM: compute.instances.setLabels sulla VM
    • Per impostare un account di servizio per consentire alla VM di utilizzare: compute.instances.setServiceAccount sulla VM
    • Per creare un nuovo disco per la VM: compute.disks.create nel progetto
    • Per collegare un disco esistente in modalità di sola lettura o di lettura e scrittura: compute.disks.use sul disco
    • Per collegare un disco esistente in modalità di sola lettura: compute.disks.useReadOnly sul disco
  • Per creare modelli di istanze: compute.instanceTemplates.create sul progetto

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Utilizzare VM riservate

Quando crei un'istanza di una macchina virtuale (VM), la VM inizia a utilizzare una prenotazione solo se le proprietà della VM e della prenotazione sono corrispondenti. Inoltre, devi impostare la proprietà di affinità di prenotazione della VM su una delle seguenti opzioni:

  • Utilizza qualsiasi prenotazione corrispondente: la VM può utilizzare automaticamente qualsiasi prenotazione con proprietà corrispondenti (valore predefinito).

    Questa opzione è utile se crei ed elimini molte VM e vuoi utilizzare le prenotazioni ogni volta che è possibile. In questo scenario, è possibile creare una VM anche se le sue proprietà non corrispondono a una prenotazione. Se corrispondono, la VM inizia a utilizzare la prenotazione in base all'ordine di consumo della prenotazione.

  • Utilizza una prenotazione specifica: la VM può utilizzare solo una prenotazione specifica. La prenotazione non può essere consumata automaticamente.

    Questa opzione è utile quando, ad esempio, vuoi mantenere una certa quantità di capacità come backup per eventi speciali. In questo scenario, è possibile creare una VM solo se le sue proprietà corrispondono a quelle della prenotazione specifica.

  • Non può consumare alcuna prenotazione: la VM non può consumare alcuna prenotazione.

    Questa opzione è utile, ad esempio, quando crei una VM temporanea di cui non vuoi consumare le risorse riservate.

Utilizza le VM di qualsiasi prenotazione corrispondente

In questo modello di consumo, le VM esistenti e nuove consumano automaticamente una prenotazione se le relative proprietà corrispondono a quelle specificate nella prenotazione.

Quando utilizzi questo modello di consumo, le VM nel progetto corrente consumano prima tutte le prenotazioni per un singolo progetto prima di consumare le prenotazioni condivise. Per maggiori informazioni su come vengono consumate automaticamente le prenotazioni, consulta Ordine di consumo.

Quando crei una prenotazione, questo è il modello di consumo predefinito, a condizione che non utilizzi il flag o l'opzione che indica che sono obbligatorie prenotazioni specifiche.

Console

  1. Per creare una prenotazione con risorse che possono essere utilizzate dalle VM con una proprietà di affinità di prenotazione configurata per utilizzare eventuali prenotazioni (valore predefinito):

    1. Seleziona il tipo di prenotazione che vuoi creare:

      • Per creare una prenotazione autonoma:

        1. Nella console Google Cloud, vai alla pagina Prenotazioni.

          Vai a Prenotazioni

        2. Nella scheda Prenotazione on demand (predefinita), fai clic su Crea prenotazione.

          Viene visualizzata la pagina Crea una prenotazione.

      • Per creare una prenotazione collegata a un impegno:

        1. Nella console Google Cloud, vai alla pagina Sconti per utilizzo a livello di impegno.

          Vai a Sconti per impegno di utilizzo

          Viene visualizzata la pagina Elenco impegni.

        2. Fai clic su Impegno di acquisto.

          Viene visualizzata la pagina Acquista uno sconto per impegno di utilizzo.

        3. Specifica le proprietà di impegno. Poi, nella sezione Prenotazioni, fai clic su Aggiungi un articolo.

          Viene visualizzata la sezione Aggiungi una nuova prenotazione.

          Per saperne di più su come acquistare un impegno con una prenotazione allegata, consulta la pagina Acquistare impegni con prenotazioni allegate.

    2. Nel campo Nome, inserisci un nome per la prenotazione. Per questo esempio, inserisci reservation-01.

    3. Scegli la Regione e la Zona in cui vuoi prenotare le risorse. Per questo esempio, seleziona us-central1 come regione e us-central1-a come zona.

    4. Scegli il tipo di condivisione che preferisci:

      • Per creare una prenotazione per un singolo progetto, seleziona Locale.
      • Per creare una prenotazione condivisa tra più progetti, seleziona Condivisa. Per condividere questa prenotazione con altri progetti, fai clic su Aggiungi progetti e seleziona i progetti che ti interessano dall'organizzazione del progetto corrente.
    5. Nella sezione Utilizza con l'istanza VM, seleziona Utilizza automaticamente la prenotazione in modo che tutte le VM corrispondenti possano utilizzare automaticamente questa prenotazione.

    6. Nel campo Numero di istanze VM, inserisci il numero di VM che vuoi prenotare. Per questo esempio, inserisci 2.

    7. Specifica le risorse che vuoi prenotare per ogni VM:

      • Se vuoi prenotare VM corrispondenti a un modello di istanza esistente, seleziona Utilizza modello di istanza e un modello di istanza dall'elenco.
      • In caso contrario, seleziona Specifica il tipo di macchina e specifica quanto segue:
        1. Nei campi Famiglia di macchine, Serie e Tipo di macchina, seleziona una famiglia, una serie e un tipo di macchina.
        2. (Facoltativo) Specifica una piattaforma CPU e/o GPU minima:
          1. Per espandere la sezione Piattaforma CPU e GPU, fai clic sulla Freccia di espansione .
          2. (Facoltativo) Per specificare una piattaforma CPU minima, seleziona un'opzione nell'elenco Piattaforma CPU.
          3. (Facoltativo) Per aggiungere GPU, fai clic su Aggiungi GPU. Poi, nei campi Tipo di GPU e Numero di GPU, seleziona il tipo e il numero di GPU per ogni VM.
        3. (Facoltativo) Aggiungi SSD locali:
          1. Nel campo Numero di dischi, seleziona il numero di SSD locali per ogni VM.
          2. Nel campo Tipo di interfaccia, seleziona l'interfaccia per le unità SSD locali.

      Per questo esempio, seleziona Specifica il tipo di macchina. Quindi, seleziona il tipo di macchina n2-standard-32 per la famiglia di macchine General-purpose e la serie N2 e seleziona la piattaforma CPU minima Intel Cascade Lake.

    8. Completa la creazione della prenotazione:

      • Se stai creando una prenotazione autonoma, fai clic su Crea.

      • Se stai creando una prenotazione collegata a un impegno:

        1. Per completare la specifica delle proprietà per questa prenotazione, fai clic su Fine.
        2. Per completare la creazione dell'impegno e delle prenotazioni allegate, fai clic su Acquista.
  2. Nello stesso progetto o in un progetto con cui la prenotazione è condivisa, crea una VM che abbia come target qualsiasi prenotazione aperta.

    Assicurati che le proprietà della VM corrispondano a quelle della VM in reservation-01, incluse la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU e l'interfaccia e le dimensioni dell'SSD locale.

    Per ulteriori informazioni su come creare una VM, consulta Creare e avviare una VM

    1. Nella console Google Cloud, vai alla pagina Crea un'istanza.

      Vai a Crea un'istanza

      Viene visualizzata la pagina Crea un'istanza.

    2. Specifica un nome per la VM.

    3. Nelle sezioni seguenti, seleziona una configurazione che corrisponde esattamente a tutte le proprietà della prenotazione, incluse quelle facoltative. Per questo esempio, devi associare le seguenti proprietà VM a reservation-01:

      • Regione: us-central1
      • Zona: us-central1-a
      • Tipo di macchina: n2-standard-32
      • Piattaforma CPU minima: Intel Cascade Lake
      • GPU: nessuna
      • SSD locali: nessuna
    4. Espandi la sezione Opzioni avanzate e poi la sezione Gestione. Nell'elenco Prenotazioni, seleziona Usa automaticamente la prenotazione creata.

    5. Per creare la VM, fai clic su Crea.

gcloud

  1. Crea una prenotazione aperta denominata reservation-01.

    gcloud compute reservations create reservation-01 \
        --vm-count=2 \
        --machine-type=n2-standard-32 \
        --min-cpu-platform="Intel Cascade Lake" \
        --zone=us-central1-a
    
  2. Crea una VM che abbia come target qualsiasi prenotazione aperta e che corrisponda alle proprietà della VM in reservation-01, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU e la quantità e l'interfaccia dell'SSD locale.

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

Vai

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

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

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

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

  1. Crea una prenotazione aperta denominata reservation-01.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations
    
    {
      "name": "reservation-01",
      "specificReservation": {
        "count": "2",
        "instanceProperties": {
          "machineType": "n2-standard-32",
          "minCpuPlatform": "Intel Cascade Lake",
        }
      }
    }
    
  2. Crea una VM che abbia come target qualsiasi prenotazione aperta e che corrisponda alle proprietà della VM in reservation-01, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU e la quantità e l'interfaccia dell'SSD locale.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances
    
    {
      "name": "instance-1",
      "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"
      }
    }
    

Utilizzare le VM da una prenotazione specifica

In questo modello di consumo, solo le nuove VM che hanno come target una prenotazione specifica per nome possono utilizzarla e la prenotazione non viene consumata automaticamente.

Quando crei la prenotazione, specifica che le VM devono avere come target la prenotazione specifica utilizzando uno dei seguenti metodi:

  • Nella console Google Cloud, seleziona la casella di controllo Seleziona una prenotazione specifica.
  • Nell'interfaccia alla gcloud CLI, includi il --require-specific-reservation flag.
  • Nell'API Compute Engine, imposta il campo specificReservationRequired su true.
  • In Terraform, imposta il campo specific_reservation_required su true.

Quindi, crea VM che hanno come target specifico la prenotazione. Puoi creare una VM che abbia come target una prenotazione specifica solo se le proprietà della VM e quelle della prenotazione corrispondono. In caso contrario, la creazione della VM non va a buon fine.

Se utilizzi un modello di istanza per creare VM in un gruppo di istanze gestite regionale, crea prenotazioni identiche con lo stesso nome in ogni zona applicabile. Quindi, scegli come target le prenotazioni per nome nel modello di istanza del gruppo.

Ad esempio, crea una prenotazione specifica denominata reservation-02 e poi una VM corrispondente che abbia come target la prenotazione e che corrisponda alle proprietà VM della prenotazione.

A seconda del tipo di VM che vuoi utilizzare, segui i passaggi per utilizzare una prenotazione per un singolo progetto specifico o utilizzare una prenotazione condivisa specifica.

Utilizzare una prenotazione specifica per un singolo progetto

Per utilizzare una prenotazione per un singolo progetto specifico, seleziona una delle seguenti opzioni:

Console

  1. Per creare una prenotazione con risorse che possono essere utilizzate solo dalle VM che scelgono come target specifico la prenotazione per nome:

    1. Seleziona una delle seguenti opzioni:

      • Per creare una prenotazione autonoma:

        1. Nella console Google Cloud, vai alla pagina Prenotazioni.

          Vai a Prenotazioni

        2. Nella scheda Prenotazioni on demand (predefinita), fai clic su Crea prenotazione.

          Viene visualizzata la pagina Crea una prenotazione.

      • Per creare una prenotazione collegata a un impegno:

        1. Nella console Google Cloud, vai alla pagina Sconti per utilizzo a livello di impegno.

          Vai a Sconti per impegno di utilizzo

        2. Fai clic su Impegno di acquisto.

          Viene visualizzata la pagina Acquista uno sconto per impegno di utilizzo.

        3. Specifica le proprietà di impegno. Poi, nella sezione Prenotazioni, fai clic su Aggiungi un articolo.

          Viene visualizzata la sezione Aggiungi una nuova prenotazione.

          Per saperne di più su come acquistare un impegno con una prenotazione allegata, consulta la pagina Acquistare impegni con prenotazioni allegate.

    2. Nel campo Nome, inserisci un nome per la prenotazione. Per questo esempio, inserisci reservation-02.

    3. Scegli la Regione e la Zona in cui vuoi prenotare le risorse. Per questo esempio, seleziona us-central1 come regione e us-central1-a come zona.

    4. Per specificare che la prenotazione sarà per un singolo progetto, seleziona Locale come Tipo di condivisione.

    5. Nella sezione Utilizza con l'istanza VM, seleziona Seleziona prenotazione specifica in modo che solo le VM corrispondenti che hanno come target specifico questa prenotazione per nome possano utilizzarla.

    6. Nel campo Numero di istanze VM, inserisci il numero di VM che vuoi prenotare. Per questo esempio, inserisci 10.

    7. Specifica le risorse che vuoi prenotare per ogni VM:

      • Se vuoi prenotare VM corrispondenti a un modello di istanza esistente, seleziona Utilizza modello di istanza e un modello di istanza dall'elenco.
      • In caso contrario, seleziona Specifica il tipo di macchina e specifica quanto segue:
        1. Nei campi Famiglia di macchine, Serie e Tipo di macchina, seleziona una famiglia, una serie e un tipo di macchina.
        2. (Facoltativo) Specifica una piattaforma CPU e/o GPU minima:
          1. Per espandere la sezione Piattaforma CPU e GPU, fai clic sulla Freccia di espansione .
          2. (Facoltativo) Per specificare una piattaforma CPU minima, seleziona un'opzione nell'elenco Piattaforma CPU.
          3. (Facoltativo) Per aggiungere GPU, fai clic su Aggiungi GPU. Poi, nei campi Tipo di GPU e Numero di GPU, seleziona il tipo e il numero di GPU per ogni VM.
        3. (Facoltativo) Aggiungi SSD locali:
          1. Nel campo Numero di dischi, seleziona il numero di SSD locali per ogni VM.
          2. Nel campo Tipo di interfaccia, seleziona l'interfaccia per le unità SSD locali.

      Per questo esempio, seleziona Specifica il tipo di macchina. Quindi, seleziona il tipo di macchina n2-standard-32 per la famiglia di macchine General-purpose e la serie N2 e seleziona la piattaforma CPU minima Intel Cascade Lake.

    8. Completa la creazione della prenotazione:

      • Se stai creando una prenotazione autonoma, fai clic su Crea.

      • Se stai creando una prenotazione collegata a un impegno:

        1. Per completare la specifica delle proprietà per questa prenotazione, fai clic su Fine.
        2. Per completare la creazione dell'impegno e delle prenotazioni allegate, fai clic su Acquista.
  2. Nello stesso progetto, crea una VM che abbia come target la prenotazione specifica per nome.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione specifica, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU e le dimensioni e l'interfaccia dell'SSD locale.

    Per ulteriori informazioni su come creare una VM, consulta Creare e avviare una VM.

    1. Nella console Google Cloud, vai alla pagina Crea un'istanza.

      Vai a Crea un'istanza

    2. Nel campo Nome, inserisci un nome per la VM.

    3. Nelle sezioni seguenti, seleziona una configurazione che corrisponde esattamente a tutte le proprietà della prenotazione, incluse quelle facoltative. Per questo esempio, devi associare le seguenti proprietà VM a reservation-02:

      • Regione: us-central1
      • Zona: us-central1-a
      • Tipo di macchina: n2-standard-32
      • Piattaforma CPU minima: Intel Cascade Lake
      • GPU: nessuna
      • SSD locali: nessuna
    4. Espandi la sezione Opzioni avanzate e segui questi passaggi:

      1. Espandi la sezione Gestione.

      2. Nella sezione Prenotazioni, nell'elenco Criteri di applicazione, seleziona Seleziona una prenotazione specifica.

      3. Seleziona la prenotazione con le proprietà VM corrispondenti che vuoi che la tua VM utilizzi. Per questo esempio, seleziona reservation-02.

    5. Per creare la VM, fai clic su Crea.

gcloud

  1. Crea una prenotazione denominata reservation-02 con il --require-specific-reservation flag. Queste risorse riservate possono essere utilizzate solo dalle VM che hanno come target specifico questa prenotazione per nome.

    gcloud compute reservations create reservation-02 \
        --machine-type=n2-standard-32 \
        --min-cpu-platform="Intel Cascade Lake" \
        --vm-count=10 \
        --zone=us-central1-a \
        --require-specific-reservation
    
  2. Crea una VM che abbia come target reservation-02 per nome utilizzando i flag --reservation-affinity e --reservation.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU, nonché l'interfaccia e le dimensioni dell'SSD locale.

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

Vai

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
}

Java

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);
    }
  }
}

Node.js

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

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)

REST

  1. Crea una prenotazione denominata reservation-02 con il specificReservationRequired impostato su true.

    POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations
    
    {
      "name":"reservation-02",
      "specificReservation":{
        "count":"10",
        "instanceProperties":{
          "machineType":"n2-standard-32",
          "minCpuPlatform": "Intel Cascade Lake",
        }
      },
      "specificReservationRequired": true
    }
    
  2. Crea una VM che abbia come target reservation-02 per nome utilizzando il campo reservationAffinity.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU, nonché l'interfaccia e le dimensioni dell'SSD locale.

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

Utilizzare una prenotazione condivisa specifica

Per utilizzare una prenotazione condivisa specifica, seleziona una delle seguenti opzioni:

Console

  1. Per creare una prenotazione condivisa con risorse che possono essere utilizzate solo dalle VM che hanno come target specifico questa prenotazione per nome, segui questi passaggi:

    1. Seleziona una delle seguenti opzioni:

      • Per creare una prenotazione autonoma:

        1. Nella console Google Cloud, vai alla pagina Prenotazioni.

          Vai a Prenotazioni

        2. Nella scheda Prenotazioni on demand (predefinita), fai clic su Crea prenotazione.

          Viene visualizzata la pagina Crea una prenotazione.

      • Per creare una prenotazione collegata a un impegno:

        1. Nella console Google Cloud, vai alla pagina Sconti per utilizzo a livello di impegno.

          Vai a Sconti per impegno di utilizzo

        2. Fai clic su Impegno di acquisto.

          Viene visualizzata la pagina Acquista uno sconto per impegno di utilizzo.

        3. Specifica le proprietà di impegno. Poi, nella sezione Prenotazioni, fai clic su Aggiungi un articolo.

          Viene visualizzata la sezione Aggiungi una nuova prenotazione.

          Per saperne di più su come acquistare un impegno con una prenotazione allegata, consulta la pagina Acquistare impegni con prenotazioni allegate.

    2. Nel campo Nome, inserisci un nome per la prenotazione. Per questo esempio, inserisci reservation-02.

    3. Scegli la Regione e la Zona in cui vuoi prenotare le risorse. Per questo esempio, seleziona us-central1 come regione e us-central1-a come zona.

    4. Per specificare che la prenotazione è condivisa, seleziona Condivisa come Tipo di condivisione.

    5. Fai clic su Aggiungi progetti e seleziona i progetti dell'organizzazione del progetto corrente con cui vuoi condividere la prenotazione.

    6. Nella sezione Utilizza con l'istanza VM, seleziona Seleziona prenotazione specifica in modo che solo le VM corrispondenti che hanno come target specifico questa prenotazione per nome possano utilizzarla.

    7. Nel campo Numero di istanze VM, inserisci il numero di VM che vuoi prenotare. Per questo esempio, inserisci 10.

    8. Specifica le risorse che vuoi prenotare per ogni VM:

      • Se vuoi prenotare VM corrispondenti a un modello di istanza esistente, seleziona Utilizza modello di istanza e un modello di istanza dall'elenco.
      • In caso contrario, seleziona Specifica il tipo di macchina e specifica quanto segue:
        1. Nei campi Famiglia di macchine, Serie e Tipo di macchina, seleziona una famiglia, una serie e un tipo di macchina.
        2. (Facoltativo) Specifica una piattaforma CPU e/o GPU minima:
          1. Per espandere la sezione Piattaforma CPU e GPU, fai clic sulla Freccia di espansione .
          2. (Facoltativo) Per specificare una piattaforma CPU minima, seleziona un'opzione nell'elenco Piattaforma CPU.
          3. (Facoltativo) Per aggiungere GPU, fai clic su Aggiungi GPU. Poi, nei campi Tipo di GPU e Numero di GPU, seleziona il tipo e il numero di GPU per ogni VM.
        3. (Facoltativo) Aggiungi SSD locali:
          1. Nel campo Numero di dischi, seleziona il numero di SSD locali per ogni VM.
          2. Nel campo Tipo di interfaccia, seleziona l'interfaccia per le unità SSD locali.

      Per questo esempio, seleziona Specifica il tipo di macchina. Quindi, seleziona il tipo di macchina n2-standard-32 per la famiglia di macchine General-purpose e la serie N2 e seleziona la piattaforma CPU minima Intel Cascade Lake. 1. Completa la creazione della prenotazione:

      • Se stai creando una prenotazione autonoma, fai clic su Crea.

      • Se stai creando una prenotazione collegata a un impegno:

        1. Per completare la specifica delle proprietà per questa prenotazione, fai clic su Fine.
        2. Per completare la creazione dell'impegno e delle prenotazioni allegate, fai clic su Acquista.
  2. Nello stesso progetto o in un progetto con cui la prenotazione è condivisa, crea una VM che abbia come target la prenotazione specifica per nome.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione specifica, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU e le dimensioni e l'interfaccia dell'SSD locale.

    1. Nella console Google Cloud, vai alla pagina Crea un'istanza.

      Vai a Crea un'istanza

      Viene visualizzata la pagina Crea un'istanza.

    2. Specifica un nome per la VM.

    3. Nelle sezioni seguenti, seleziona una configurazione che corrisponde esattamente a tutte le proprietà della prenotazione, incluse quelle facoltative. Per questo esempio, devi associare le seguenti proprietà VM a reservation-02:

      • Regione: us-central1
      • Zona: us-central1-a
      • Tipo di macchina: n2-standard-32
      • Piattaforma CPU minima: Intel Cascade Lake
      • GPU: nessuna
      • SSD locali: nessuna
    4. Espandi la sezione Opzioni avanzate e poi la sezione Gestione. Nell'elenco Prenotazioni, seleziona Seleziona una prenotazione specifica e poi procedi nel seguente modo:

      1. Seleziona un progetto di prenotazione con prenotazioni condivise con il tuo progetto attuale. Per questo esempio, seleziona il progetto utilizzato per creare reservation-02.
      2. Seleziona il nome della prenotazione della prenotazione condivisa che vuoi che venga utilizzata da questa VM. Per questo esempio, seleziona reservation-02.
    5. Per creare la VM, fai clic su Crea.

gcloud

  1. Crea una prenotazione denominata reservation-02 con il --require-specific-reservation flag. Queste risorse riservate possono essere utilizzate solo dalle VM che hanno come target specifico questa prenotazione per nome.

    gcloud compute reservations create reservation-02 \
        --machine-type=n2-standard-32 \
        --min-cpu-platform="Intel Cascade Lake" \
        --vm-count=10 \
        --zone=us-central1-a \
        --project=my-owner-project \
        --share-setting=projects \
        --share-with=project-1,project-2 \
        --require-specific-reservation
    
  2. Crea una VM che abbia come target reservation-02 per nome utilizzando i flag --reservation-affinity e --reservation. Per utilizzare questa prenotazione da qualsiasi progetto consumer con cui è condivisa, devi specificare anche il progetto che ha creato la prenotazione, my-owner-project.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU, nonché l'interfaccia e le dimensioni dell'SSD locale.

    gcloud compute instances create instance-2 \
        --machine-type=n2-standard-32 \
        --min-cpu-platform="Intel Cascade Lake" \
        --zone=us-central1-a \
        --reservation-affinity=specific \
        --reservation=projects/my-owner-project/reservations/reservation-02
    

Vai

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

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);
    }
  }
}

Python

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

  1. Crea una prenotazione denominata reservation-02 con il specificReservationRequired impostato su true.

    POST https://compute.googleapis.com/compute/v1/projects/my-owner-project/zones/us-central1-a/reservations
    
    {
      "name":"reservation-02",
      "specificReservation":{
        "count":"10",
        "instanceProperties":{
          "machineType":"n2-standard-32",
          "minCpuPlatform": "Intel Cascade Lake"
        }
      },
      "shareSettings": {
        "shareType": "SPECIFIC_PROJECTS",
        "projectMap": {
          "project-1": {
            "projectId": "project-1"
          },
          "project-2": {
            "projectId": "project-2"
          }
        }
      },
      "specificReservationRequired": true
    }
    
  2. Crea una VM che abbia come target reservation-02 per nome utilizzando il campo reservationAffinity. Per utilizzare questa prenotazione da qualsiasi progetto consumer con cui è condivisa, devi anche specificare il progetto proprietario della prenotazione, my-owner-project.

    Assicurati che le proprietà della VM corrispondano a quelle della prenotazione, tra cui la zona, il tipo di macchina (famiglia di macchine, vCPU e memoria), la piattaforma CPU minima, la quantità e il tipo di GPU, nonché l'interfaccia e le dimensioni dell'SSD locale.

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

Creare VM senza utilizzare le prenotazioni

Se crei una prenotazione consumata automaticamente, tutte le VM in esecuzione con proprietà corrispondenti nel tuo progetto possono utilizzarla. Per impedire a una o più VM di utilizzare la prenotazione, procedi nel seguente modo:

  • Imposta la proprietà di affinità di prenotazione delle VM in modo che non consumi esplicitamente alcuna prenotazione come descritto in questa sezione.

  • Assicurati che le VM non corrispondano alle proprietà VM della prenotazione.

Per creare VM che non consumano esplicitamente le prenotazioni, seleziona uno dei seguenti metodi:

Crea una VM per non consumare prenotazioni

Per creare una VM che non utilizza esplicitamente le prenotazioni, seleziona una delle seguenti opzioni:

Console

  1. Nella console Google Cloud, vai alla pagina Crea un'istanza.

    Vai a Crea un'istanza

  2. Nel campo Nome, inserisci un nome per la VM.

  3. Negli elenchi Regione e Zona, seleziona la regione e la zona in cui creare la VM.

  4. Nella sezione Configurazione macchina, specifica il tipo di macchina da utilizzare per la VM.

  5. Espandi la sezione Opzioni avanzate e segui questi passaggi:

    1. Espandi la sezione Gestione.

    2. Nella sezione Prenotazioni, nell'elenco Norme relative alle applicazioni, seleziona Non utilizzare.

  6. Fai clic su Crea.

gcloud

Per creare una VM che non consuma esplicitamente le prenotazioni, utilizza il comando gcloud compute instances create con il flag --reservation-affinity=none.

gcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --reservation-affinity=none \
    --zone=ZONE

Sostituisci quanto segue:

  • VM_NAME: il nome della VM.

  • MACHINE_TYPE: il tipo di macchina da utilizzare per la VM.

  • ZONE: la zona in cui creare la VM.

Vai

import (
	"context"
	"fmt"
	"io"

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

// createInstanceNotConsumeReservation creates VM, without consuming reservation
func createInstanceNotConsumeReservation(w io.Writer, projectID, zone, instanceName string) error {
	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"),
				},
			},
			ReservationAffinity: &computepb.ReservationAffinity{
				ConsumeReservationType: proto.String("NO_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\n")

	return nil
}

Java

import static com.google.cloud.compute.v1.ReservationAffinity.ConsumeReservationType.NO_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 CreateInstanceWithoutConsumingReservation {
  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 you want to use.
    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.
    // *   This value uses the format zones/{zone}/machineTypes/{type_name}.
    // *   For a list of machine types, see https://cloud.google.com/compute/docs/machine-types
    String machineTypeName = "n1-standard-1";
    // 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";

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

  // Create a virtual machine that explicitly doesn't consume reservations
  public static Instance createInstanceWithoutConsumingReservationAsync(
      String project, String zone, String instanceName,
      String machineTypeName, String sourceImage, long diskSizeGb, String networkName)
      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(NO_RESERVATION.toString())
              .build();

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

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

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

      // Wait for the operation to complete.
      Operation response = operation.get(3, TimeUnit.MINUTES);

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

Node.js

// 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 a VM that explicitly doesn't consume reservations
async function callCreateInstanceToNotConsumeReservation() {
  // 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: 'NO_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 callCreateInstanceToNotConsumeReservation();

Python

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 create_vm_not_consume_reservation(
    project_id: str, zone: str, instance_name: str, machine_type: str = "n2-standard-2"
) -> compute_v1.Instance:
    """Creates a VM that explicitly doesn't consume reservations
    Args:
        project_id (str): The ID of the Google Cloud project.
        zone (str): The zone where the VM will be created.
        instance_name (str): The name of the instance to create.
        machine_type (str, optional): The machine type for the instance.
    Returns:
        compute_v1.Instance: The created instance.
    """
    instance = compute_v1.Instance()
    instance.name = instance_name
    instance.machine_type = f"zones/{zone}/machineTypes/{machine_type}"
    instance.zone = zone

    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
                )
            ],
        )
    ]

    # Set the reservation affinity to not consume any reservation
    instance.reservation_affinity = compute_v1.ReservationAffinity(
        consume_reservation_type="NO_RESERVATION",  # Prevents the instance from consuming reservations
    )

    # 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"Creating the {instance_name} instance in {zone}...")

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

REST

Per creare una VM che non consuma prenotazioni in modo esplicito, invia una richiesta POST al metodo instances.insert. Nel corpo della richiesta, includi il campo consumeReservationType impostato su NO_RESERVATION.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "VM_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "reservationAffinity": {
    "consumeReservationType": "NO_RESERVATION"
  }
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto in cui creare la VM.

  • ZONE: la zona in cui creare la VM.

  • VM_NAME: il nome della VM.

  • MACHINE_TYPE: il tipo di macchina da utilizzare per la VM.

  • IMAGE_PROJECT: il progetto immagine che contiene l'immagine del sistema operativo, ad esempio debian-cloud. Per saperne di più sui progetti di immagini supportati, consulta Immagini pubbliche.

  • IMAGE: specifica una delle seguenti opzioni:

    • Una versione specifica dell'immagine del sistema operativo, ad esempio debian-12-bookworm-v20240617.

    • Una famiglia di immagini, che deve essere formattata come family/IMAGE_FAMILY. Specifica l'immagine del sistema operativo più recente e non ritirata. Ad esempio, se specifichi family/debian-12, viene utilizzata la versione più recente della famiglia di immagini Debian 12. Per saperne di più sull'utilizzo delle famiglie di immagini, consulta le best practice per le famiglie di immagini.

Per ulteriori informazioni sulla creazione di una VM, consulta Creare e avviare un'istanza Compute Engine.

Crea un modello di istanza per non consumare prenotazioni

Per creare un modello di istanza che crei VM che non consumano esplicitamente le prenotazioni, seleziona una delle seguenti opzioni:

Console

  1. Nella console Google Cloud, vai alla pagina Crea un modello di istanza.

    Vai a Crea un modello di istanza

  2. Nel campo Nome, inserisci un nome per il modello di istanza.

  3. Nella sezione Località, specifica se vuoi creare un modello di istanza regionale (predefinito) o globale.

  4. Nella sezione Configurazione macchina, specifica il tipo di macchina da utilizzare per le VM create utilizzando il modello.

  5. Espandi la sezione Opzioni avanzate e segui questi passaggi:

    1. Espandi la sezione Gestione.

    2. Nella sezione Prenotazioni, nell'elenco Norme relative alle applicazioni, seleziona Non utilizzare.

  6. Fai clic su Crea.

gcloud

Per creare un modello di istanza che crei VM che non consumano esplicitamente le prenotazioni, utilizza il comando gcloud compute instances-templates create con il flag --reservation-affinity=none.

Ad esempio, per creare un modello di istanza globale che crei VM che non consumano esplicitamente le prenotazioni, esegui il seguente comando:

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=MACHINE_TYPE \
    --reservation-affinity=none

Sostituisci quanto segue:

  • INSTANCE_TEMPLATE_NAME: il nome del modello di istanza.

  • MACHINE_TYPE: il tipo di macchina da utilizzare per le VM create utilizzando il modello di istanza.

Vai

import (
	"context"
	"fmt"
	"io"

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

// createInstanceNotConsumeReservation creates a new instance template, which won't consume reservations
func createTemplateNotConsumeReservation(w io.Writer, projectID, templateName string) error {
	// projectID := "your_project_id"
	// templateName := "your_template_name"

	ctx := context.Background()
	instanceTemplatesClient, err := compute.NewInstanceTemplatesRESTClient(ctx)
	if err != nil {
		return fmt.Errorf("NewInstanceTemplatesRESTClient: %w", err)
	}
	defer instanceTemplatesClient.Close()

	req := &computepb.InsertInstanceTemplateRequest{
		Project: projectID,
		InstanceTemplateResource: &computepb.InstanceTemplate{
			Name: proto.String(templateName),
			Properties: &computepb.InstanceProperties{
				// The template describes the size and source image of the boot disk
				// to attach to the instance.
				Disks: []*computepb.AttachedDisk{
					{
						InitializeParams: &computepb.AttachedDiskInitializeParams{
							DiskSizeGb:  proto.Int64(250),
							SourceImage: proto.String("projects/debian-cloud/global/images/family/debian-11"),
						},
						AutoDelete: proto.Bool(true),
						Boot:       proto.Bool(true),
					},
				},
				MachineType: proto.String("e2-standard-4"),
				// The template connects the instance to the `default` network,
				// without specifying a subnetwork.
				NetworkInterfaces: []*computepb.NetworkInterface{
					{
						Name: proto.String("global/networks/default"),
						// The template lets the instance use an external IP address.
						AccessConfigs: []*computepb.AccessConfig{
							{
								Name:        proto.String("External NAT"),
								Type:        proto.String(computepb.AccessConfig_ONE_TO_ONE_NAT.String()),
								NetworkTier: proto.String(computepb.AccessConfig_PREMIUM.String()),
							},
						},
					},
				},
				ReservationAffinity: &computepb.ReservationAffinity{
					ConsumeReservationType: proto.String("NO_RESERVATION"),
				},
			},
		},
	}

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

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

	fmt.Fprintf(w, "Instance template created\n")

	return nil
}

Java

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

import com.google.cloud.compute.v1.AccessConfig;
import com.google.cloud.compute.v1.AttachedDisk;
import com.google.cloud.compute.v1.AttachedDiskInitializeParams;
import com.google.cloud.compute.v1.InsertInstanceTemplateRequest;
import com.google.cloud.compute.v1.InstanceProperties;
import com.google.cloud.compute.v1.InstanceTemplate;
import com.google.cloud.compute.v1.InstanceTemplatesClient;
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 CreateTemplateWithoutConsumingReservation {
  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 template you want to query.
    String templateName = "YOUR_INSTANCE_TEMPLATE_NAME";
    String machineType = "e2-standard-4";
    String sourceImage = "projects/debian-cloud/global/images/family/debian-11";

    createTemplateWithoutConsumingReservationAsync(
        projectId, templateName, machineType, sourceImage);
  }


  // Create a template that explicitly doesn't consume any reservations.
  public static InstanceTemplate createTemplateWithoutConsumingReservationAsync(
      String projectId, String templateName, String machineType, String sourceImage)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // 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 (InstanceTemplatesClient instanceTemplatesClient = InstanceTemplatesClient.create()) {
      AttachedDisk attachedDisk = AttachedDisk.newBuilder()
          .setInitializeParams(AttachedDiskInitializeParams.newBuilder()
              .setSourceImage(sourceImage)
              .setDiskType("pd-balanced")
              .setDiskSizeGb(250)
              .build())
          .setAutoDelete(true)
          .setBoot(true)
          .build();

      NetworkInterface networkInterface = NetworkInterface.newBuilder()
          .setName("global/networks/default")
          .addAccessConfigs(AccessConfig.newBuilder()
              .setName("External NAT")
              .setType(AccessConfig.Type.ONE_TO_ONE_NAT.toString())
              .setNetworkTier(AccessConfig.NetworkTier.PREMIUM.toString())
              .build())
          .build();

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

      InstanceProperties instanceProperties = InstanceProperties.newBuilder()
          .addDisks(attachedDisk)
          .setMachineType(machineType)
          .setReservationAffinity(reservationAffinity)
          .addNetworkInterfaces(networkInterface)
          .build();

      InsertInstanceTemplateRequest insertInstanceTemplateRequest = InsertInstanceTemplateRequest
          .newBuilder()
          .setProject(projectId)
          .setInstanceTemplateResource(InstanceTemplate.newBuilder()
              .setName(templateName)
              .setProperties(instanceProperties)
              .build())
          .build();

      Operation response = instanceTemplatesClient.insertAsync(insertInstanceTemplateRequest)
          .get(3, TimeUnit.MINUTES);

      if (response.hasError()) {
        return null;
      }
      return instanceTemplatesClient.get(projectId, templateName);
    }
  }
}

Node.js

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

// Instantiate an instanceTemplatesClient
const instanceTemplatesClient = new computeLib.InstanceTemplatesClient();
// Instantiate a globalOperationsClient
const globalOperationsClient = new computeLib.GlobalOperationsClient();

/**
 * TODO(developer): Update/uncomment these variables before running the sample.
 */
// The ID of the project where you want to create template.
const projectId = await instanceTemplatesClient.getProjectId();
// The name of the template to create.
// const templateName = 'instance-01';

// Create an instance template that creates VMs that don't explicitly consume reservations
async function callCreateTemplateToNotConsumeReservation() {
  // Define the boot disk for the instance template
  const disk = new compute.AttachedDisk({
    initializeParams: new compute.AttachedDiskInitializeParams({
      sourceImage:
        'projects/debian-cloud/global/images/debian-12-bookworm-v20240815',
      diskSizeGb: '100',
      diskType: 'pd-balanced',
    }),
    autoDelete: true,
    boot: true,
    type: 'PERSISTENT',
  });

  // Define the network interface for the instance template
  const network = new compute.NetworkInterface({
    network: `projects/${projectId}/global/networks/default`,
  });

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

  // Define instance template
  const instanceTemplate = new compute.InstanceTemplate({
    name: templateName,
    properties: {
      disks: [disk],
      machineType: 'e2-medium',
      // The template connects the instance to the `default` network,
      // without specifying a subnetwork.
      networkInterfaces: [network],
      reservationAffinity,
    },
  });

  const [response] = await instanceTemplatesClient.insert({
    project: projectId,
    instanceTemplateResource: instanceTemplate,
  });

  let operation = response.latestResponse;

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

  console.log(`Template ${templateName} created.`);
}

await callCreateTemplateToNotConsumeReservation();

Python

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 create_instance_template_not_consume_reservation(
    project_id: str,
    template_name: str,
    machine_type: str = "n1-standard-1",
) -> compute_v1.InstanceTemplate:
    """
    Creates an instance template that creates VMs that don't explicitly consume reservations

    Args:
        project_id: project ID or project number of the Cloud project you use.
        template_name: name of the new template to create.
        machine_type: machine type for the instance.
    Returns:
        InstanceTemplate object that represents the new instance template.
    """

    template = compute_v1.InstanceTemplate()
    template.name = template_name
    template.properties.machine_type = machine_type
    # The template describes the size and source image of the boot disk
    # to attach to the instance.
    template.properties.disks = [
        compute_v1.AttachedDisk(
            boot=True,
            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,
            ),
        )
    ]
    # The template connects the instance to the `default` network,
    template.properties.network_interfaces = [
        compute_v1.NetworkInterface(
            network="global/networks/default",
            access_configs=[
                compute_v1.AccessConfig(
                    name="External NAT",
                    type="ONE_TO_ONE_NAT",
                )
            ],
        )
    ]
    # The template doesn't explicitly consume reservations
    template.properties.reservation_affinity = compute_v1.ReservationAffinity(
        consume_reservation_type="NO_RESERVATION"
    )

    template_client = compute_v1.InstanceTemplatesClient()
    operation = template_client.insert(
        project=project_id, instance_template_resource=template
    )

    wait_for_extended_operation(operation, "instance template creation")

    return template_client.get(project=project_id, instance_template=template_name)

REST

Per creare un modello di istanza che crei VM che non consumano esplicitamente le prenotazioni, invia una richiesta POST a uno dei seguenti metodi:

Nel corpo della richiesta, includi il campo consumeReservationType e impostalo su NO_RESERVATION.

Ad esempio, per creare un modello di istanza globale che crei VM che non consumano esplicitamente le prenotazioni, effettua una richiesta come segue:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/InstanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "machineType": "MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "reservationAffinity": {
      "consumeReservationType": "NO_RESERVATION"
    }
  }
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto in cui creare il modello di istanza.

  • INSTANCE_TEMPLATE_NAME: il nome del modello di istanza.

  • MACHINE_TYPE: il tipo di macchina da utilizzare per le VM create utilizzando il modello di istanza.

  • IMAGE_PROJECT: il progetto immagine che contiene l'immagine del sistema operativo, ad esempio debian-cloud. Per saperne di più sui progetti di immagini supportati, consulta Immagini pubbliche.

  • IMAGE: specifica una delle seguenti opzioni:

    • Una versione specifica dell'immagine del sistema operativo, ad esempio debian-12-bookworm-v20240617.

    • Una famiglia di immagini, che deve essere formattata come family/IMAGE_FAMILY. Specifica l'immagine del sistema operativo più recente e non ritirata. Ad esempio, se specifichi family/debian-12, viene utilizzata la versione più recente della famiglia di immagini Debian 12. Per saperne di più sull'utilizzo delle famiglie di immagini, consulta le best practice per le famiglie di immagini.

Per saperne di più sulla creazione di modelli di istanze, consulta Creare modelli di istanze.

Verificare che le proprietà della VM corrispondano a una prenotazione

Per verificare se le VM possono utilizzare automaticamente una prenotazione, puoi creare una copia della prenotazione come prenotazione specifica e poi verificare se una VM che prevedi di creare può utilizzarla. Se riesci a creare correttamente la VM, significa che hai verificato che la VM può utilizzare correttamente la prenotazione corrispondente. In caso contrario, la creazione della VM non riesce perché le proprietà non corrispondono o non sono presenti risorse riservate disponibili. Dopo il test, puoi eseguire una o più delle seguenti operazioni:

Verificare il consumo delle prenotazioni

Per assicurarti che le VM consumino efficacemente le prenotazioni, puoi verificarne il consumo utilizzando i seguenti metodi:

  • Visualizzare i dettagli della prenotazione

    Se il numero di VM che utilizzano una prenotazione aumenta di 1 dopo aver creato o aggiornato una VM, è probabile che la tua azione abbia causato l'inizio dell'utilizzo della prenotazione da parte della VM. Questo è il modo più rapido per verificare se una prenotazione è in corso di utilizzo. Tuttavia, potrebbe non essere efficace per verificare quale VM esatta sta utilizzando la prenotazione.

  • Crea la VM da scegliere come target per una prenotazione specifica

    Se riesci a creare una VM che ha come target una prenotazione specifica, significa che la VM sta utilizzando la prenotazione. Questo è il metodo più affidabile per verificare che una VM specifica stia utilizzando una prenotazione e che le proprietà della VM corrispondano a quelle della prenotazione.

  • Monitorare il consumo delle prenotazioni

    Utilizzando Cloud Monitoring, puoi accedere e visualizzare le informazioni associate al consumo delle prenotazioni create nel tuo progetto. Il monitoraggio aggiorna i dati sul consumo delle prenotazioni almeno ogni 30 minuti. Questo metodo è utile per verificare la tendenza di consumo di una o più prenotazioni in un progetto, nonché per ricevere notifiche per prenotazioni sottoutilizzate o inutilizzate.

  • Visualizzare l'utilizzo storico delle prenotazioni

    Utilizzando Capacity Planner (Preview), puoi accedere e visualizzare l'utilizzo storico delle prenotazioni dalla loro creazione fino alla loro eliminazione. Lo strumento di pianificazione della capacità aggiorna i dati sul consumo delle prenotazioni ogni 24 ore. Questo metodo è utile per verificare il consumo passato delle prenotazioni all'interno di un progetto, di una cartella o di un'organizzazione, nonché per aiutarti a pianificare le esigenze di capacità future.

Se noti che una VM non utilizza una prenotazione dopo aver verificato che l'affinità della prenotazione della VM può utilizzare la prenotazione, la prenotazione non è stata completamente utilizzata e le proprietà della VM e della prenotazione corrispondono, consulta Disponibilità delle risorse.

Visualizzare i report sull'utilizzo delle prenotazioni

Esporta report dettagliati sull'utilizzo di Compute Engine in un bucket Cloud Storage utilizzando la funzionalità di esportazione dell'utilizzo. Per le istruzioni, consulta Visualizzare i report sull'utilizzo.

Il report sull'utilizzo mostra quanto segue:

  • Le risorse prenotate in uso. Queste voci vengono visualizzate come normali risorse vCPU, memoria, GPU e SSD locali.
  • Le risorse prenotate non in uso. Queste voci hanno nomi SKU e URI delle risorse di prenotazione normali.
  • Risorse prenotate totali. Queste voci hanno nomi SKU di prenotazione e URI di risorse di prenotazione. Non sono previsti costi per queste voci. Utilizza queste voci per calcolare quante prenotazioni stai utilizzando.
Misurazione Formato MeasurementId Formato Resource URI
Risorse riservate in uso com.google.cloud/services/compute-engine/SKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/RESOURCE_NAME.

Ad esempio, https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/my-instance
Risorse prenotate non in uso com.google.cloud/services/compute-engine/SKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME.

Ad esempio, https://compute.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-b/reservations/my-reservation
Risorse riservate totali com.google.cloud/services/compute-engine/ReservationSKU_NAME https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations/RESERVATION_NAME.

Ad esempio, https://compute.googleapis.com/compute/v1/projects/my-project/zones/europe-west1-b/reservations/my-reservation

Ad esempio, nel seguente snippet di un report sull'utilizzo per una prenotazione chiamata my-reservation:

  • La riga 1 mostra la RAM prenotata attualmente in uso. Il valore ResourceId della riga indica che questa RAM è utilizzata da una VM denominata my-instance.
  • La riga 2 mostra la RAM riservata non in uso. Il valore ResourceId della riga indica che questa RAM riservata è in possesso di my-reservation e non è ancora utilizzata da nessuna VM.
  • La riga 3 mostra la RAM totale prenotata della prenotazione.
Report Date,MeasurementId,Quantity,Unit,Resource URI,ResourceId,Location
2019-06-06,com.google.cloud/services/compute-engine/VmimageN2StandardRam,166970074857472,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/instances/my-instance,1775485842510981624,us-central2-a
2019-06-06,com.google.cloud/services/compute-engine/VmimageN2StandardRam,166970074857472,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/reservations/my-reservation,7.58809E+17,us-central2-a
2019-06-06,com.google.cloud/services/compute-engine/ReservationN2StandardRam,333940149714944,byte-seconds,https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central2-a/reservations/my-reservation,7.58809E+17,us-central2-a
...

Risoluzione dei problemi

Scopri come risolvere i problemi relativi al consumo delle prenotazioni.

Passaggi successivi