testcloud is a small helper script to download and boot cloud images locally. Currently, only Fedora qcow2 images are tested and supported.
The following procedure should only be used to install testcloud on a production system. For developing purposes, you need a different kind of installation which is described in the Testcloud Development section below.
To use testcloud on a production system:
Install the testcloud.
$ sudo dnf install testcloud
Add yourself to the testcloud group
.
$ sudo usermod -a -G testcloud $USER
Restart your user session to update the group privileges, or use
su -
to get a login shell for that particular user where the group
settings will be updated.
$ su -i $USER
Now, you are ready to use testcloud.
To create a new instance, you will need to provide the url of some cloud image in the qcow2 format. If you do not have an image location of your own, you can use the image from the Fedora Cloud download pages (https://alt.fedoraproject.org/cloud/).
To create a new instance with the cloud image, run:
$ testcloud instance create <instance name> -u <url for qcow2 image>
testcloud will download the qcow2 image and save it in the
/var/lib/testcloud/backingstores/<qcow2-filename>
. It will use this
image a backing store for the newly created instance in
/var/tmp/instances/<instance-name>
. When the image has been already
downloaded, testcloud will use the previously download image to
create the instance.
You will be able to see the instance using the list
command.
$ testcloud instance list
Note, that the above command will only list the running instances. To see all instances, use:
$ testcloud instance list --all
Alternatively, the instances can also be viewed and manipulated using the virt-manager tool.
Instances can be started and stopped using the instance
interface of
the testcloud, too:
List all instances to see the correct name of the instance:
$ testcloud instance list --all
Start the instance:
$ testcloud instance start <instance-name>
Stop the instance:
$ testcloud instance stop <instance-name>
Remove the instance:
$ testcloud instance remove <instance-name>
Removing the instance only succeeds when the appropriate instance has
been stopped before. However, you can use the -f
option to force
removing the instance.
Reboot the instance:
$ testcloud instance reboot <instance-name>
Remove non-existing libvirt VMs from testcloud:
$ testcloud instance clean
When the instance is created, testcloud will return its IP address
that you can use to access the running instance via ssh
. The login
name is fedora
and the password is passw0rd
.
ssh fedora@<instance-IP>
The IP address of an instance is also shown when you list the instance
using the testcloud instance list
command. You can also control the
instance using the virt-manager tool.
There are several options (all optional) that can be used to create a new instance using testcloud.
To set the amount of RAM that will be available to the virtual machine (in MiB).
This turns off the graphical display of the virtual machine.
To open a VNC connection at the :1
display of the instance.
The URL from where the qcow2 image should be downloaded. This option is compulsory.
A time (in seconds) to wait for boot to complete. Setting to 0 (default) will disable this functionality.
To set the disk size of the virtual machine (in GiB)
The default configuration should work for many people but those defaults
can be overridden through the use of a settings.py
file containing the
values to use when overriding default settings. The example file in
conf/settings-example.py
shows the possible configuration values which
can be changed.
Note that in order for those new values to be picked up, the filename
must be settings.py
and that file must live in one of the following
locations:
conf/settings.py
in the git checkout~/.config/testcloud/settings.py
/etc/testcloud/settings.py
For example, if you wanted to set up an ssh accessible root account that
uses an ssh key as the authentification method, you could provide the
following to the ~/.config/testcloud/settings.py
:
USER_DATA = """#cloud-config users: - default - name: root password: %s chpasswd: { expire: False } ssh-authorized-keys: - <my ssh pub key> """
To develop testcloud, you need to perform a more complicated process to install all its dependencies, download the source code and perform a set-up.
To install testcloud for development purposes:
Install the dependencies for testcloud.
$ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2
Start libvirtd.
$ sudo systemctl start libvirtd
Add the testcloud
group to the system.
$ sudo groupadd testcloud
Add a user into the testcloud
group.
$ sudo usermod -a -G testcloud $USER
Log out of the system and log in again to update the group information on your user or use a login shell on a different terminal.
$ su - $USER
Clone the testcloud repository.
$ git clone https://pagure.io/testcloud.git
Create the application directories.
$ sudo mkdir -p -m 775 /var/lib/testcloud
$ sudo mkdir -p -m 775 /var/lib/testcloud/instances
$ sudo mkdir -p -m 775 /var/lib/testcloud/backingstores
Change ownership on these directories to enable their use with testcloud.
$ sudo chown qemu:testcloud /var/lib/testcloud
$ sudo chown qemu:testcloud /var/lib/testcloud/instances
$ sudo chown qemu:testcloud /var/lib/testcloud/backingstores
Copy the .rules
file to the polkit rules.
$ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/
Navigate to your testcloud git repository.
$ cd testcloud
Execute the run_testcloud.py
script to run the testcloud. You
can use any options as with the regular installation, for example:
$ ./run_testcloud.py instance create ...
Alternatively, you can use pip to install testcloud onto the system and then use it like it has been installed normally.
$ pip3 install -e . --user
There is a small testsuite you can run with:
tox
This is a good place to contribute if you\'re looking to help out.
Our project tracker is on the Fedora QA-devel Pagure instance.
Thanks to Oddshocks for the koji downloader code :)
This code is licensed GPLv2+. See the LICENSE file for details.