Importing a boot image

IBM Power Virtual Server in IBM data center

IBM Power Virtual Server Private Cloud in Client location

You can import a custom operating system (OS) image from an IBM Cloud Object Storage (COS) bucket by using the IBM® Power® Virtual Server user interface, CLI, or API, instead of using an IBM-provided stock image. After you import the boot image, you can use it to create a Power Virtual Server virtual server instance (VSI).

When you import a boot image, you select a storage tier and storage pool for the image. Power Virtual Server creates the boot volumes from the imported boot image in the storage pool that you specify during the import. You cannot change the storage tier or storage pool after you import the image. A VSI can have disks from multiple storage types. All Power Virtual Server data centers support Tier 0, Tier 1, Tier 3, and Fixed IOPs storage types.

Boot image import and export are long-running, asynchronous operations. Power Virtual Server monitors these operations across all workspaces in your account. You can run only one import or export operation at a time in a workspace. You cannot start another operation in that workspace until the current operation is complete.

Before you begin

Before you import a boot image, verify that you meet the following prerequisites:

  • Upload your boot image file to an IBM Cloud Object Storage bucket. Supported file formats are .ova, .ova.gz, .tar, .tar.gz, and .tgz. For more information, see Create some buckets to store your data.

  • Generate Hash-based Message Authentication Code (HMAC) credentials for your COS instance. For more information, see Using HMAC credentials.

  • Create or use an existing Power Virtual Server workspace.

Importing a boot image by using the Power Virtual Server user interface

To import a boot image by using the Power Virtual Server user interface, complete the following steps:

  1. Log in to the IBM Cloud catalog with your IBM credentials.

  2. In the search box, type Power Virtual Server and click the Power Virtual Server tile.

  3. Click Workspaces in the navigation panel. The Workspaces page with a list of existing workspaces is displayed.

  4. Select the workspace to which you want to import the boot image. The "Virtual server instances" page of the selected workspace is displayed.

  5. Click Boot images in the navigation panel and click Import image. The "Import boot image" panel is displayed.

  6. In the "Import boot image" panel, complete the following steps in the Source section:

    1. Select the image OS from the Image OS drop-down list.

      If you select a SAP HANA or SAP NetWeaver image OS, you must select the self-certification checkbox.

    2. From the Region drop-down list, select the region that contains your COS bucket.

    3. Enter the file name of the image in the Image filename field. The image file name must not contain spaces.

      The supported file name extensions are .ova, .ova.gz, .tar, .tar.gz, and .tgz. You can compress image files by using gzip. For example: Aix_7200-03-02-1846_cldrdy_112018.ova.gz.

    4. Enter the name of your bucket in the Bucket name field. If your image file is stored in a subfolder in the bucket, specify the full path by using the bucketName/optional/folders format.

      To identify your bucket name, go to Navigation menu > Resource list > Storage and click your Cloud Object Storage instance name. Your buckets are listed on the Buckets tab.

    5. Copy the access_key_id value from your COS service credentials and paste it into the HMAC access key field.

      To find your service credentials, go to Navigation menu > Resource list > Storage, click your Cloud Object Storage instance name, and then go to Service credentials > View credentials.

    6. Copy the secret_access_key value from your COS service credentials and paste it into the HMAC secret access key field.

    7. Set Validate import with checksum file to On to verify the imported file against the checksum file. You must store the checksum file and the boot image file in the same COS bucket.

      You can generate the checksum file when you export the boot image file to the IBM Cloud Object Storage bucket. The checksum file name is based on the name of the boot image file and uses the .sha256 file extension.

      If you create your own boot image, you can create a checksum file and store it with your boot image in the same bucket. You can generate the checksum file by running the shasum -a 256 <filename> or sha256sum <filename> command.

      For more information about generating a checksum file, see Using the Power Virtual Server user interface to capture and export a VM.

      Validating the import file against the checksum file might increase the import time.

  7. Click Next.

  8. Enter the following information in the Destination section:

    1. In the Custom image name field, enter a name for the imported boot image.

    2. Optional: In the User tags field, enter tags to organize or categorize this boot image.

      User tags are visible to all users in the account. Do not include sensitive data in tag names.

    3. In the Tier field, select one of the following storage type options:

      • Tier 0 (25 IOPs / GiB)
      • Tier 1 (10 IOPs / GiB)
      • Tier 3 (3 IOPs / GiB)
      • Fixed IOPs (5000 IOPs)

      A VSI cannot use Tier 1 and Tier 3 storage types simultaneously. For more information, see Storage tiers.

    4. In the Storage pool field, select a storage pool option.

      Power Virtual Server places one or more custom image storage volumes in the storage pool based on the option that you select: Auto-select, Affinity, or Anti-affinity. The boot volume of any VSI that you deploy by using this image is created in the same storage pool. For more information about storage volumes, see Adding and managing storage volumes.

      The following storage pool options are available:

      • Auto-select: Creates the storage volume in a storage pool with sufficient capacity automatically.

      • Affinity: Identifies the storage pool for the boot volumes, based on an existing VSI or storage volume from your account. Power Virtual Server stores the custom image storage volumes in the same storage pool in which the affinity object exists. If the affinity object is a VSI, Power Virtual Server determines the storage pool based on the boot volume of the VSI.

      • Anti-affinity: Identifies one or more storage pools that you want to exclude. Power Virtual Server does not consider the excluded storage pools when placing boot volumes. The pools to exclude are identified based on existing VSIs or storage volumes in your account. When you select this option, Power Virtual Server excludes the storage pools where the anti-affinity objects exist when it creates the custom image storage volumes. If you use VSIs as the anti-affinity objects, Power Virtual Server excludes the storage pools based on the boot volume of each VSI.

  9. Click Import image.

    Large boot images might take longer to import. You might experience a delay before you receive a confirmation message.

The new boot image is listed on the Boot images page.

Importing a boot image by using the Power Virtual Server CLI

To import a boot image, run the ibmcloud pi image import command. To verify that the import is complete, run the ibmcloud pi image list command.

If you are using a bring-your-own-license (BYOL) SAP HANA or SAP NetWeaver image, add the --import-details option to the ibmcloud pi image import command to identify the image as SAP-certified.

Importing a boot image by using the Power Virtual Server API

To import a boot image from IBM Cloud Object Storage by using the API, use the Create a cos-image import job method with the required properties in the request body: imageName, imageFilename, and bucketName. For private buckets, you must specify accessKey and secretKey, which are the HMAC access key and secret key for your COS instance. For more information, see Using HMAC credentials.

curl -X POST \
  https://us-east.power-iaas.cloud.ibm.com/pcloud/v1/cloud-instances/$CLOUD_INSTANCE_ID/cos-images \
  -H "Authorization: Bearer $TOKEN" \
  -H "CRN: $CRN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "my-image-name",
    "imageFilename": "my-os-image-file.ova.gz",
    "bucketName": "my-cos-bucket-name",
    "region": "us-east",
    "accessKey": "my-cos-access-key",
    "secretKey": "my-cos-secret-key",
    "storageType": "tier3"
  }'

If you are using a bring-your-own-license (BYOL) SAP HANA or SAP NetWeaver image, include the importDetails object in the request body to identify the image as SAP-certified:

"importDetails": {
   "licenseType": "byol",
   "product": "Hana",
   "vendor": "SAP"
}

Viewing boot image import results

After you start a boot image import, the Status column on the Boot images page shows the import progress. To view details, click View details to open the "Ongoing job status" dialog. The dialog shows the following information:

  • Job ID
  • Operation type
  • Input resource
  • Creation time
  • Steps completed

To view the boot image import job details by using the CLI, use the ibmcloud pi image import-show command.

To view the boot image import job details by using the API, use the Get detail of last cos-image import job method.

Downloading a boot image from Cloud Object Storage

To download the boot image after you import it, complete the following steps:

  1. In the IBM Cloud dashboard, go to Resource list and click your Cloud Object Storage instance.

  2. In the bucket where you stored your boot image, click the boot image file.

  3. Click Download objects.

For more information about the Cloud Object Storage CLI command, see Download an object.