Importing and validating custom images into VPC

Importing a custom image by using the UI

When you have an image available in IBM Cloud Object Storage, you can import it to IBM Cloud VPC infrastructure by using the IBM Cloud console.

1. Make sure that your compatible custom image is available in IBM Cloud Object Storage. To upload an image to IBM Cloud Object Storage, on the Objects page of your bucket, click Upload. You can use the Aspera high-speed transfer plug-in to upload images larger than 200 MB. For more information, see Creating a Linux custom image, Creating a Windows custom image, Bring your own license and Uploading data to IBM Cloud Object Storage.
2. In IBM Cloud console, go to Menu icon > VPC Infrastructure > Compute > Images.
3. On the Custom images tab, click Create.
4. Complete the fields that are described in Table 1 and click Create Custom Image.

Importing a custom image by using the CLI

Make sure that your compatible custom image is available in IBM Cloud Object Storage. For more information, see Creating a Linux custom image, Creating a Windows custom image, Creating a generic operating system custom image, Bring your own license and Uploading data to IBM Cloud Object Storage.

When you have an image available in IBM Cloud Object Storage, you can import it to IBM Cloud VPC infrastructure by using the command-line interface (CLI).

To import a custom image by using the CLI, use the ibmcloud is image-create command. Specify the name of the custom image to be created by using the IMAGE_NAME variable. The name can't be used by another image in the region and names that start with ibm- are reserved for system-provided images. You must also specify the source; for example, specify the --file option with the image file location. Specify the --os-name option with the name of the operating system for the image.

ibmcloud is image-create IMAGE_NAME [--file IMAGE_FILE_LOCATION] [--os-name OPERATING_SYSTEM_NAME]

The following example creates a custom image with the name of my-ubuntu-16-amd64. The image source location is cos://us-south/custom-image-vpc-bucket/customImage-0.qcow2. The operating system is ubuntu-16-amd64.

ibmcloud is image-create my-ubuntu-16-amd64 --file cos://us-south/custom-image-vpc-bucket/customImage-0.qcow2 --os-name ubuntu-16-amd64

For more information, see ibmcloud is image-create in the VPC CLI reference page.

ibmcloud is image-create IMAGE_NAME [--file IMAGE_FILE_LOCATION] [--os-name OPERATING_SYSTEM_NAME] [--deprecate-at YYYY-MM-DDThh:mm:ss+hh:mm] [--obsolete-at YYYY-MM-DDThh:mm:ss+hh:mm]

ibmcloud is image-create my-ubuntu-16-amd64 --file cos://us-south/custom-image-vpc-bucket/customImage-0.qcow2 --os-name ubuntu-16-amd64 --deprecate-at 2023-03-01T06:11:28+05:30 --obsolete-at 2023-12-31T06:11:28+05:30

Importing a custom image by using the API

Make sure that your compatible custom image is available in IBM Cloud Object Storage. For more information, see Creating a Linux custom image, Creating a Windows custom image, Creating a generic operating system custom image, Bring your own license, and Uploading data to IBM Cloud Object Storage.

When you have an image available in IBM Cloud Object Storage, you can import it to IBM Cloud VPC infrastructure by using the application programming interface (API).

To import a custom image by using the API, use Create an image.

The name can't be used by another image in the region and names that start with ibm- are reserved for system-provided images. Specify the file.href subproperty with the location of the image. Specify the operating_system.name subproperty with the name of the image operating system.

Generic operating system custom images is a beta feature that is available for evaluation and testing purposes. The generic operating systems have family of Generic. Be sure to select the one with allow_user_image_creation value of true and the user_data_format needed for your operating system to boot and initialize correctly. For more information, see User data format considerations.

The following example imports a custom image with the name of my-image, source location of cos://us-south/my-bucket/my-image.qcow2, and the operating system for the image is debian-9-amd64.

curl -X POST "$vpc_api_endpoint/v1/images?version=2023-02-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{
      "name": "my-image",
      "file": {
        "href": "cos://us-south/my-bucket/my-image.qcow2"
      },
      "operating_system": {
        "name": "debian-9-amd64"
      }
    }'

curl -X POST "$vpc_api_endpoint/v1/images?version=2023-02-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{
      "name": "my-image",
      "file": {
        "href": "cos://us-south/my-bucket/my-image.qcow2"
      },
      "operating_system": {
        "name": "debian-9-amd64"
      },
      "deprecation_at": "2023-03-01T06:11:28+05:30",
      "obsolescence_at": "2023-12-31T06:11:28+05:30"
    }'

Schedule custom image lifecycle status changes by using Terraform

When you import a custom image by using Terraform, you can also schedule the lifecycle status changes of an IBM Cloud VPC custom image at the same time by using the Terraform resource command ibm_is_image.

The name attribute can't be used by another image in the region and names that start with ibm- are reserved for system-provided images.

To schedule the deprecation_at or obsolescence_at attributes, specify a date in the ISO 8601 (YYYY-MM-DDThh:mm:ss+hh:mm) date and time format.

• YYYY is the four-digit year
• MM is the two-digit month
• DD is the two-digit day
• T separates the date and time information
• hh is the two-digit hours
• mm is the two-digit minutes
• +hh:mm or -hh:mm is the Coordinated Universal Time time zone

Thus, the date of 30 September 2023 at 8:00 PM in the North American Central Standard time zone (CST) would be 2023-09-30T20:00:00-06:00

When you schedule the date and time, you can't use your current date and time. For example, if it is 8:00 AM on 12 June, then the scheduled date and time must be after 8:00 AM on 12 June. If you define both the deprecation_at and obsolescence_at dates and times, the obsolescence_at date must be after the deprecation_at date and time.

The following example imports a custom image with the name of example-image, source location of cos://us-south/buckettesttest/livecd.ubuntu-cpc.azure.vhd, and the operating system for the image is ubuntu-16-04-amd64. The image is scheduled to be deprecated on 2023-11-28T15:10:00.000Z. The image is scheduled to be obsolete on 2023-11-28T15:10:00.000Z.

• Schedule a status change to deprecated.

  resource "ibm_is_image" "example" {
    name               = "example-image"
    href               = "cos://us-south/buckettesttest/livecd.ubuntu-cpc.azure.vhd"
    operating_system   = "ubuntu-16-04-amd64"
    deprecated_at      = "2023-11-28T15:10:00.000Z"
  }
  

• Schedule a status change to obsolete.

  resource "ibm_is_image" "example" {
    name               = "example-image"
    href               = "cos://us-south/buckettesttest/livecd.ubuntu-cpc.azure.vhd"
    operating_system   = "ubuntu-16-04-amd64"
    obsolescence_at    = "2023-11-28T15:10:00.000Z"
  }
  

Validating an imported custom image by using the UI

After you import a custom image, you can view the checksum that was generated for the image when it is imported to IBM Cloud VPC.

If you generate a checksum locally for your image before you import it, you can compare the two checksums to make sure that they are identical. Matching checksums indicate that the image is unaltered.

1. In IBM Cloud console, go to Menu icon > VPC Infrastructure > Compute > Images.

2. On the Custom images tab, from your list of custom images, click the name of the custom image that you want to validate.

3. In the image details side panel, locate the Checksum (SHA256) field. You see content similar to, 6809606da67eb83670e6249e54e94043eb43c0471669fb96ea4050c4c07e2df7.

   For z/OS Wazi aaS custom image only: You cannot validate the checksum of the imported custom images that are deployed from Wazi Image Builder.

4. Compare the Checksum (SHA256) value to the output that is generated when you calculate a checksum for the image locally.

   • Example Linux command: sha256sum ubuntu_image.qcow2
   • Example Mac command: shasum -a 256 ubuntu_image.qcow2
   • You receive output similar to: 6809606da67eb83670e6249e54e94043eb43c0471669fb96ea4050c4c07e2df7

5. Create a virtual server instance or a bare metal server by using this image. For more information, see Create a virtual server instance or Creating Bare Metal Servers on VPC.

Validating an imported custom image by using the CLI

After you import a custom image, you can view the checksum that was generated for the image when it is imported to IBM Cloud VPC.

If you generate a checksum locally for your image before you import it, you can compare the two checksums to make sure that they are identical. Matching checksums indicate that the image is unaltered.

To validate an imported custom image by using the CLI, use the ibmcloud is image command.

First, view the details of the imported custom image you want to validate. Specify the name or ID of the custom image to be created by using the IMAGE variable.

ibmcloud is image IMAGE

For more information, see ibmcloud is imagein the VPC CLI reference page.

The following example views the details of a custom image with the ID of r134-1d1e92e9-6550-4d06-8483-d674310045fd.

ibmcloud is image r134-1d1e92e9-6550-4d06-8483-d674310045fd

Getting image r134-1d1e92e9-6550-4d06-8483-d674310045fd under account Rios IMSLess as user gbgrout@ibm.com...

ID                             r134-589548bd-9241-4ad7-a610-1df6ba020793
Name                           my-image-from-volume-cli-1
CRN                            crn:v1:staging:public:is:us-south:a/efe5afc483594adaa8325e2b4d1290df::image:r134-589548bd-9241-4ad7-a610-1df6ba020793
Status                         available
Operating system               Name             Architecture   Vendor   Version                 Dedicated host only
                               centos-7-amd64   amd64          CentOS   7.x - Minimal Install   false

Source volume                  ID                                          Name
                               r134-6438d80f-4433-4445-be2f-0cca05afff3e   transpose-clubhouse-putt-repent

Created                        2023-03-16T01:11:03+05:30
Deprecation Date               2023-03-01T06:11:28+05:30
Obsolescence Date              2023-12-31T06:11:28+05:30
Visibility                     private
Owner type                     user
Minimum provisioned size(GB)   250
SHA256 Checksum                774d44ac0d55f2bfe869b995565715e5d9970ec23ce7127b2e2776b2618a9f7c
File size(GB)                  2
Encryption                     none
Resource group                 11caaa983d9c4beb82690daab08717e9
Resource type                  image
Catalog Offering Managed       false

Compare the returned Checksum (SHA256) value to the output that is generated when you calculate a checksum for the image locally.

• Example Linux command: sha256sum ubuntu_image.qcow2
• Example Mac command: shasum -a 256 ubuntu_image.qcow2
• You receive output similar to: 6809606da67eb83670e6249e54e94043eb43c0471669fb96ea4050c4c07e2df7

After you validate the Checksum (SHA256), use the image to create a virtual server. See Creating a virtual server instance by using the CLI.

Validating an imported custom image by using the API

After you import a custom image, you can view the checksum that was generated for the image when it is imported to IBM Cloud VPC.

If you generate a checksum locally for your image before you import it, you can compare the two checksums to make sure that they are identical. Matching checksums indicate that the image is unaltered.

To validate as custom image by using the API, use List all images.

For the $image_id, specify the ID of the custom image you want to validate.

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

Compare the returned Checksum (SHA256) value to the output that is generated when you calculate a checksum for the image locally.

• Example Linux command: sha256sum ubuntu_image.qcow2
• Example Mac command: shasum -a 256 ubuntu_image.qcow2
• You receive output similar to: 6809606da67eb83670e6249e54e94043eb43c0471669fb96ea4050c4c07e2df7

After you validate the Checksum (SHA256), use the image to create a virtual server. See Creating a virtual server instance by using the API.