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.
-
In the IBM Cloud console, click Navigation Menu icon > Infrastructure > Reservations.
-
To create a new reservation, click Create.
-
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. -
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.
- From your virtual server list, click Attach.
- 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.
- From your bare metal server list, click Attach.
- 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
-
Download, install, and initialize the following CLI plug-ins.
- IBM Cloud CLI
- The infrastructure-service plug-in
For more information, see Setting up your API and CLI environment.
-
Make sure that you created a VPC.
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.
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.
|
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.
- 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.
- 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.
- 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"
}