Consuming reserved zonal resources

Standard

Customers can reserve Compute Engine instances in a specific zone to ensure resources are available for their workloads when needed. For more details on how to manage reservations, see Reserving Compute Engine zonal resources.

After creating reservations, you can create Google Kubernetes Engine (GKE) clusters and node pools to consume the reserved instances. GKE supports the same consumption modes as Compute Engine:

Consuming resources from any reservations.
Consuming resources from a specific reservation.
Creating nodes without consuming any reservations.

Before you begin

Before you start, make sure you have performed the following tasks:

Enable the Google Kubernetes Engine API.

Enable Google Kubernetes Engine API

If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI.
Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Consuming reserved instances in GKE

When you create a cluster or node pool, you can indicate the reservation consumption mode by specifying the --reservation-affinity flag.

Consuming any matching reservations

To consume from any matching reservations automatically, set the reservation affinity flag to --reservation-affinity=any.

In the any reservation consumption mode, nodes first take capacity from all single-project reservations before any shared reservations, because the shared reservations are more available to other projects. For more information about how instances are automatically consumed see Consumption order.

To create a reservation and instances to consume any reservation, perform the following steps:

Create a reservation of three VM instances:
```
gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE --vm-count=3
```
Replace the following:
- RESERVATION_NAME: the name of the reservation to create.
- MACHINE_TYPE: the type of machine (name only) to use for the reservation. For example, n1-standard-2.
Verify the reservation was created successfully:
```
gcloud compute reservations describe RESERVATION_NAME
```
Replace RESERVATION_NAME with the name of the reservation you just created.
Create a cluster having one node to consume any matching reservation:
```
gcloud container clusters create CLUSTER_NAME \
    --machine-type=MACHINE_TYPE --num-nodes=1 \
    --reservation-affinity=any
```
Replace the following:
- CLUSTER_NAME: the name of the cluster to create.
- MACHINE_TYPE: the type of machine (name only) to use for the cluster. For example n1-standard-2.
Create a node pool with three nodes to consume any matching reservation:
```
gcloud container node-pools create NODEPOOL_NAME \
    --cluster CLUSTER_NAME --num-nodes=3 \
    --machine-type=MACHINE_TYPE --reservation-affinity=any
```
Replace the following:
- NODEPOOL_NAME: the name of the node pool to create.
- CLUSTER_NAME: the name of the cluster you created earlier.
- MACHINE_TYPE: the type of machine (name only) to use for the node pool. For example n1-standard-2.

The total number of nodes is four, which exceeds the capacity of the reservation. Three of the nodes consume the reservation while the last node takes capacity from the general Compute Engine resource pool.

Consuming a specific single-project reservation

To consume a specific reservation, set the reservation affinity flag to --reservation-affinity=specific and provide the specific reservation name. In this mode, instances must take capacity from the specified reservation in the zone. The request fails if the reservation does not have sufficient capacity.

To create a reservation and instances to consume a specific reservation, perform the following steps:

Create a specific reservation of three VM instances:
```
gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE --vm-count=3 \
    --require-specific-reservation
```
Replace the following:
- RESERVATION_NAME: the name of the reservation to create.
- MACHINE_TYPE: the type of machine (name only) to use for the reservation. For example, n1-standard-2.
Create a cluster having one node to consume a specific single-project reservation:
```
gcloud container clusters create CLUSTER_NAME \
    --machine-type=MACHINE_TYPE --num-nodes=1 \
    --reservation-affinity=specific --reservation=RESERVATION_NAME
```
Replace the following:
- CLUSTER_NAME: the name of the cluster to create.
- MACHINE_TYPE: the type of machine (name only) to use for the cluster. For example n1-standard-2.
- RESERVATION_NAME: the name of the reservation to consume.

Consuming a specific shared reservation

To create a specific shared reservation and consume the shared reservation, perform the following steps:

Follow the steps in Allowing and restricting projects from creating and modifying shared reservations.
Create a specific shared reservation:
```
gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE --vm-count=3 \
    --zone=ZONE \
    --require-specific-reservation \
    --project=OWNER_PROJECT_ID \
    --share-setting=projects \
    --share-with=CONSUMER_PROJECT_IDS
```
Replace the following:
- RESERVATION_NAME: the name of reservation to create.
- MACHINE_TYPE: the name of the type of machine to use for the reservation. For example, n1-standard-2.
- OWNER_PROJECT_ID: the project ID of the project that you want to create this shared reservation. If you omit the --project flag, GKE uses the current project as the owner project by default.
- CONSUMER_PROJECT_IDS: a comma-separated list of the project IDs of projects that you want to share this reservation with. For example, project-1,project-2. You can include 1 to 100 consumer projects. These projects must be in the same organization as the owner project. Do not include the OWNER_PROJECT_ID, because it can consume this reservation by default.
Consume the shared reservation:
```
gcloud container clusters create CLUSTER_NAME \
    --machine-type=MACHINE_TYPE --num-nodes=1 \
    --reservation-affinity=specific \
    --reservation=projects/OWNER_PROJECT_ID/reservations/RESERVATION_NAME
```
Replace the following:
- CLUSTER_NAME: the name of the new cluster.
- MACHINE_TYPE: the name of the type of machine to use for the cluster. For example n1-standard-2.
- OWNER_PROJECT_ID: the project ID where the shared reservation is created.
- RESERVATION_NAME: the name of the specific shared reservation to consume.

Additional considerations for consuming from a specific reservation

When a node pool is created with specific reservation affinity, including default node pools during cluster creation, its size is limited to the capacity of the specific reservation over the node pool's entire lifetime. This affects the following GKE features:

Cluster with multiple zones: In regional or multi-zonal clusters, nodes of a node pool can span across multiple zones. Since reservations are single-zonal, multiple reservations are needed. To create a node pool consuming specific reservation in these clusters, you must create a specific reservation with exactly the same name and machine properties in each zone of the node pool.
Cluster autoscaling and node pool upgrades: If you don't have extra capacity in the specific reservation, node pool upgrades or auto-scaling of the node pool might fail because both operations require creating extra instances. To resolve this, you can change the size of the reservation, or free up some of its bounded resources.

Creating nodes without consuming reservations

To explicitly avoid consuming resources from any reservations, set the affinity to --reservation-affinity=none.

Create a cluster to consume any matching reservation:
```
gcloud container clusters create CLUSTER_NAME --reservation-affinity=none
```
Replace CLUSTER_NAME with the name of the cluster to create.
Create a node pool to consume any matching reservation:
```
gcloud container node-pools create NODEPOOL_NAME \
    --cluster CLUSTER_NAME \
    --reservation-affinity=none
```
Replace the following:
- NODEPOOL_NAME: the name of the node pool to create.
- CLUSTER_NAME: the name of the cluster you created earlier.

Following available reservations between zones

When using node pools running in multiple zones with reservations that are not equal between zones, you can use the flag --location_policy=ANY. This ensures that when new nodes are added to the cluster they are created in the zone that still has unused reservations.

Cleaning up

To avoid incurring charges to your Cloud Billing account for the resources used in this page:

Delete the clusters you created by running the following command for each of the clusters:
```
gcloud container clusters delete CLUSTER_NAME
```
Delete the reservations you created by running the following command for each of the reservations:
```
gcloud compute reservations delete RESERVATION_NAME
```