Creating an image from a volume

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.

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]
   

   See the following 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 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're scheduling the date and time, you can't use your current date and time. For example, if it is 8:00 AM on 12 June 2024, then the scheduled date and time must be after 8:00 AM on 12 June 2024. 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 begin, make sure that you set up your API environment.

Creating an image from a boot of an instance with the API

1. Locate the instance and boot volume that you want to create an image from. Get the list of the available instances with the list instance method.

   curl -X GET "$vpc_api_endpoint/v1/instances?version=2024-06-11&generation=2" -H "Authorization: Bearer $iam_token"
   

2. Take a note of the instance ID, and use it to retrieve the instance details.

   curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-06-11&generation=2" -H "Authorization: Bearer $iam_token"
   

   The response contains the name, ID, and other details of the boot volume in the volume_attachments section.

   "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"
       }
     }
   ]
   

3. If the instance is running, stop it by specifying the stop action in a POST /instances call:

   curl -X POST \
   "$vpc_api_endpoint/v1/instances/{instance-id}/gen/actions?ersion=2024-06-11&generation=2"
   -H "Authorization: Bearer $iam_token"\
   -d '{"type":"stop"}'
   

4. By using the boot volume ID, create an image. See the following example:

    curl -X POST "$vpc_api_endpoint/v1/images?version=2024-06-11&generation=2" 
    -H "Authorization: Bearer $iam_token" 
    -d '{
         "name": "my-image",
         "source_volume": {"id": "4fec84ef-baf9-405d-bf3b-9d5a60e068f7"}
         }`
   

   In the example response, source_volume indicates the boot volume that is used to create the image. Also, notice that the image encryption appears as none because the source volume used the default IBM-managed encryption. If you used you own root key, the response would show user-managed instead.

   {
    "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": "my-boot-volume"
      }
    }
   

Creating an image from volume and specifying your own encryption key

1. As described in the previous section, locate the instance, and boot volume information. Stop the instance.

2. Get your key management service instance ID and root key CRN.

   • Key Protect - Retrieving your instance ID and cloud resource name (CRN).
   • Hyper Protect Crypto Services - Retrieving your instance ID.

3. Make an API request to create an image. Specify the volume ID the CRN of the root key as shown in the following example.

   curl -X POST "$vpc_api_endpoint/v1/images?version=2024-06-11&generation=2" 
   -H "Authorization: Bearer $iam_token" 
       -d '{
            "name": "my-encrypted-image",
            "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"
      }
    }
   

Scheduling custom image lifecycle status changes with the API

When you create an image from a volume by using the application programming interface (API), you can schedule the lifecycle status changes of the custom image 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 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're scheduling the date and time, you can't use your current date and time. For example, if it is 8:00 AM on 12 June 2024, then the scheduled date and time must be after 8:00 AM on 12 June 2024. 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"
    }'