Managing image from a volume

Images from volumes have their own lifecycles that you can manage.

IAM permissions for creating an image from volume.
Make an immediate or schedule a lifecycle status change.
Cancel an image queued for creation.
Delete an image from volume.

IAM permissions for creating an image from volume

IAM enables you to securely authenticate users for platform services and control access to resources consistently across IBM Cloud®. The following table shows the access requirements for creating an image from a volume.

Table 2. IAM user permissions
Operation	Action	API call	IAM access roles
Create an instance	is.instance.instance.create	`POST/instances`	Administrator, Editor
List all instances	is.instance.instance.list	`GET/instances`	Administrator, Editor, Operator, Viewer
Create an image from an instance boot volume	is.image.image.create	`POST/images`	Administrator, Editor
List all images	is.image.image.list	`GET/images`	Administrator, Editor, Operator, Viewer
Delete image	is.image.image.delete	`DELETE/images`	Administrator, Editor
Schedule deprecation	is.image.image.deprecate	`POST/images` with `deprecation_at` specified	Administrator, Editor
Schedule obsolescence	is.image.image.obsolete	`POST/images` with `obsolescence_at` specified	Administrator, Editor

Image from volume lifecycle states

The following table describes the lifecycle states for custom images that are created from a volume.

Table 3. Image lifecycle states
Status	Explanation
Available	Image is available when you provision an instance.
Pending	The image is being created. If successful, the image is available. Otherwise, creation failed.
Failed	Image creation failed.
Deleting	The image is being deleted.
Deprecated	You can use the image to create an instance. Using the `deprecated` status can discourage use of the image before the status changes to `obsolete`.
Obsolete	You can't use the image to a create an instance. If you try to use an obsolete image to create an instance, you receive a message that the image can't be used to create an instance. This status allows a reversible disabling of an image before you delete the image.

Scheduling an image from volume lifecycle status by using the UI

You can schedule either a single image lifecycle status change or schedule the status changes for the entire lifecycle of the image.

Use the following steps to schedule a single status change:

You can schedule a single status change for an image.

In IBM Cloud console, go to Navigation Menu icon > VPC Infrastructure > Compute > Images.
On the Custom images tab, click the Actions icon for a specific image and select from the available options.
Select Schedule lifecycle.
In Image status, select the status change for the image.
In Deprecation details, select whether to change status Immediately or to Schedule future date.
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.
Click Save.

Use the following 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.

In IBM Cloud console, go to Navigation Menu icon > VPC Infrastructure > Compute > Images.
On the Custom images tab, click the Actions icon for a specific image and select from the available options.
Select Schedule lifecycle.
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.
Click Schedule.

Changing an image from volume lifecycle status by using the CLI

You can change the lifecycle status of an IBM Cloud VPC image from volume 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.

Removing previously scheduled image from volume lifecycle statuses 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.

Changing an image from volume lifecycle status by using the API

You can change the lifecycle status of a IBM Cloud VPC image from volume 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.

Removing previously scheduled image from volume lifecycle statuses 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 }'

Performance considerations

Several factors can impact how quickly your image from volume is queued and created, such as the size of the image and number of jobs in the queue. If an image is taking longer than you want to wait, you can cancel the job.

Performance during image creation

When you create the image, the API status_reasons parameter indicates image_request_queued, with a message "The image request is accepted and waiting for system resources to become available". When you see this message, it might take a while for the job to start. The following table provides some guidelines that are based on image size. Check for an in_progress status to see whether the image is being created. Again, depending on the size of the image, it might take a while before the image is available.

Table 1. Estimated wait time for image creation
Image size	Estimated time until image is available
5 GB	5 min
10 GB	10 min
25 GB	25 min
50 GB	50 min
75 GB	1 hr 15 min
100 GB	1 hr 40 min

The time for the job to start is about 30 seconds. This time does not reflect traffic in the queue, which can increase the estimate. Most jobs start within 5 - 10 minutes. If it takes longer, cancel the image creation.

Cancelling an image that is queued for creation

You can cancel the image creation by deleting the image if the underlying job didn't start yet. For images in a pending state, the GET/images API call returns an image_request_queued reason code. You can delete the pending image with DELETE/image{image_id}. Alternatively, you can use the UI or CLI to delete the image that is in a pending state.

Deleting an image from volume by using the UI

Delete an image from a volume from the list of custom images. You can delete images in that are while they are being created (pending state) and available images.

Go to the list of custom images. In the IBM Cloud console, go to Navigation Menu icon > VPC Infrastructure > Compute > Images.
On the Custom images tab, locate the image that you want to delete. From the overflow menu (ellipsis), select Delete.

Deleting an image from volume by using the CLI

Locate the image from volume in the list of images.
```
ibmcloud is images
```
Delete the image by ID.
```
ibmcloud is image-delete IMAGE_ID
```

Deleting an image from volume by using the API

Specify a DELETE/images call and specify the ID of the image that was created from the boot volume.

Locate the ID of the image from volume:
```
GET/images
```
Delete the image by ID:
```
DELETE/image/{image_id}
```

Next steps

Preview the end-to-end process for creating an image from volume, then you can use the image when you create a new virtual server instance. For more information, see the Image from volume tutorial.