The VirtualImage
resource is designed to load virtual machine images and then use them to create virtual machine disks. This resource is available only in the namespace or project in which it was created.
When connected to a virtual machine, the image is accessed in read-only mode.
The image creation process includes the following steps:
- The user creates a
VirtualImage
resource. - After creation, the image is automatically loaded from the specified source into the storage (DVCR).
- Once the download is complete, the resource becomes available for disk creation.
There are different types of images:
- ISO image: an installation image used for the initial installation of an operating system. Such images are released by OS vendors and are used for installation on physical and virtual servers.
- Preinstalled disk image: contains an already installed and configured operating system ready for use after the virtual machine is created. Ready images can be obtained from the distribution developers’ resources or created by yourself.
Examples of resources for obtaining virtual machine images:
Distribution | Default user. |
---|---|
AlmaLinux | almalinux |
AlpineLinux | alpine |
CentOS | cloud-user |
Debian | debian |
Rocky | rocky |
Ubuntu | ubuntu |
The following preinstalled image formats are supported:
- qcow2
- raw
- vmdk
- vdi
Image files can also be compressed with one of the following compression algorithms: gz, xz.
Once a share is created, the image type and size are automatically determined. This information is reflected in the resource status.
Images can be downloaded from various sources, such as HTTP servers where image files are located or container registries. It is also possible to download images directly from the command line using the curl utility.
Images can be created from other images and virtual machine disks.
Project image two storage types are supported:
ContainerRegistry
: The default type in which the image is stored inDVCR
.PersistentVolumeClaim
: The type that usesPVC
as the storage for the image. This option is preferred if you are using storage that supportsPVC
fast cloning, which allows you to create disks from images faster.
Using an image with the storage: PersistentVolumeClaim
parameter is only supported for creating disks in the same storage class (StorageClass).
A full description of the VirtualImage
resource configuration settings can be found at link.
Creating image from HTTP server
Consider creating an image with the option of storing it in DVCR. Execute the following command to create a VirtualImage
:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: ubuntu-22-04
spec:
# Save the image to DVCR
storage: ContainerRegistry
# The source for the image.
dataSource:
type: HTTP
http:
url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
EOF
Check the result of the VirtualImage
creation:
d8 k get virtualimage ubuntu-22-04
# or a shorter version
d8 k get vi ubuntu-22-04
Example output:
NAME PHASE CDROM PROGRESS AGE
ubuntu-22-04 Ready false 100% 23h
After creation the VirtualImage
resource can be in the following states (phases):
Pending
: Waiting for all dependent resources required for image creation to be ready.WaitForUserUpload
: Waiting for the user to upload the image (the phase is present only fortype=Upload
).Provisioning
: The image creation process is in progress.Ready
: The image is created and ready for use.Failed
: An error occurred during the image creation process.Terminating
: The image is being deleted. The image may “hang” in this state if it is still connected to the virtual machine.
As long as the image has not entered the Ready
phase, the contents of the .spec
block can be changed. If you change it, the disk creation process will start again. After entering the Ready
phase, the contents of the .spec
block cannot be changed.
Diagnosing problems with a resource is done by analyzing the information in the .status.conditions
block
You can trace the image creation process by adding the -w
key to the previous command:
d8 k get vi ubuntu-22-04 -w
Example output:
NAME PHASE CDROM PROGRESS AGE
ubuntu-22-04 Provisioning false 4s
ubuntu-22-04 Provisioning false 0.0% 4s
ubuntu-22-04 Provisioning false 28.2% 6s
ubuntu-22-04 Provisioning false 66.5% 8s
ubuntu-22-04 Provisioning false 100.0% 10s
ubuntu-22-04 Provisioning false 100.0% 16s
ubuntu-22-04 Ready false 100% 18s
The VirtualImage
resource description provides additional information about the downloaded image:
d8 k describe vi ubuntu-22-04
How to create an image from an HTTP server in the web interface:
- Go to the “Projects” tab and select the desired project.
- Go to the “Virtualization” → “Disk Images” section.
- Click “Create Image”.
- Select “Load data from link (HTTP)” from the list.
- In the form that opens, enter the image name in the “Image name” field.
- Select
ContainerRegistry
in the “Storage” field. - Specify the link to the image in the “URL” field.
- Click the “Create” button.
- The image status is displayed at the top left, under the image name.
Now let’s look at an example of creating an image and storing it in PVC:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: ubuntu-22-04-pvc
spec:
storage: PersistentVolumeClaim
persistentVolumeClaim:
# Substitute your StorageClass name.
storageClassName: i-sds-replicated-thin-r2
# Source for image creation.
dataSource:
type: HTTP
http:
url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
EOF
Check the result of the VirtualImage
creation:
d8 k get vi ubuntu-22-04-pvc
Example output:
NAME PHASE CDROM PROGRESS AGE
ubuntu-22-04-pvc Ready false 100% 23h
If the .spec.persistentVolumeClaim.storageClassName
parameter is not specified, the default StorageClass
at the cluster level will be used, or for images if specified in module settings.
How to create an image and store it in PVC in the web interface:
- Go to the “Projects” tab and select the desired project.
- Go to the “Virtualization” → “Disk Images” section.
- Click “Create Image”.
- Select “Load data from link (HTTP)” from the list.
- In the form that opens, enter the image name in the “mage name” field.
- In the “Storage” field, select
PersistentVolumeClaim
. - In the “Storage class” field, you can select StorageClass or leave the default selection.
- In the URL field, specify the link to the image.
- Click the Create button.
- The image status is displayed at the top left, under the image name.
Creating an image from container registry
An image stored in container registry has a certain format. Let’s look at an example:
First, download the image locally:
curl -L https://cloud-images.ubuntu.com/minimal/releases/jammy/release/ubuntu-22.04-minimal-cloudimg-amd64.img -o ubuntu2204.img
Next, create a Dockerfile
with the following contents:
FROM scratch
COPY ubuntu2204.img /disk/ubuntu2204.img
Build the image and load it into the container registry. The example below uses docker.io as the container registry. you need to have a service account and a customized environment to run it.
docker build -t docker.io/<username>/ubuntu2204:latest
where username
is the username specified when registering with docker.io.
Load the created image into the container registry:
docker push docker.io/<username>/ubuntu2204:latest
To use this image, create a resource as an example:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: ubuntu-2204
spec:
storage: ContainerRegistry
dataSource:
type: ContainerImage
containerImage:
image: docker.io/<username>/ubuntu2204:latest
EOF
How to create an image from Container Registry in the web interface:
- Go to the “Projects” tab and select the desired project.
- Go to the “Virtualization” → “Disk Images” section.
- Click “Create Image”.
- Select “Upload data from container image” from the list.
- In the form that opens, enter the image name in the “Image Name” field.
- In the “Storage” field, select
ContainerRegistry
. - In the “Image in Container Registry” field, specify
docker.io/<username>/ubuntu2204:latest
. - Click the “Create” button.
- The image status is displayed at the top left, under the image name.
Load an image from the command line
To load an image from the command line, first create the following resource as shown below with the VirtualImage
example:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: some-image
spec:
storage: ContainerRegistry
dataSource:
type: Upload
EOF
Once created, the resource will enter the WaitForUserUpload
phase, which means it is ready for image upload.
There are two options available for uploading from a cluster node and from an arbitrary node outside the cluster:
d8 k get vi some-image -o jsonpath="{.status.imageUploadURLs}" | jq
Example output:
{
"external":"https://virtualization.example.com/upload/g2OuLgRhdAWqlJsCMyNvcdt4o5ERIwmm",
"inCluster":"http://10.222.165.239/upload"
}
As an example, download the Cirros image:
curl -L http://download.cirros-cloud.net/0.5.1/cirros-0.5.1-x86_64-disk.img -o cirros.img
Upload the image using the following command:
curl https://virtualization.example.com/upload/g2OuLgRhdAWqlJsCMyNvcdt4o5ERIwmm --progress-bar -T cirros.img | cat
After the upload is complete, the image should be created and enter the Ready
phase
d8 k get vi some-image
Example output:
NAME PHASE CDROM PROGRESS AGE
some-image Ready false 100% 1m
How to upload an image from the command line in the web interface:
- Go to the “Projects” tab and select the desired project.
- Go to the “Virtualization” -> “Disk Images” section.
- Click “Create Image” then select “Upload from computer” from the drop-down menu.
- Enter the image name in the “Image Name” field.
- In the “Upload File” field, click the “Choose a file from your computer” link.
- Select the file in the file manager that opens.
- Click the “Create” button.
- Wait until the image changes to
Ready
status.
Creating an image from a disk
It is possible to create an image from disk. To do so, one of the following conditions must be met:
- The disk is not attached to any virtual machine.
- The virtual machine to which the disk is attached is in a powered off state.
Example of creating an image from a disk:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: linux-vm-root
spec:
storage: ContainerRegistry
dataSource:
type: ObjectRef
objectRef:
kind: VirtualDisk
name: linux-vm-root
EOF
How to create an image from a disk in the web interface:
- Go to the “Projects” tab and select the desired project.
- Go to the “Virtualization” → “Disk Images” section.
- Click “Create Image”.
- Select “Write data from disk” from the list.
- In the form that opens, enter
linux-vm-root
in the “Image Name” field. - In the “Storage” field, select
ContainerRegistry
. - In the “Disk” field, select the desired disk from the drop-down list.
- Click the “Create” button.
- The image status is displayed at the top left, under its name.
Creating an image from a disk snapshot
It is possible to create an image from snapshot. This requires that the disk snapshot is in the ready phase.
Example of creating an image from a disk snapshot:
d8 k apply -f - <<EOF
apiVersion: virtualization.deckhouse.io/v1alpha2
kind: VirtualImage
metadata:
name: linux-vm-root
spec:
storage: ContainerRegistry
dataSource:
type: ObjectRef
objectRef:
kind: VirtualDiskSnapshot
name: linux-vm-root-snapshot
EOF