Managing custom images

Managing custom images by using the UI

You can manage an image by using the IBM Cloud console.

1. In IBM Cloud console, go to Navigation Menu icon > Infrastructure > Compute > Images.
2. On the Custom images tab, click the Actions icon for a specific image and select from the available options. Encrypted custom images are identified by a lock icon after the image name. You can select from the following actions:

Listing custom images by using the CLI

You can list all of the IBM Cloud VPC custom images in your region by using the command-line interface (CLI).

To list all custom images by using the CLI, use the ibmcloud is images command. Custom images are private to the account where they are created, so the --visibility option is private.

ibmcloud is images --visibility private

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

Listing all images by using the API

You can list all of the IBM Cloud VPC images in your region by using the application programming interface (API).

To list all images by using the API, use List all images. Custom images are private to the account where they are created, so you can set the visibility property to private to retrieve only custom images.

curl -X GET \
”$vpc_api_endpoint/v1/images?version=2022-11-21&generation=2" \
-H "Authorization: Bearer $iam_token"

Listing all images by using Terraform

You can list all of the IBM Cloud VPC images in your region by using Terraform.

To list all images by using Terraform, use the Terraform data source command ibm_is_images. Custom images are private to the account where they are created, so you can set the visibility attribute to private to retrieve only custom images.

data "ibm_is_images" "images" {
  visibility = "public"
}

Viewing custom image details by using the UI

You can view the following details of a custom image:

• Name and ID
• Assigned resource group
• Size
• Location
• Creation date
• Operating system and version
• Encryption type
• Deprecation date (if set)
• Obsolescence date (if set)

You can edit the name of the custom image, adds tags for searchability, and view and copy the unique Cloud Resource Name (CRN). The SHA256 checksum value for the image is accessible.

To view details for a custom image, complete the following steps.

1. In IBM Cloud console, go to Navigation Menu icon > Infrastructure > Compute > Images.
2. On the Custom images tab, click the name of a custom image to view details about that image.
3. On the Image details page you can edit the name of the image, add tags, and copy the CRN for the image.
4. From the Actions menu of the Image details page, you can create a virtual server instance from the custom image or deleting the image. For a full list of possible actions, see Managing custom images by using the UI.

Viewing custom image details by using the CLI

You can view the details of a custom image, such as name and ID, operating system and version, encryption status, deprecation or obsolescence dates, and assigned resource group, by using the command-line interface (CLI).

To view the details of a custom image by using the CLI, use the ibmcloud is image command. Specify the name or ID of the custom image with the IMAGE variable.

ibmcloud is image IMAGE

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

Retrieving custom image details by using the API

You can view the details of a custom image, such as name and ID, operating system and version, encryption status, deprecation or obsolescence dates, and assigned resource group, by using the application programming interface (API).

To retrieve the details of a specific custom image by using the API, use Retrieve an image. For the $image_id variable, specify the ID of the custom image that you want to retrieve.

curl -X GET \
”$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" \
-H "Authorization: Bearer $iam_token"

Retrieving custom image details by using Terraform

You can view the details of a custom image, such as name and ID, operating system and version, encryption status, deprecation or obsolescence dates, and assigned resource group, by using Terraform.

To view the details of an image by using Terraform, use the Terraform data source command ibm_is_images. For the name variable, specify the name of the custom image that you want to retrieve.

data "ibm_is_images" "image_name" {
}

Sharing a custom image to a private catalog by using the UI

You can share an existing IBM Cloud VPC custom image to an existing private catalog. If you don't already have a private catalog, see Onboarding a virtual server image for VPC.

The Share image to private catalog action is not available for the following images:

• The image is already shared with a private catalog. An image in a private catalog can exist in only one version within one product offering in one private catalog. You must remove the image from the version it is in first before that image can be shared in a different version.
• The image is encrypted.
• The image is not an x86 image.

To share a custom image to a private catalog, complete the following steps.

1. In IBM Cloud console, go to Navigation Menu icon > Infrastructure > Compute > Images.
2. On the Custom images tab, click the Actions icon and select Share to catalog.
3. On the Share image to private catalog page, select a Private catalog from the list of available private catalogs.
4. Enter a version number in Software version.
5. Click Create catalog offering to share the image to the private catalog.
6. After the image is created, click Validate image.

This process shares only the custom image to the private catalog. The validation process occurs within the private catalog. Clicking Validate image takes you to a new page and from this screen, you can start with Step 3: Validate the virtual server image in Onboarding a virtual server image for VPC to complete the validation process.

Sharing a custom image to a private catalog by using the CLI

You can only share a custom image to a private catalog from IBM Cloud VPC by using the UI. For more information about onboarding to a private catalog using the CLI, see Onboarding software to your account.

Sharing a custom image to a private catalog by using the API

You can only share a custom image to a private catalog from IBM Cloud VPC by using the UI. For more information about onboarding to a private catalog using the API, see Onboarding software to your account.

Sharing a custom image to a private catalog by using Terraform

You can only share a custom image to a private catalog from IBM Cloud VPC by using the UI. For more information about onboarding to a private catalog using the Terraform, see Onboarding software to your account.

Schedule a custom image lifecycle status change in the UI

You can schedule either a single image lifecycle status change or schedule the status changes for the entire lifecycle of the image. You can make an immediate status change only if you didn't schedule a future status change.

Follow these steps to schedule a single status change:

You can schedule a single status change for an image.

1. In IBM Cloud console, go to Navigation Menu icon > Infrastructure > Compute > Images.
2. On the Custom images tab, click the Actions icon for a specific image and select from the available options.
3. Select Schedule lifecycle.
4. In Image status, select the status change for the image.
5. In Deprecation details, select whether to change status Immediately or to Schedule future date.
6. If you selected Schedule future date, you need to fill out the following:
   • Select either By calendar date or By number of days.
     • If you selected By calendar date, enter the date and time information. This is the date and time when the status change will occur.
     • If you selected By number of days, put in the number of days that will pass before the status is changed.
7. Click Save.

Follow these steps to schedule the entire lifecycle of the image:

You can schedule the complete lifecycle for the image. The image is first deprecated and then changes to obsolete according to the schedule that you define. Use the following steps to schedule a lifecycle change.

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

2. On the Custom images tab, click the Actions icon for a specific image and select from the available options.

3. Select Schedule lifecycle.

4. Select Schedule complete lifecycle.

   • If you selected By calendar date, enter the date and time for when you want the status change occur.
   • If you selected By number of days, put in the number of days that you want to pass before the status is changed.

   The date for obsolescence must be after the deprecation date.

5. Click Schedule.

Change the custom image lifecycle status by using the CLI

You can change the lifecycle status of an IBM Cloud VPC custom image by using the command-line interface (CLI). You can make an immediate status change by using the ibmcloud is image-deprecate or ibmcloud is image-obsolete commands. You can also schedule these status changes for a future date and time by using the ibmcloud is image-update command. Specify the name or ID of the custom image with the IMAGE variable.

To make an immediate status change, use one of the following examples.

You can make an immediate status change only if a future status change is not scheduled. To remove a scheduled status change, see Remove a scheduled custom image lifecycle status change by using the CLI. After you remove the scheduled status change, you can make an immediate status change.

• Change the image lifecycle status to deprecate.

  ibmcloud is image-deprecate IMAGE
  

• Change the image lifecycle status to obsolete.

  ibmcloud is image-obsolete IMAGE
  

To schedule a status change, use the following example.

For the deprecate-at or obsolete-at option, 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 UTC 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 scheduling the date and time, you can't use your current date and time. For example, if it is 8:00 AM on June 12, then the scheduled date and time must be after 8:00 AM on June 12. If you define both the deprecate-at and obsolete-at dates, the obsolete-at date must be after the deprecate-at date.

ibmcloud is image-update IMAGE [--deprecate-at YYYY-MM-DDThh:mm:ss+hh:mm] [--obsolete-at YYYY-MM-DDThh:mm:ss+hh:mm]

If you want to change the deprecate-at and obsolete-at date and time entries, you can run these commands again. The previous dates and times are then replaced with the new dates and times.

Remove a previously scheduled custom image lifecycle status change by using the CLI

You can remove a scheduled status change by using the --reset-deprecate-at or --reset-obsolete-at options. If you use either of these options with the ibmcloud is image-update command, the date and time are removed from the image. The image is no longer scheduled for that status change.

ibmcloud is image-update IMAGE [--reset-deprecate-at] [--reset-obsolete-at]

If you use both the --reset-deprecate-at and --reset-obsolete-at options, the image status returns to available.

Change the custom image lifecycle status by using the API

You can change the lifecycle status of an IBM Cloud VPC custom image by using the application programming interface (API). You can make an immediate status change or schedule a status change to happen later.

To make an immediate status change, use one of the following examples. For the$image_id variable, specify the ID of the custom image for the status change.

You can make an immediate status change only if a future status change is not scheduled. To remove a scheduled status change, see Remove a scheduled custom image lifecycle status change by using the API. After you remove the scheduled status change, you can make an immediate status change.

• Change image lifecycle status to deprecated.

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

• Change the image lifecycle status to obsolete.

  curl -X POST "$vpc_api_endpoint/v1/images/$image_id/obsolete?version=2023-12-21&generation=2" -H “Authorization: Bearer $iam_token”
  

To schedule a status change, use one of the following examples.

For the deprecation_at or obsolescence_at properties, 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 UTC 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 scheduling the date and time, you can't use your current date and time. For example, if it is 8:00 AM on June 12, then the scheduled date and time must be after 8:00 AM on June 12. 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.

• Schedule a status change to deprecated.

  curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{
   "deprecation_at": "2023-03-01T06:11:28+05:30" }'
  

• Schedule a status change to obsolete.

  curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{
   “obsolescence_at": "2023-12-31T06:11:28+05:30" }'
  

  If you want to change the deprecation_at and obsolescence_at date and time entries, you can run these commands again. The previous dates and times are replaced with the new dates and times.

Remove previously scheduled custom image lifecycle status by using the API

Make a PATCH /images request to remove any scheduled status change by updating deprecation_at or obsolescence_at to null. This property change removes the date and time from the image and the image is no longer scheduled for that status change.

• To change an image from deprecated to available, change the deprecation_at property to null.

  curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{ "deprecation_at": null }'
  

• To change an image from obsolete to its previous state, change obsolescence_at to null. If the image previously contained a value other than null for deprecation_at, then this property change removes the obsolete state and changes it back to deprecated. If the previous state was available, meaning the image was moved from available directly to obsolete, then this property change moves from obsolete back to available.

  curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{ “obsolescence_at": null }'
  

• To change an image that has both the deprecation_at or obsolescence_at properties set back to available, you must update both the deprecation_at or obsolescence_at properties.

  curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2022-11-21&generation=2" -H "Authorization: Bearer $iam_token" -d '{ "deprecation_at": null, “obsolescence_at": null }'
  

Change the custom image lifecycle status using Terraform

To make an immediate status change using Terraform, use the ibm_is_image_deprecate or ibm_is_image_obsolete resource commands. use one of the following examples. For the name variable, specify the name of the custom image for the status change.

You can make an immediate status change only if a future status change is not scheduled. To remove a scheduled status change, see Remove a scheduled custom image lifecycle status change by using Terraform. After you remove the scheduled status change, you can make an immediate status change.

• Change image lifecycle status 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"
    encrypted_data_key = "eJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0="
    encryption_key     = "crn:v1:bluemix:public:kms:us-south:a/6xxxxxxxxxxxxxxx:xxxxxxx-xxxx-xxxx-xxxxxxx:key:dxxxxxx-fxxx-4xxx-9xxx-7xxxxxxxx"
  }
  resource "ibm_is_image_deprecate" "example" {
    image               = ibm_is_image.example.id
  }
  

• Change the image lifecycle status 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"
    encrypted_data_key = "eJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0="
    encryption_key     = "crn:v1:bluemix:public:kms:us-south:a/6xxxxxxxxxxxxxxx:xxxxxxx-xxxx-xxxx-xxxxxxx:key:dxxxxxx-fxxx-4xxx-9xxx-7xxxxxxxx"
  }
  resource "ibm_is_image_obsolete" "example" {
    image               = ibm_is_image.example.id
  }
  

To schedule a status change, use one of the following examples.

For the deprecation_at or obsolescence_at attribute, 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 UTC 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 scheduling the date and time, you can't use your current date and time. For example, if it is 8:00 AM on June 12, then the scheduled date and time must be after 8:00 AM on June 12. 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.

• 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"
    deprecation_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"
  }
  

  If you want to change the deprecation_at and obsolescence_at date and time entries, you can run these commands again. The previous dates and times are replaced with the new dates and times.

Remove previously scheduled custom image lifecycle status using Terraform

To remove any scheduled status change, update the deprecation_at or obsolescence_at attributes to null. This attribute change removes the date and time from the image and the image is no longer scheduled for that status change.

• To change an image from deprecated to available, change the deprecation_at property to null.

  resource "ibm_is_image" "example" {
    name               = "example-image"
    href               = "cos://us-south/buckettesttest/livecd.ubuntu-cpc.azure.vhd"
    operating_system   = "ubuntu-16-04-amd64"
    deprecation_at       = null
  }
  

• To change an image from obsolete to its previous state, change obsolescence_at to null. If the image previously contained a value other than null for deprecation_at, then this attribute change removes the obsolete state and changes it back to deprecated. If the previous state was available, meaning the image was moved from available directly to obsolete, then this attribute change moves from obsolete back to available.

  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    = null
  }
  

• To change an image that has both the deprecation_at or obsolescence_at properties set back to available, you must update both the deprecation_at or obsolescence_at attributes.

  resource "ibm_is_image" "example" {
    name               = "example-image"
    href               = "cos://us-south/buckettesttest/livecd.ubuntu-cpc.azure.vhd"
    operating_system   = "ubuntu-16-04-amd64"
    deprecation_at     = null
    obsolescence_at    = null
  }