Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/teemtee/testcloud

A small helper script to download and boot cloud images locally
https://github.com/teemtee/testcloud

Last synced: about 1 year ago
JSON representation

A small helper script to download and boot cloud images locally

Awesome Lists containing this project

README 

          
# testcloud



**testcloud** is a small helper script to download and boot cloud/coreos VM images

locally. Testcloud supports wide range of distributions, namely Fedora, Fedora CoreOS,

CentOS, CentOS Stream, Red Hat Enterprise Linux, Debian and Ubuntu.



**testcloud** can run either in system mode or in constrained user session mode,

which is useful for running testcloud and its VMs in unprivileged containers.



## Installation



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:



1. Install the **testcloud**.



       ```

       $ sudo dnf install testcloud

       ```



2. Add yourself to the `testcloud group`.



      ```

      $ sudo usermod -a -G testcloud $USER

      ```



3. 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

      ```



4. Now, you are ready to use **testcloud**.



## Using testcloud



### Creating a new instance



To create a new instance, you will need to provide distribution and version you wish to use or 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

().



To create a new instance with the cloud image, run:



```

$ testcloud create  or 

```



Some examples how to create an instance with distribution:version shortcut:



```

# Latest Fedora Release

$ testcloud create fedora

```



```

# Fedora Rawhide (latest Nightly Compose)

$ testcloud create fedora:rawhide

```



```

# CentOS Stream 8

$ testcloud create centos-stream:8

```



```

# Ubuntu Hirsute (21.04)

$ testcloud create ubuntu:hirsute

```



```

# Debian 11

$ testcloud create debian:11

```



Supported distributions with shortcuts are: Fedora, CentOS, CentOS Stream, Ubuntu, Debian, Alma, Rocky, and Oracle.

For other distributions, you can provide link to basically any qcow2 image which has the cloud-init package included.



Testcloud supports also Vagrant .box files, in a limited manner and currently only for Fedora and CentOS.



**testcloud** will download the *qcow2* image and save it in the

`/var/lib/testcloud/backingstores/`. It will use this

image a backing store for the newly created instance in

`/var/tmp/instances/`. When the image has been already

downloaded, **testcloud** will use the previously download image to

create the instance.



To create a new instance with the coreos image, run:



```

$ testcloud create fedora-coreos: or 



```



You will be able to see the instance using the `list` command.



```

$ testcloud list

```



Alternatively, the instances can also be viewed and manipulated using

the **virt-manager** tool.



### Creating an instance with specific architecture



Instances can be created with a different architecture than the host architecture. You'll need to have a proper

qemu binary installed for this to work (eg. qemu-system-aarch64-core for aarch64 on x86_64 on Fedora). Supported

architectures in testcloud are: x86_64, aarch64, ppc64le, and s390x. Any combinations of these are supported.



Some examples:



```

# Fedora aarch64 on x86_64 (or any other)

$ testcloud create fedora --arch aarch64

```



```

# CentOS Stream x86_64 on aarch64 (or any other)

$ testcloud create centos-stream --arch x86_64

```



```

# Fedora Rawhide ppc64le on aarch64 (or any other)

$ testcloud create fedora:rawhide --arch ppc64le

```



### Starting, stopping, and removing an instance



Instances can be started and stopped using the `instance` interface of

the **testcloud**, too:



1. List all instances to see the correct name of the instance:



       ```

       $ testcloud list

       ```



2. Start the instance:



       ```

       $ testcloud start 

       ```



3. Stop the instance:



       ```

       $ testcloud stop 

       ```



4. Remove the instance:



       ```

       $ testcloud remove 

       ```



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.



### Other instance operations



1. Reboot the instance:



       ```

       $ testcloud reboot 

       ```



2. Remove non-existing libvirt VMs from testcloud:



       ```

       $ testcloud clean

       ```



### Logging into the instance



When the cloud/coreos instance is created, **testcloud** will return its IP address

that you can use to access the running instance via `ssh`. The default *login

name* is `cloud-user` and the *password* is `passw0rd`. Testcloud will output info how you can connect to any of the Supported Distributions.



```

ssh cloud-user@

```



The IP address of an instance is also shown when you list the instance

using the `testcloud list` command. You can also control the

instance using the **virt-manager** , **GNOME Boxes** or any other tool to manage libvirt VMs.



### Available options to create an instance



There are several options (all optional) that can be used to create a

new instance using **testcloud**.



-c, \--connection QEMU_URI



: You can specify uri to qemu you wish to use. For limited environments, you might wish to use *qemu:///session*. Remote connections other than *qemu:///session* and *qemu:///system* (like qemu+ssh,...) are known to be problematic.



\--arch ARCH



: To request a speciffic architecture for the guest. The default

|    is the architecture of the host system.



\--ram RAM



: To set the amount of RAM that will be available to the virtual

    machine (in MiB).



\--vcpus VCPUS



: To set the amount of VCPUS that will be available to the virtual

    machine.



\--no-graphic



: This turns off the graphical display of the virtual machine.



\--vnc



: To open a VNC connection at the `:1` display of the instance.



-n, \--name NAME



: To specify a custom name for you instance.



\--timeout TIMEOUT



: A time (in seconds) to wait for boot to complete. Setting to 0

    (default) will disable this functionality.



\--disksize DISKSIZE



: To set the disk size of the virtual machine (in GiB)



\--disk_number



: To provide disk number you want



\--nic_number



: To provide nic number you want



\--virtiofs

: To specify a local directory to mount and mount target like :



\--iommu



: To provide virtual iommu device



There are several additional options that can be used to create a

new Coreos instance using **testcloud**.



\--bu_file BU_FILE



: To provide a bu_file you want to use



\--ign_file IGN_FILE



: To provide an ign_file you want to use



\--ssh_path



: To provide ssh pubkey path



### Configuration



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`:



```yaml

USER_DATA = """#cloud-config

users:

    - default

    - name: root

      password: %s

      chpasswd: { expire: False }

      ssh-authorized-keys:

      - 

"""

```



## Testcloud Development



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:



### Prerequisites



1. Install the dependencies for **testcloud**.



       ```

       $ sudo dnf builddep testcloud

       ```



2. Start **libvirtd**.



       ```

       $ sudo systemctl start libvirtd

       ```



3. Add the `testcloud` group to the system.



       ```

       $ sudo groupadd testcloud

       ```



4. Add a user into the `testcloud` group.



       ```

       $ sudo usermod -a -G testcloud $USER

       ```



5. 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

       ```



### Installation



1. Clone the **testcloud** repository.



       ```

       $ git clone https://pagure.io/testcloud.git

       ```



2. 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

       ```



3. 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

       ```



4. Copy the `.rules` file to the **polkit** rules.



       ```

       $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/

       ```



### Running testcloud



1. Navigate to your **testcloud** git repository.



       ```

       $ cd testcloud

       ```



2. 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 ...

       ```



3. 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

       ```



### Testing



There is a small testsuite you can run with:



```

tox

```



This is a good place to contribute if you\'re looking to help out.



### Releasing



Testcloud is being released to all stable Fedora releases, EPEL branches, and PyPi.

The release process can be summed up to these steps:



1. A batch of changes has accumulated

2. Testsuite sanity is verified (via either tox or pytest)

3. Documentation is verified up-to-date (README.md, docs/, manpages/)

4. Compatibility with tmt is verified

5. `__version__` is updated in `testcloud/__init__.py`, `version` is updated in `docs/source/conf.py`

6. Version bumps are commited, pushed, a new tag is pushed to this repository

7. A new version is uploaded on PyPi:

       ```

       python3 setup.py sdist bdist_wheel && twine upload dist/*

       ```

8. Resulting .tar.gz is copied to the dist-git, and build are submitted to all of the stable Fedoras and EPELs

9. New bodhi builds are queued into the -testing repositories



### Issue Tracking and Roadmap



Our project tracker is on the teemtee

[GitHub](https://github.com/teemtee/testcloud) instance.



### Credit



Thanks to [Oddshocks](https://github.com/oddshocks) for the koji

downloader code :)



### License



This code is licensed GPLv2+. See the LICENSE file for details.