Creating a Linux custom image

You can create your own custom Linux-based image to import into IBM Cloud® Virtual Private Cloud. You can then use the custom image to deploy a virtual server or bare metal server in the IBM Cloud® Virtual Private Cloud infrastructure.

You can begin with an image template from the IBM Cloud Classic infrastructure. For more information, see Migrating a virtual server from the classic infrastructure. Did you know that you can also create a custom image of a boot volume that is attached to an instance at import time? For more information, see About creating an image from volume.

All custom images must meet the following requirements：

Contain a single file or volume.
Be in qcow2 or vhd format.
Be cloud-init enabled or bootable by using ESXi kickstart.
Size doesn't exceed 250 GB.
The minimum size is 10 GB. For any image that is less than 10 GB, the size is rounded up to 10 GB.

To create secure execution-based custom images by using the IBM Cloud Object Storage option, see Preparing the workload. For more information about creating secure execution-based images, IBM Secure Execution for Linux.

For Linux images, the Ed25519 SSH key type can be used only if the SSH server for the operating system supports this key type. For more information, see Getting started with SSH keys.

Complete the following steps to make sure that you can successfully deploy your own Linux custom image in the IBM Cloud VPC infrastructure environment. Keep in mind that you can't create an image from an encrypted boot volume (image from a volume) that is not 100 GB. The operation is blocked.

Step 1 - Start with a single image file in qcow2 or VHD format

If you're creating your own custom Linux-based image, begin with a single image file in qcow2 or VHD format. It might be helpful to begin with a cloud-enabled vendor image.

Kernel logs are important in debugging boot related issues. To ensure kernel logs are printed to the serial console, use the console=ttyS0 kernel command line argument. In addition, the nomodeset and nofb kernel parameters are used to resolve display-related issues during the boot process for older kernels that were released before mid 2021. The newer kernels use the video mode setting into the kernel.

Step 2 - Check for virtio drivers

Make sure that virtio drivers are installed on your operating system image, along with any code that is needed by virtio. Virtio network drivers are required to enable networking. Check whether virtio drivers are installed in the kernel, by running the following command:
```
grep -i virtio /boot/config-$(uname -r)
```
Look for VIRTIO_BLK and VIRTIO_NET in the output. If those lines are not present, then the virtio driver is not built into the kernel.
If the VIRTIO_BLK and VIRTIO_NET lines are present, verify that the drivers are present in the temporary root file system by running the following command:
```
lsinitrd /boot/initramfs-$(uname -r).img | grep virtio
```
If you are using a Debian operating system, use the following command:
```
lsinitramfs /boot/initrd.img-$(uname -r) | grep virtio
```
Verify that the virtio blk driver and its dependencies virtio.ko, virtio_pci, and virtio_ring are present. If the virtio dependencies are not present, you must recover the root file system.

Step 3 - Network interface is set to auto-configure

If network interfaces are defined in the guest image, make sure that at least one network interface is set to auto-configure. All interfaces can't be designated for manual configuration. Typically the interface is set to use DHCP. For more information about configuring DHCP, see the documentation for your Linux distribution.

Step 4 - Make sure that image is cloud-init enabled

Make sure that your image is cloud-init enabled. Cloud-init version 0.7.9 or greater is required.

To determine whether cloud-init is installed, run the following command: cloud-init --version
- In some cases, cloud-init might be installed but not in your environment PATH.
- To find the path for cloud-init on ExecStart, run the following command:systemctl cat cloud-init
To install cloud-init, use one of the following commands.
- For Ubuntu or Debian, run the following command: apt-get install cloud-init
- For CentOS or Red Hat, run the following command: yum install cloud-init
If the datasources_list property exists in /etc/cloud/cloud.cfg, verify that it only contains NoCloud or remove the datasources_list property entirely. ConfigDrive is not supported. For more information about data sources, see data sources. IBM Cloud cloud-init images are created for the environment by using the NoCloud data source to supply the metadata.

A block device is provided. See the following example.
```
blkid
/dev/vdb: UUID="2023-03-15-16-50-02-00" LABEL="cidata" TYPE="iso9660"
```
This block device is found by cloud-init and contains the following files.
- meta-data instance-id: INSTANCE_ID local-hostname: NAME
- user-data Optional user data that was provided when the instance was created. See User data for more information.
- vendor-data A MIME formatted file containing the cloud config SSH authorization derived from the SSH keys that were provided when the instance is created and additional initialization information.
In the /etc/cloud/cloud.cfg file, verify that the cloud_final_modules section includes the scripts-vendor module and that it is enabled. By default, Red Hat Enterprise Linux and CentOS do not include the scripts-vendor module that is required to provision instances in the IBM Cloud VPC infrastructure. You must enable the scripts-vendor module to provision an IBM Cloud VPC virtual server instance with the Linux custom image.

For Red Hat Enterprise Linux images, the following packages are included as part of the base image by default and are required for cloud-init to run successfully: subscription-manager, ethtool, and rpm. In addition, make sure that these services are enabled: cloud-init-local.service, cloud-init.service, cloud-config.service, and cloud-final.service.
Make sure that you configure your image to use SSH for logging in to your virtual server.

For more information about enabling cloud-init, see cloud-init documentation.

Step 5 - Boot disk size

Make sure that the image has a boot disk size of 10 - 250 GB. Images that are less than 10 GB are rounded up to 10 GB.

If you are customizing a virtual server to migrate from the Classic infrastructure, return to Migrating a virtual server from the classic infrastructure and continue completing migration steps.

Step 6 - Upload image to IBM Cloud Object Storage

Upload your image to IBM Cloud Object Storage. On the Objects page of your IBM Cloud® Object Storage bucket, click Upload. You can use the Aspera high-speed transfer plug-in to upload images that are larger than 200 MB. For more information about uploading to IBM Cloud Object Storage, see Upload data.

Next steps

When your Linux custom image is created and available in IBM Cloud Object Storage, you can import the custom image into VPC and Onboard a virtual server image for VPC. Make sure that you Granted access to IBM Cloud Object Storage to import images.

If you plan to use a private catalog to manage your custom images, you must first import that image into IBM Cloud VPC, and then onboard the virtual server image into a private catalog.

After the custom image is imported, you can then use the custom image to deploy a virtual server in the IBM Cloud® Virtual Private Cloud infrastructure.