Creating an image from a volume

Choosing the source for your custom image

Use the UI to import your custom image by choosing to create and import an image from a volume.

1. In the IBM Cloud console, click the Navigation Menu > VPC Infrastructure Compute > Images**.

2. On the Custom images tab, click Create. The Import custom image page is displayed.

3. Complete the required fields on the Import custom images page (see Table 1), and then continue with one of the Source options.

Create an image from a virtual server instance boot volume

When you select the Virtual server instance boot volume as the source of your custom image, a list of instances displays. To create an image from the instance's boot volume:

1. On the Import custom image page, select Virtual server instance boot volume (default).

   To create an image of the boot volume associated with an instance, the virtual server instance must be stopped.

2. Optionally, stop a running instance by clicking the overflow menu (ellipsis) and click Stop.

3. Select an instance from the list. You're selecting the boot volume of the instance.

4. Select the encryption type, either customer-managed encryption or IBM-managed encryption (see Table 2).

5. On the side panel, click Create custom image.

Create an image from the list of boot volumes

When you select a Block Storage boot volume as the source of your custom image, a list of Block Storage volumes displays.

To create an image from the volume:

1. On the Import custom image page, select Block Storage boot volume.

   A list of Block Storage volumes shows attached Boot and Data volumes. Unattached volumes appear with a dash (-). To create an image from a volume:

   • The volume must be a boot volume
   • The volume must have an available status
   • The volume must be attached to a virtual server instance
   • The instance must be stopped

2. Optionally, stop a running instance by clicking the overflow menu (ellipsis) and click Stop attached instance. Click refresh and select the volume.

3. Select the volume from the list.

4. Select the encryption type, either customer-managed encryption or IBM-managed encryption (see Table 2).

5. On the side panel, click Create custom image.

Select the encryption type

To complete your image from volume, select either IBM-managed encryption or customer-managed encryption. Table 2 describes these options as they appear in the UI.

For more information, see Setting up your key management service and keys.

View and use your image from volume

When the image from a volume is created, it appears in the list of custom images.

1. In the IBM Cloud console, go to the **menu > VPC Infrastructure > Compute > Images.

2. On the Custom images tab, click the image name to see the volume from which it was created. The image details panel links to the source volume.

To use this image when you create a new instance, select it as the operating system type when you create an instanceL

1. In the IBM Cloud console, go to the **menu > VPC Infrastructure > Compute > Virtual server instances.

2. Click Create. For more information about how to provision a new virtual server instance, see Creating virtual server instances in the UI. For the Operating system, select the Custom image tile.

3. Click Select custom image and select the image from volume that you created.

Before you begin

1. Make sure that you downloaded, installed, and initialized the following CLI plug-ins:

   • IBM Cloud CLI
   • The infrastructure-service plug-in

   For more information, see the CLI Reference.

   After you install the vpc-infrastructure plug-in, set the target to generation 2 by running the command ibmcloud is target --gen 2.

2. Make sure that you created an IBM Cloud VPC.

Create an image from a boot volume that is attached to an instance

1. To locate the instance that you want to create an image from, list the instances in the region. Take note of the instance ID in the command output.

   ibmcloud is instances
   

2. Stop the running instance before you create the image from the volume.

   ibmcloud is instance-stop INSTANCE_ID
   

3. Run the image-create command to create an image of a boot volume. Specify the ID of the source volume.

   ibmcloud is image-create IMAGE_NAME [--source-volume VOLUME_ID]
   

   Example:

   $ ibmcloud is image-create test-ifv-vol1 --source-volume ecc68c2f-96a1-4862-bc86-14f47e5d9ed8
   
   Creating image test-ifv-vol1 in resource group  under account Test Account as user test.user@ibm.com...
   ID                 5b2fd4ee-c636-44c4-9673-453fca36832e
   Name               test-ifv-vol1
   CRN                crn:v1:bluemix:public:is:us-south:a/a123456::image:5b2fd4ee-c636-44c4-9673-453fca36832e
   Status             pending
   Status reason      Code                   Message                                                More info
                      image_request_queued   The image request is accepted and waiting for system   -
                                             resources to become available.
   Operating system   Name             Architecture   Vendor   Version                 Dedicated host only
                      centos-8-amd64   amd64          CentOS   8.x - Minimal Install   false
   Source volume      ID                                     Name
                      ecc68c2f-96a1-4862-bc86-14f47e5d9ed8   aa-1-bx-boot-1617035447000
   Created            2021-05-20T09:43:16+08:00
   Visibility         private
   File size(GB)      -
   Encryption         none
   Resource group     f22cf48f-8836-4527-9131-1d7c73ba85e9
   

Schedule custom image lifecycle status changes by using the CLI

When you import a custom image by using the command-line interface (CLI), you can also schedule the lifecycle status changes of the IBM Cloud VPC custom image at the same time by using options of the ibmcloud is image-create command.

Specify the name of the custom image to be created by using the IMAGE_NAME variable and the source by using the --source-volume option to indicate that the source is an existing boot volume.

To schedule the deprecate-at or obsolete-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 deprecate-at and obsolete-at dates and times, the deprecate-at date must be after the obsolete-at date and time.

ibmcloud is image-create IMAGE_NAME [--source-volume VOLUME_ID] [--deprecate-at YYYY-MM-DDThh:mm:ss+hh:mm] [--obsolete-at YYYY-MM-DDThh:mm:ss+hh:mm]

Before you begin

Before you can use the API, you must take some preliminary steps. For more information, see API prerequisites.

Creating an image from volume when you create an instance (API)

Follow these steps to create an image from volume when you create a new instance. The new instance's boot volume is used for the image, which inherits the encryption from the boot volume. In this scenario, the boot volume uses the default IBM-managed encryption, which is inherited by the new image. You can also specify your own root encryption key in the POST/images call. For more information, see Create an image from volume and use your root encryption key.

This procedure:

1. Creates an instance and uses its boot volume ID as the source volume.
2. Stops the running instance.
3. Creates an image with the ID of the boot volume. In this scenario, the boot volume is encrypted with the default IBM-managed encryption. If the boot volume was encrypted with a customer root key, that root key is used to encrypt the new image. The API response displays the CRN of the root key.

curl -X POST \
"$vpc_api_endpoint/v1/instances?version=2021-05-20"\
-H "Authorization: Bearer $iam_token"\
-d '{
   "name":"test-ifv-instance",
   "profile":{
      "name":"bx2-2x8"
   },
   "vpc":{
      "id":"6054c339-8a17-4c75-958c-4a23358a37ed"
   },
   "image":{
      "id":"524d52aa-b267-4801-a7d2-6d4fe75baf65"
   },
   "zone":{
      "href":"https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3"
   },
   "primary_network_interface":{
      "name":"ifv-nic",
      "subnet":{
         "id":"7382-4b33d349-1752-4bf9-ab73-751ec065e193"
      }
   }
}'

curl -X POST \
"$vpc_api_endpoint/v1/instances/{instance-id}/gen/actions?version=2021-05-20"
-H "Authorization: Bearer $iam_token"\
-d '{
   "type":"stop"
}'

curl -X POST \
"$vpc_api_endpoint/v1/images?version=2021-05-20"
-H "Authorization: Bearer $iam_token"\
-d '{
    "name": "test-ifv-boot-volume",
    "source_volume": {
    	"id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7"
    }
}``

{
  "created_at": "2021-05-20T00:05:13.873893Z",
  "crn": "crn:[...]",
  "encryption": "none",
  "file": {},
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
  "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
  "name": "test-ifv-boot-volume",
  "operating_system": {
    "architecture": "amd64",
    "display_name": "CentOS 8.x - Minimal Install (amd64)",
    "family": "CentOS",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/centos-8-amd64",
    "name": "centos-8-amd64",
    "vendor": "CentOS",
    "version": "8.x - Minimal Install"
  },
  "resource_group": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771",
    "id": "3fad3f2204eb4998c3964d254ffcd771",
    "name": "Default"
  },
  "status": "pending",
  "status_reasons": [],
  "visibility": "private",
  "source_volume":  {
    "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
    "crn": "crn:[...]",
    "href": "",
    "name": "ifv-boot-vol"
  }
}

Creating an image from volume and specifying your own encryption key

In this scenario, you're creating an image from a volume and specifying your root key in the POST /images call.

The example request specifies the CRN of the root key in the encryption_key parameter:

curl -X POST \
"$vpc_api_endpoint/v1/images?version=2021-05-20"
-H "Authorization: Bearer $iam_token"\
-d '{
    "name": "test-ifv-boot-volume",
    "source_volume": {
        "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7"
    },
    "encryption_key":{
      "crn":"crn:[...key:...]"
    },
}`

The response includes information about the root key:

{
  "created_at": "2021-05-20T00:05:13.873893Z",
  "crn": "crn:[...]",
  "encryption_key": {
    "crn": "crn:[...key:...]"
    },
  "encryption": "user_managed",
  "file": {},
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
  "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
  "name": "test-ifv-boot-volume",
  "operating_system": {
    "architecture": "amd64",
    "display_name": "CentOS 8.x - Minimal Install (amd64)",
    "family": "CentOS",
    "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/centos-8-amd64",
    "name": "centos-8-amd64",
    "vendor": "CentOS",
    "version": "8.x - Minimal Install"
  },
  "resource_group": {
    "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771",
    "id": "3fad3f2204eb4998c3964d254ffcd771",
    "name": "Default"
  },
  "status": "pending",
  "status_reasons": [],
  "visibility": "private",
  "source_volume":  {
    "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7",
    "crn": "crn:[...]",
    "href": "",
    "name": "ifv-boot-vol"
  }
}

Creating an image from a volume of an existing instance

You can also create an image from a boot volume that is attached to an existing instance. This procedure:

1. Lists all instances and then gets the ID of a boot volume that is attached to an available running instance.
2. Stops the running instance.
3. Creates an image by using the ID of the boot volume image.

curl -X GET \
"$vpc_api_endpoint/v1/instances?version=2023-08-04&generation=2" \
-H "Authorization: Bearer $iam_token"

curl -X GET \
"$vpc_api_endpoint/v1/instances/$instance_id?version=2023-08-04&generation=2"\
-H "Authorization: Bearer $iam_token"

  "volume_attachments": [
    {
      "device": {
        "id": "a8a15363-a6f7-4f01-af60-715e85b28141"
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-a8d7-703aac843651/volume_attachments/7389-a8a15363-a6f7-4f01-af60-715e85b28141",
      "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
      "name": "my-boot-volume-attachment",
      "volume": {
        "crn": "crn:[...]",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "name": "my-boot-volume"
      }
    }
  ]

curl -X POST \
"$vpc_api_endpoint/v1/instances/$instance_id/actions?version=2023-08-04&generation=2"\ 
-H "Authorization: Bearer $iam_token"\
-d '{
  "type": "stop"
  }'

curl -X POST \
"$vpc_api_endpoint/v1/images?version=2021-05-20"
-H "Authorization: Bearer $iam_token"\
-d '{
    "name": "test-ifv-boot-volume",
    "source_volume": {
    	"id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7"
    }
}`

Scheduling custom image lifecycle status changes by using the API

When you create an image from volume by using the application programming interface (API), you can schedule the lifecycle status changes of the IBM Cloud VPC image from volume at the same time.

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 source.volume subproperty to indicate the source of the image from volume.

To schedule 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.

curl -X POST "$vpc_api_endpoint/v1/images?version=2023-02-21&generation=2"\
-H "Authorization: Bearer $iam_token"\
-d '{
      "name": "test-ifv-boot-volume",
      "source_volume": {
    	  "id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7"
      },
      "deprecation_at": "2023-03-01T06:11:28+05:30",
      "obsolescence_at": "2023-12-31T06:11:28+05:30"
    }'