Creating an instance template

Before you begin

Make sure that you set up your IBM Cloud® CLI environment and your IBM Cloud VPC.

Gathering information to create an instance template

Ready to create an instance template? Before you can run the ibmcloud is instance-template-create command, you must gather the details that you need to include for your instance template and command options. For example, you need the ID or name of the VPC, and the name of the zone where the instance template is to be created. You also need the name of the instance profile that you want to use, and the ID or name of the subnet where the template is to be created.

Gather the following required instance template details.

Use the following commands to determine the required information for creating an instance template.

1. List the regions that are associated with your account.

   ibmcloud is regions
   

   See the following example.

   $ ibmcloud is regions
   Listing regions under account Test Account as user test.user@ibm.com...
   Name       Endpoint                              Status
   au-syd     https://au-syd.iaas.cloud.ibm.com     available
   br-sao     https://br-sao.iaas.cloud.ibm.com     available
   ca-tor     https://ca-tor.iaas.cloud.ibm.com     available
   eu-de      https://eu-de.iaas.cloud.ibm.com      available
   eu-es      https://eu-es.iaas.cloud.ibm.com      available
   eu-gb      https://eu-gb.iaas.cloud.ibm.com      available
   jp-osa     https://jp-osa.iaas.cloud.ibm.com     available
   jp-tok     https://jp-tok.iaas.cloud.ibm.com     available
   us-east    https://us-east.iaas.cloud.ibm.com    available
   us-south   https://us-south.iaas.cloud.ibm.com   available
   

2. Switch to your target region.

   ibmcloud target -r <region-name>
   

3. List the zones that are associated with the target region.

   ibmcloud is zones
   

   In the following example, the command is run in the us-south region and the output shows the available zones that are in the region.

   $ ibmcloud is zones
   Listing zones in target region us-south under account Test Account as user test.user@ibm.com...
   Name         Region     Status
   us-south-1   us-south   available
   us-south-2   us-south   available
   us-south-3   us-south   available
   

4. List the IBM Cloud VPCs that are associated with your account.

   ibmcloud is vpcs
   

   For this example, you see a response similar to the following output.

   ID                                          Name                         Status      Classic access   Default network ACL                   Default security group                 Resource group
   r006-0d37163a-701d-4ad6-9ece-a3e34cf28935   cdl                          available   false            acl-test-1                            pedicure-budding-providing-excluded    Default
   r006-212def4b-93f0-4b9a-a331-94178b99d474   cli-test-1                   available   false            surprise-pacifier-cubicle-demystify   foyer-alongside-rug-zen                Default
   

   If you don't have one available, you can create an IBM Cloud VPC by using the ibmcloud is vpc-create command. For more information about creating an IBM Cloud VPC, see IBM Cloud VPC CLI reference.

5. List the available profiles for creating your instance template.

   ibmcloud is instance-profiles
   

   The command output is similar to the following example.

   Name               vCPU Manufacturer   Architecture   Family              vCPUs   Memory(GiB)   Bandwidth(Mbps)   Volume bandwidth(Mbps)   GPUs   Storage(GB)
   bx2-2x8            intel               amd64          balanced            2       8             4000              1000                     -      -
   bx2d-2x8           intel               amd64          balanced            2       8             4000              1000                     -      1x75
   bx2-4x16           intel               amd64          balanced            4       16            8000              2000                     -      -
   bx2d-4x16          intel               amd64          balanced            4       16            8000              2000                     -     1x150
   bx2-8x32           intel               amd64          balanced            8       32            16000             4000                     -      -
   bx2d-8x32          intel               amd64          balanced            8       32            16000             4000                     -     1x300
   bx2-16x64          intel               amd64          balanced            16      64            32000             8000                     -      -
   bx2d-16x64         intel               amd64          balanced            16      64            32000             8000                     -      1x600
   

6. List the subnets that are associated with the IBM Cloud VPC.

   ibmcloud is subnets
   

   The command output is similar to the following example.

   ID                                          Name                       Status      Subnet CIDR       Addresses   ACL                                   Public Gateway   VPC                     Zone         Resource group
   0717-cd4f74f1-bfae-423a-886b-9163256ec4a9   subnet-south-1             available   10.240.0.0/24     124/256     acl-test-1                            -                cdl                     us-south-1   Default
   0727-9447a2c3-efb8-44d2-a180-115531e0b0d3   cdl                        available   10.240.64.0/24    238/256     acl-test-1                            -                cdl                     us-south-2   Default
   

   For the best performance of an instance group, make sure that you use a subnet size of 32 or greater.

   If you don't have a subnet available, you can create one by using the ibmcloud is subnet-create command. For more information about creating a subnet, see the IBM Cloud VPC CLI reference.

7. List the available images for creating your instance template.

   ibmcloud is images
   

   The command output is similar to the following example.

   ID                                          Name                                                Status       Arch    OS name                              OS version                                               File size(GB)   Visibility   Owner type   Encryption   Resource group
   r006-3fa3bea4-7f9c-4eeb-8248-ab1f6e03185b   ibm-centos-7-9-minimal-amd64-9                      available    amd64   centos-7-amd64                       7.x - Minimal Install                                    1               public       provider     none         Default
   r006-c55167af-ea8c-4c27-871f-ccc9c868753e   ibm-centos-stream-8-amd64-1                         available    amd64   centos-stream-8-amd64                8                                                        2               public       provider     none         Default
   

8. List the available SSH keys that you can associate with your instance.

   ibmcloud is keys
   

   The command output is similar to the following example.

   ID                                          Name     Type   Length   FingerPrint          Resource group
   r006-89ec781c-9630-4f76-b9c4-a7d204828d61   my-key   rsa    4096     gtnf+pdX2PYI9Ofq..   Default
   

   If you do not have an SSH key available, you can create an SSH key by using the ibmcloud is key-create command.

   RSA and ED25519 are the two types of SSH keys that you can use. However, you can't use the ED25519 SSH key type with Windows or VMware images. You can use only RSA SSH keys for these images. For more information, see Getting started with SSH keys.

9. List all the available placement groups that you can associate with your instance.

   ibmcloud is placement-groups
   

   The command output is similar to the following example.

   Listing placement groups for generation 2 compute in all resource groups and region us-east under account vpcdemo as user    yaohaif@cn.ibm.com...
   ID                                            Name                             State    Strategy       Resource Group
   c5f1f366-b92a-4080-991a-aa5c2e33d96b          placement-group-region-us-east   stable   power_spread       5018a8564e8120570150b0764d39ebcc
   placement-group-cccc-cccc-cccc-cccccccccccc   vsi-placementGroup1              stable   host_spread    5018a8564e8120570150b0764d39ebcc
   placement-group-bbbb-bbbb-bbbb-bbbbbbbbbbbb   vsi-placementGroup2              stable   power_spread     5018a8564e8120570150b0764d39ebcc
   placement-group-aaaa-aaaa-aaaa-aaaaaaaaaaaa   vsi-placementGroup3              stable   power_spread   1d18e482b282409e80eff354c919c6a2
   

Creating an instance template from the CLI

After you know these values, use them to run the instance-template-create command. In addition to the information that you gathered, you must specify a name for the instance.

ibmcloud is instance-template-create INSTANCE_TEMPLATE_NAME VPC ZONE_NAME PROFILE_NAME SUBNET --image IMAGE

For example, if you create an instance template that is named my-instance-template in us-south-3 and use the bx2-2x8 profile, your instance-template-create command would look similar to the following sample.

ibmcloud is instance-template-create my-instance-template 0738-xxx1xx23-4xx5-6789-12x3-456xx7xx123x us-south-3 bx2-2x8 0076-2249dabc-8c71-4a54-bxy7-953701ca3999 --image r008-54e9238a-feaa-4f90-9742-7424cb2b9ff1 --placement-group r006-953db18c-068c-4a11-9b07-645684b444b2

Where

• INSTANCE_TEMPLATE_NAME is my-instance-template
• VPC is 0738-xxx1xx23-4xx5-6789-12x3-456xx7xx123x
• ZONE_NAME is us-south-3
• PROFILE_NAME is bx2-2x8
• SUBNET_ID is 0076-2249dabc-8c71-4a54-bxy7-953701ca3999
• IMAGE is r008-54e9238a-feaa-4f90-9742-7424cb2b9ff1
• PLACEMENT_GROUP_ID is _r134-953db18c-068c-4a11-9b07-645684b444b2

For this example, you see a response similar to the following output.

The following response varies depending on what values that you use.

ID                          0727-0fdac0fb-ad59-4d7b-9f03-604ddc1db002
Name                        my-instance-template
CRN                         crn:v1:bluemix:public:is:us-south-2:a/7f75c7b025e54bc5635f754b2f888665::instance-template:0727-0fdac0fb-ad59-4d7b-9f03-604ddc1db002
Resource group              Default
Image                       r006-3fa3bea4-7f9c-4eeb-8248-ab1f6e03185b
VPC                         r006-212def4b-93f0-4b9a-a331-94178b99d474
Zone                        us-south-2
Profile                     bx2-2x8
Boot volume                 Name   Capacity   Profile           IOPS   Attachment name                      Auto delete   Tags
                            -      100        general-purpose   0      illude-education-spotted-reanalyze   true          -

Primary Network Interface   Name      Subnet ID                                   Security Groups                             Allow source IP spoofing   Reserved IP Address   Reserved IP ID   Reserved IP Name   Reserved IP Auto Delete
                            primary   0727-944126da-e46d-4104-8ba4-ab5a5832864b   r006-2295f00e-8af0-4736-be11-94677955b6b2   false                      -                     -                -                  -

Placement                   ID
                            r006-9994e3ab-18ae-49a7-95cf-25c77e09fa76

Created                     2023-03-29T22:02:59+05:30

For more examples of the ibmcloud is instance-template-create command, see the VPC CLI reference.

When you create an instance template, validation steps are performed to make sure that you can use your template to provision a virtual server instance. Need more help? You can always run ibmcloud is help instance-template-create to display help for creating an instance template.

Before you begin

Define variables for the IAM token, API endpoint, and API version. For instructions, see Setting up your API and CLI environment.

Make sure that you have the required access. To call these methods, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to the Users page of Cloud Identity and Access Management dashboard.

A good way to learn more about the API is to click Get sample API call on the provisioning pages in IBM Cloud console. You can view the correct sequence of API requests and better understand actions and their dependencies.

Gathering information to create an instance template

Ready to create an instance template? Before you can make the POST request with the /instance/templates method, you need to know the details that you want to include for your instance template. For example, you need the ID or name of the VPC, and the name of the zone where the instance template is to be created. You also need the name of the instance profile that you want to use, and the ID or name of the subnet where the template is to be created.

Gather the following required instance template details by making the following API calls:

Use the following commands to determine the required information for creating a new instance template.

1. List the IBM Cloud VPCs that are associated with your account.

   curl -X GET "$vpc_api_endpoint/v1/vpcs?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

   If you don't have one available, you can create an IBM Cloud VPC by using the POST /vpcs method. For more information about creating an IBM Cloud VPC, see IBM Cloud API Docs - Create a VPC.

2. List the regions associated with your account.

   curl -X GET "$vpc_api_endpoint/v1/regions?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

3. List the zones that are associated with the region.

   curl -X GET "$vpc_api_endpoint/v1/regions/$region_name/zones?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

4. List the available profiles for creating your instance template.

   curl -X GET "$vpc_api_endpoint/v1/instance/profiles?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

5. List the subnets that are associated with the IBM Cloud VPC.

   curl -X GET "$vpc_api_endpoint/v1/subnets?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

   For the best performance of an instance group, make sure that you use a subnet size of 32 or greater.

   If you don't have a subnet available, you can create one by using the POST /subnets method. For more information about creating an IBM Cloud VPC, see IBM Cloud API Docs - Create a subnet.

6. List the available images for creating your instance template.

   curl -X GET "$vpc_api_endpoint/v1/images?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

7. List the available SSH keys that you can associate with your instance.

   curl -X GET "$vpc_api_endpoint/v1/keys?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

   If you do not have an SSH key available, you can create an SSH key by using the ibmcloud is key-create command.

   If you don't have an SSH key available, you can create one by using the POST /keys method. For more information about creating an IBM Cloud VPC, see IBM Cloud API Docs - Create a key.

   RSA and ED25519 are the two types of SSH keys that you can use. However, you can't use the ED25519 SSH key type with Windows or VMware images. You can use only RSA SSH keys for these images. For more information, see Getting started with SSH keys.

8. List all the available placement groups that you can associate with your instance.

   curl -X GET "$vpc_api_endpoint/v1/placement_groups?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token"
   

Creating the instance template with the API

After you know these values, use them to make a POST request with the /instance/templates method. In addition to the information that you gathered, you must specify a name for the instance.

For example, if you create an instance template that is named my-instance-template in us-south-1 and use the bx2-2x8 profile, your POST /instance/templates command would look similar to the following sample.

curl -X POST "$vpc_api_endpoint/v1/instance/templates?version=2023-07-13&generation=2" -H "Authorization: Bearer $iam_token" -d '{
      "primary_network_interface": {
        "subnet": {
          "id": "0d933c75-492a-4756-9832-1200585dfa79"
        }
      },
      "name": "my-instance-template",
      "zone": {
        "name": "us-south-1"
      },
      "vpc": {
        "id": "dc201ab2-8536-4904-86a8-084d84582133"
      },
      "profile": {
        "name": "bx2-2x8"
      },
      "image": {
        "id": "3f9a2d96-830e-4100-9b4c-663225a3f872"
      },
      "placement_group": {
          "id": "363f6d70-0000-0001-0000-00000013b96c"
      },
      "keys": [
        {
          "id": "363f6d70-0000-0001-0000-00000013b96c"
         }
      ]
    }'

Where

• instance_template_name is my-instance-template
• vpc is dc201ab2-8536-4904-86a8-084d84582133
• zone_name is us-south-1
• profile_name is bx2-2x8
• subnet_id is 0d933c75-492a-4756-9832-1200585dfa79
• image is 3f9a2d96-830e-4100-9b4c-663225a3f872
• keys is 363f6d70-0000-0001-0000-00000013b96c
• placement_group is 363f6d70-0000-0001-0000-00000013b96c

For more examples of the /instance/templates method, see the Create an instance template API documentation.

Before you begin

Make sure that you set up Terraform for VPC.

Gathering information to create an instance template

Ready to create an instance template? Before you include the ibm_is_instance_template resource in your configuration, you need to know the details that you want to include in your instance template. For example, you need the ID or name of the VPC, and the name of the zone where the instance template is to be created. You also need the name of the instance profile that you want to use, and the ID or name of the subnet where the template is to be created.

Gather the following required Terraform instance template details.

Use the following guide to determine the required information for creating a new instance template.

Gather the following information by using DataSource block.

1. Gather instance profile details. Run the following block for the profile that you select. See x86 instance profiles for a list of available profiles. For more information, see the Terraform documentation on ibm_is_instance_profiles. Use an instance profile by referring to the instance profile data source. For more information, see the Terraform documentation on ibm_is_instance_profile.

   data "ibm_is_instance_profile" "example_profile" {
      name = "bx2-2x8"
   }
   

2. List the available images for creating your instance. You can use a stock image, a custom image from your account, or an image that was shared with your account from a private catalog. For more information, see the Terraform documentation on ibm_is_image. If you plan to use an image that was shared from a private catalog, see the Terraform documentation on ibm_cm_version or ibm_cm_offering_instance.

   • Select a stock image or custom image from your account for your instance.

   data "ibm_is_image" "example_image" {
      name = "ibm-centos-7-6-minimal-amd64-2"
   }
   

   • Select an image that is shared from a private catalog for the instance. For more information, see the Terraform documentation on ibm_is_images.

   data "ibm_is_images" "example_images" {
      catalog_managed = true
   }
   

   If you select a catalog image that belongs to a different account, you have more considerations and limitations to review. See Using cross-account image references in a private catalog in Terraform.

3. Create a VPC resource or use an existing VPC by referring to the VPC data source. For more information, see the Terraform documentation on data source ibm_is_vpc or resource ibm_is_vpc.

   data "ibm_is_vpc" "example_vpc" {
      name = "example-vpc"
   }
   

4. Create a subnet resource or use an existing subnet by referring to the subnet data source. For more information, see the Terraform documentation on data source ibm_is_subnet or resource ibm_is_subnet.

   data "ibm_is_subnet" "example_subnet" {
      name            = "example-subnet"
      vpc             = ibm_is_vpc.example_vpc.id
      zone            = "us-south-1"
      ipv4_cidr_block = "10.240.0.0/24"
   }
   

5. Use an existing ssh-key by referring to the ssh-key data source ibm_is_ssh_key. If you don't have any available SSH keys, use the resource ibm_is_ssh_key to create one.

   RSA and ED25519 are the two types of SSH keys that you can use. However, you can't use the ED25519 SSH key type with Windows or VMware images. You can use only RSA SSH keys for these images. For more information, see Getting started with SSH keys.

   resource "ibm_is_ssh_key" "example_sshkey" {
      name       = "example-sshkey"
      public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCKVmnMOlHKcZK8tpt3MP1lqOLAcqcJzhsvJcjscgVERRN7/9484SOBJ3HSKxxNG5JN8owAjy5f9yYwcUg+JaUVuytn5Pv3aeYROHGGg+5G346xaq3DAwX6Y5ykr2fvjObgncQBnuU5KHWCECO/4h8uWuwh/kfniXPVjFToc+gnkqA+3RKpAecZhFXwfalQ9mMuYGFxn+fwn8cYEApsJbsEmb0iJwPiZ5hjFC8wREuiTlhPHDgkBLOiycd20op2nXzDbHfCHInquEe/gYxEitALONxm0swBOwJZwlTDOB7C6y2dzlrtxr1L59m7pCkWI4EtTRLvleehBoj3u7jB4usR"
   }
   

Next steps

After you create an instance template, you can provision a single virtual server instance, or you can provision multiple instances at the same time as part of an instance group. Optionally, you can set auto scaling policies for your instance group to dynamically add or remove virtual server instances from your group. For more information, see the following topics:

• Bulk provisioning instances with instance groups
• Creating an instance group for auto scaling
• Managing an instance template