avocado.utils.vmimage

This utility provides an API to download/cache VM images (QCOW) from the official distributions repositories.

Basic Usage

Import vmimage module:

>>> from avocado.utils import vmimage

Get an image, which consists in an object with the path of the downloaded/cached base image and the path of the external snapshot created out of that base image:

>>> image = vmimage.Image.from_parameters()
>>> image
<Image name=Fedora version=35 arch=x86_64>
>>> image.name
'Fedora'
>>> image.path
'/tmp/by_location/951337e4bd3f30b584623d46f1745147cb32aca5/Fedora-Cloud-Base-35-1.2.x86_64-54d81da8.qcow2'
>>> image.version
35
>>> image.base_image
'/tmp/by_location/951337e4bd3f30b584623d46f1745147cb32aca5/Fedora-Cloud-Base-35-1.2.x86_64.qcow2'

If you provide more details about the image, the object is expected to reflect those details:

>>> image = vmimage.Image.from_parameters(arch='aarch64)
>>> image
<Image name=Fedora version=35 arch=aarch64>
>>> image.name
'Fedora'
>>> image.path
'/tmp/by_location/3f1d3b1b568ad908eb003d1012ba79e1f3bb0d57/Fedora-Cloud-Base-35-1.2.aarch64-dab7007f.qcow2'

>>> image = vmimage.Image.from_parameters(version=34,name='fedora')
>>> image
<Image name=Fedora version=34 arch=x86_64>
>>> image.path
'/tmp/by_location/def0ea887952961473cfbfda268e77d66f9bcd14/Fedora-Cloud-Base-34-1.2.x86_64-0ed30cd9.qcow2'

Notice that, unlike the base_image attribute, the path attribute will be always different in each instance, as it actually points to an external snapshot created out of the base image:

>>> i1 = vmimage.Image.from_parameters()
>>> i2 = vmimage.Image.from_parameters()
>>> i1.path == i2.path
False

Custom Image Provider

If you need your own Image Provider, you can extend the vmimage.IMAGE_PROVIDERS list, including your provider class. For instance, using the vmimage utility in an Avocado test, we could add our own provider with:

from avocado import Test

from avocado.utils import vmimage

class MyProvider(vmimage.ImageProviderBase):

    name = 'MyDistro'

    def __init__(self, version='[0-9]+', build='[0-9]+.[0-9]+',
                 arch=os.uname()[4]):
        """
        :params version: The regular expression that represents
                         your distro version numbering.
        :params build: The regular expression that represents
                       your build version numbering.
        :params arch: The default architecture to look images for.
        """
        super(MyProvider, self).__init__(version, build, arch)

        # The URL which contains a list of the distro versions
        self.url_versions = 'https://dl.fedoraproject.org/pub/fedora/linux/releases/'

        # The URL which contains a list of distro images
        self.url_images = self.url_versions + '{version}/CloudImages/{arch}/images/'

        # The images naming pattern
        self.image_pattern = 'Fedora-Cloud-Base-{version}-{build}.{arch}.qcow2$'

class MyTest(Test):

    def setUp(self):
        vmimage.IMAGE_PROVIDERS.add(MyProvider)
        image = vmimage.get('MyDistro')
        ...

    def test(self):
        ...

Supported images

The vmimage library has no hardcoded limitations of versions or architectures that can be supported. You can use it as you wish. This is the list of images that we tested and they work with vmimage:

Provider

Version

Architecture

centos

8

aarch64

centos

8

ppc64le

centos

8

x86_64

centos

7

x86_64

cirros

0.5.2

arm

cirros

0.5.2

aarch64

cirros

0.5.2

i386

cirros

0.5.2

ppc64

cirros

0.5.2

ppc64le

cirros

0.5.2

powerpc

cirros

0.5.2

x86_64

cirros

0.4.0

arm

cirros

0.4.0

aarch64

cirros

0.4.0

i386

cirros

0.4.0

ppc64

cirros

0.4.0

ppc64le

cirros

0.4.0

powerpc

cirros

0.4.0

x86_64

debian

buster

arm64

debian

buster

amd64

debian

bullseye

arm64

debian

bullseye

amd64

fedora

34

aarch64

fedora

34

ppc64le

fedora

34

s390x

fedora

34

x86_64

fedora

35

aarch64

fedora

35

ppc64le

fedora

35

s390x

fedora

35

x86_64

fedora

36

aarch64

fedora

36

ppc64le

fedora

36

s390x

fedora

36

x86_64

ubuntu

18.04

aarch64

ubuntu

18.04

ppc64el

ubuntu

18.04

s390x

ubuntu

18.04

x86_64

ubuntu

20.10

aarch64

ubuntu

20.10

ppc64el

ubuntu

20.10

s390x

ubuntu

20.10

x86_64

ubuntu

21.04

aarch64

ubuntu

21.04

ppc64el

ubuntu

21.04

s390x

ubuntu

21.04

x86_64

ubuntu

21.10

aarch64

ubuntu

21.10

ppc64el

ubuntu

21.10

s390x

ubuntu

21.10

x86_64

opensuse

15.2

x86_64

opensuse

15.3

x86_64

freebsd

13.0

aarch64

freebsd

13.0

i386

freebsd

13.0

x86_64

freebsd

12.2

aarch64

freebsd

12.2

i386

freebsd

12.2

x86_64