Preparing a Custom Image

This procedure allows you to add an image definition for an image file that you have already obtained, and that is already in the proper image format. This is qcow2 for QEMU/KVM-based VM images, and tar or tar.gz for Docker container images. IOL images are now also Docker images.

Docker image files are the same as those created using the docker image save command. If a Docker image can be pulled by the CML hosts from the outside network, i.e. they reside in some Docker registry, then you do not have to create and upload the file for the image definition. Instead, you can use just the Docker Tag attribute without uploading or specifying the Disk Image file.

Docker images are pulled the first time they are used to start a lab node. If the underlying image changes in the remote Docker repository at any point after being pulled, it is never pulled again. You must remove the image definition to clear the pulled image from the local Docker registry. In a cluster deployment, each compute host downloads the image independently, thus it may differ between different hosts. You should use version-specific tags to have complete control over which image will be used at any time.

Procedure

From the Dashboard, select Tools ‣ Node and Image Definitions.

Select Image Definitions.

Click Manage.

In the Upload New Image File page, click the choose a file field and select the VM image qcow2 or Docker tar/tar.gz file that you want to upload from the local drive.

Click Upload Image to upload the file.

Upload VM Image via SCP

Alternatively, you can upload the VM image to the CML server via scp. The CML server accepts scp connections on the regular port 22 specifically for uploading VM images. Use the same credentials that you use to log into the CML UI. For example, login as the admin user, not the sysadmin user. Since the SCP connection is restricted just to uploading image files, simply specify the root folder as the target of the scp command. For example, if your CML server is at 172.16.0.10, the command to copy the .qcow2 file for ASAv 9.12(2) to the CML server would look like this:

scp asav9-12-2.qcow2 admin@172.16.0.10:

The upload is complete when the upload progress bar disappears. That is, even if the progress bar shows 100%, wait for the progress bar to disappear before proceeding.

Once the upload finishes, the new VM image will show up under the Uploaded Images section of the page. Click Refresh to update the list of VM images, if needed.

Click Create New Image Definition.

Enter values for the image definition’s fields.

ID

Each image on the system must have a unique ID. The ID should not contain spaces.

Label

The label will be shown in the CML UI. For example, the label is shown in the node’s image selection drop-down list in the Workbench. We recommend using the VM image’s OS name and version, such as IOSv 15.6(3).

Description

This optional field can provide a longer description of the image.

Node Definition

Select the appropriate node definition to be associated with selected image. For example, if you are uploading a new IOS-XE image for the CAT 8000V, select “cat8000v” from the drop-down list.

Note

The fields below depend on the inheritance settings of the selected Node Definition. You only need to provide values for these properties if the new image requires different defaults from the values on the associated node definition. These properties will be used for the VM of any node that uses this image unless the property is also set on the node itself.

Disk Image

Select the image file that you uploaded from the list. Do not set it for pulled Docker images. Required for all other images. KVM images may specify up to 4 different disk images, first of which is the bootable OS image.

Disk Hash

Enter the complete image-identifying hash that can be obtained on the system from where you exported it. Use a command like docker image inspect nginx:latest | jq -r ‘.[0].Id[7:]’. Required for Docker or IOL images if Disk Image is set. Leave unset for pulled Docker images.

Docker Tag

Enter the Docker image reference for the Docker image. This must be the tag used to create the TAR archive with the image for regular Docker images, and is also the tag used to pull Docker images which do not specify Disk Image. Required for pulled Docker images, strongly recommended for all Docker images.

EFI Boot

In case this KVM image requires UEFI boot, while other images and the node definition do not, enable this flag. This flag is added specially for recent IOS XRv 9000 images which switched to UEFI. Only for KVM images.

Memory (MiB)

The amount of memory in megabytes that this image requires. Refer to your device’s installation and configuration documentation to choose the correct value.

CPUs

The number of virtual CPUs allocated to VMs created from this image. Refer to your device’s installation and configuration documentation to choose the correct value.

CPU Limit

The percentage of the allocated CPUs that VMs created from this image will be allowed to use. You should normally use a value of 100% unless you need to adjust the launch sequencing to boot additional nodes. See also Setting CPU limit on node.

Data Disk Size (GiB)

The size of the data disk required by this image in gigabytes (if any). Refer to your device’s installation and configuration documentation to choose the correct value. The data disk is an additional disk that is added to the virtual device. Some devices need a second disk to store databases or other information. An example is the SD-WAN manager that stores its database on the second disk. Only for KVM images.

Boot Disk Size (GiB)

The size of the boot disk required by this image in gigabytes (if any). Refer to your device’s installation and configuration documentation to choose the correct value. The boot disk is typically the disk that holds the operating system and that is marked bootable. Only for KVM images.

Note: the boot disk size used to start the VM must be equal to or larger than the one defined by the .qcow2 file itself. That is, the boot disk size should be at least as large as the virtual size reported by qemu-img info.

Click Create Image Definition.

A new image is created with the image properties from the form. It is now available for use in your labs.

Note

If there is more than one Image Definition available for the Node Definition the user can select one of them for each node. The automatic assignment selects the last Image Definition by image ID in dictionary order. To make the Image Definition selected by default, make sure to name it accordingly as you create the custom Image Definition. Numeral values work if they have the same width, i.e. 09 < 10 < 9 holds.

Related Topics