IBM Cloud Docs
Provisioning a reservation for VPC

Provisioning a reservation for VPC

You can provision a reservation through the UI, CLI, or API.

Before you begin

Make sure that your account has the required user permissions. Your account must be assigned the Administrator or Editor role for the VPC Infrastructure Services service and Reservations for VPC resource type. You need one of these user permissions to create a reservation. Extra roles are available.

For more information about managing IAM access, see Managing IAM access for VPC Infrastructure Services.

Provisioning a reservation with the UI

In the IBM Cloud, complete the following steps to provision your reservation.

  1. In the IBM Cloud console, click Navigation Menu icon the menu icon > Infrastructure VPC icon > Reservations.

  2. To create a new reservation, click Create.

  3. From the New reservation for VPC page, enter or select the following information:

    Reservation UI provisioning selections
    Field Value
    Geography Select the specific location for your workload. Locations are composed of regions. Each region is a separate geographic area. Keep in mind that you can't select individual locations for each virtual server that you provision within this reservation. Your selection is the location for all virtual server instances that you provision within this reservation.
    Name Enter a name for your reservation.
    Resource group Select a resource group.
    Tags Enter any applicable tags.
    Access management tags Enter any applicable access management tags.
    Reservation type Available for virtual servers and bare metal servers.
    Server quantity Enter the number of instances that you want to assign to this reservation (a limit of 200 vCPUs).
    Term length Choose either a 1 or 3-year term length.
    Server profile Select a profile for your reservation. Keep the following rules in mind when you reserve capacity.
    You can't change profiles after your reservation is created.
    You can't combine different profile sizes.
    Your reserved virtual servers must all have the same size (all resources must be identical).
    Advanced options Toggle Auto renew to On if you want to continue your reservation after your selected term length completes.
  4. Click Create a reservation.

When a reservation expires, the servers that are attached to a reservation convert to the nondiscounted on-demand rate upon expiration or nonrenewal of the reservation term and any consumption are billed monthly.

Attaching an existing virtual server to a reservation with the UI

You can attach existing virtual servers to your reservation. Keep in mind that all existing virtual servers must be the same profile, size, and location.

  1. From your virtual server list, click Attach.
  2. Select the reservation to attach the server to and click Attach.

Attaching an existing bare metal server to a reservation with the UI (beta)

Reserved bare metal servers are a beta feature that is available for evaluation and testing purposes.

You can attach an existing bare metal server to your reservation. Keep in mind that all existing bare metal servers that are attached to a reservation must be the same profile, size, and location.

  1. From your bare metal server list, click Attach.
  2. Select the reservation to attach the server to and click Attach.

Provisioning a reservation with the CLI

You can provision a reservation by using the command-line interface (CLI). If you want to use user tags or access management tags to manage your resources, see Working with tags.

IBM Cloud CLI is not supported on LinuxONE (s390x processor architecture). However, you can install the CLI on another supported platform and use it with LinuxONE (s390x processor architecture) virtual server instances.

Before you begin

Gathering information to create a reservation by using the CLI

Ready to create a reservation with the CLI? Before you can run the is.reservation-create command, you need to know the details about the reservation that you want to reserve such as the reservation type and server quantity.

Gather the following information by using the associated commands.

Required reservation details for the CLI
Reservation details Listing options
Capacity Amount of capacity to reserve (limit of 200 vCPUs).
Term length (1 or 3-year term length)
Server profile

Keep the following rules in mind when you provision a reservation.

  • You can't change profiles after your reservation is created.
  • You can't combine different profile sizes.
  • Your reserved virtual servers must all have the same size (all resources must be identical).
Zone Select the specific location for your workload. Locations are composed of regions; each region is a separate geographic area. Keep in mind that you can't select individual locations for each virtual server that you provision within this reserved capacity. Your selection is the location for all virtual server instances that you provision within this reservation.
Name The name for your reservation.

Provisioning a reservation by using the CLI

You can create an IBM Cloud VPC Reservation in your region by using the command-line interface (CLI). To create a reservation by using the CLI, use the ibmcloud is reservation-create command.

  1. Provision a reservation by using the following command with the associated details.
ibmcloud is reservation-create --capacity NUMBER --term TIME --profile PROFILE --profile-resource-type PROFILE_TYPE --zone ZONE --name NAME

See the following example.

ibmcloud is reservation-create --capacity 10 --term one_year --profile ba2-2x8 --profile-resource-type instance_profile --zone us-east-1 --name reservation-mock-test-1
Creating reservation with name reservation-mock-test-1 under account VPCUI-DEMO as user Sreekar.B.V@ibm.com...

ID                22d3ec3b-d798-454a-ad88-fe608ae86ad6
Name              reservation-mock-test-1
CRN               crn:v1:staging:public:is:us-east:a/823bd195e9fd4f0db40ac2e1bffef3e0::reservation:22d3ec3b-d798-454a-ad88-fe608ae86ad6
Status            active
Zone              us-east-1
Lifecycle state   stable
Affinity Policy   open
Resource group    -
Profile Name      ba2-2x8
Created At        2023-07-21T10:54:46.29+05:30
Expiration        At   Policy   Term
                  -    -        one_year

Capacity          Allocated   Available   Total   Used   Status
                  10          -           10      -      -

Where the following argument and option values are used:

  • --name: New name for the reservation.
  • --capacity: The capacity configuration for this reservation.
  • --term: Term of the reservation. One of: one_year, three_year.
  • --profile: The name of the profile to use for this reservation.
  • --profile-resource-type: The resource type of the profile. One of: instance_profile.
  • --zone: Name of the zone
  • --affinity-policy: The affinity policy for this reservation.
  • --expiration-policy: The policy to apply when the committed use term expires. One of: release, renew.
  • --resource-group-id: ID of the resource group. This ID is mutually exclusive with --resource-group-name.
  • --resource-group-name: Name of the resource group. This name is mutually exclusive with --resource-group-id.
  • --output: Specify output format, only JSON is supported. One of: JSON.
  • -q, --quiet: Suppress verbose output.

Next steps

After your reservation is provisioned and active, you can Attach or Create virtual servers by using the IBM Cloud console, the CLI, or the API. For more information about creating a virtual server, see Creating virtual server instances.

Attaching an existing virtual server to a reservation with the CLI

You can attach an existing virtual server to a reservation by using the CLI. To create a reserved reservation by using the CLI, use the ibmcloud is instance-update command.

  1. Attach a virtual server to a reservation by using the following command with the associated details.
ibmcloud is instance-update <instance-name> -reservation-affinity-policy manual --reservation-affinity-pool <reservation-name>

Attaching an existing bare metal server to a reservation with the CLI (beta)

Reserved bare metal servers are a beta feature that is available for evaluation and testing purposes.

You can attach an existing bare metal server to a reservation by using the CLI. To create a reserved reservation by using the CLI, use the ibmcloud is bare-metal-server-update command.

  1. Attach a bare metal server to a reservation by using the following command with the associated details.
ibmcloud is bare-metal-server-update SERVER [--name NEW_NAME] [--enable-secure-boot false | true] [--tpm-mode tpm_2 | disabled] [--bandwidth BANDWIDTH] [--reservation-affinity-policy, --res-policy disabled | manual] [--reservation-affinity-pool, --res-pool RESERVATION_AFFINITY_POOL] [--output JSON] [-q, --quiet]

Creating a reservation with the API

You can create an IBM Cloud VPC reservation in your region by using the application programming interface (API). To create a reservation by using the API, use Create a reservation.

Specify a Post /reservations request create a new reservation. See the following example.

curl -X POST "$vpc_api_endpoint/v1/reservations?version=2024-01-27&generation=2" -H "Authorization: Bearer $iam_token" -d '{
      "capacity": {
        "total": 10
      },
      "committed_use": {
        "expiration_policy": "renew",
        "term": "one_year"
      },
      "name": "my-reservation",
      "profile": {
        "name": "bx2-4x16",
        "resource_type": "instance_profile"
      },
      "zone": {
        "name": "us-south-1"
      }
    }'

Next steps

After your reservation is provisioned and active, you can attach an existing server to your reservation. Or, you can create servers in your reservation by using the IBM Cloud console, the CLI, or the API. For more information about creating server, see Creating virtual server instances and Creating Bare Metal Servers on VPC.

Creating a reservation with Terraform

You can create a reservation by using Terraform.

Before you begin

Make sure that you set up Terraform for VPC

Creating a reservation by using Terraform

Create a reservation by using one of the following examples. For more information, see the Terraform documentation on ibm_is_reservation.

Run the following Terraform commands to create a reservation.

Reservations are regional-specific that are based on the endpoint. By default, the target region is us-south. If your VPC is in another region other than us-south, make sure that you target the correct region in the provider provider.tf.

  • Set the target region.
provider "ibm" {
  region = "us-south"
}
  • Create a reservation.
resource "ibm_is_reservation" "example" {
capacity {
 total = 5
}
committed_use {
 term = "one_year"
}
profile {
 name          = "ba2-2x8"
 resource_type = "instance_profile"
}
zone = "us-east-3"
name = "reservation-terraform-1"
}