From 1e1f0818f549ce6b47976543fe0ecfa4d75fd073 Mon Sep 17 00:00:00 2001 From: Lukas Ruzicka Date: Oct 12 2020 16:48:54 +0000 Subject: [PATCH 1/11] Update README.rst to provide more structured info to use testcloud. --- diff --git a/README.rst b/README.rst index d8b32fb..0b9e632 100644 --- a/README.rst +++ b/README.rst @@ -1,90 +1,148 @@ -######### testcloud -######### +########## -testcloud is a small helper script to download and boot cloud images locally. -Currently only Fedora qcow2 images are tested and supported. +**testcloud** is a small helper script to download and boot cloud images locally. +Currently, only Fedora *qcow2* images are tested and supported. -Requirements ------------- +Installation +============ -Packages: - - libvirt - - python3-libvirt - - libguestfs - - libguestfs-tools - - python3-requests +#. Install required dependencies for ``testcloud``: -All of these packages are in the Fedora repos (and likely other distros as -well). + .. code:: bash -For the moment, the follwing directories need to exist with permissions that -allow modification by any permitted user:: + sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests - /var/lib/testcloud/ - /var/lib/testcloud/instances - /var/lib/testcloud/backingstores +#. Install the testcloud packages: -This will be automagical in a future version of testcloud and is a side-effect -of the current refactoring/transition process. + .. code:: bash -If you are running testcloud as a non-administrative user (ie. not in wheel) or -on a system that doesn't have a polkit agent running (custom setups, headless -systems etc.), you may need to adjust local polkit configuration to allow -non-admin users to manage VMs with libvirt. Look into -``conf/99-testcloud-nonroot-libvirt-access.rules`` file. + sudo dnf install testcloud -Basic Usage ------------ +#. Add yourself to the ``testcloud group``: -The usage varies slightly between using the git checkout and installing the -module. To run testcloud straight from the git checkout, use + .. code:: bash -.. code:: bash + sudo usermod -a -G testcloud + +#. Restart your user session to update the group privileges, or use the ``newgrp`` command to update them in the current session. + + .. code:: bash + + newgrp - + +#. Now, you are ready to use **testcloud**. + + +Using testcloud +=============== + + +Creating a new instance +----------------------- - python run_testCloud.py instance create -u +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/). -After installing via pip or setup.py, you can run +To create a new instance with the cloud image, run: .. code:: bash testcloud instance create -u -This will download the qcow2 and store it in /var/lib/testcloud/backingstores/. -This will be used as a backing store for your instance under /var/tmp/instances/. These instances will be viewable within virt-manager. To see your running -instances run: +**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. + +You will be able to see the instance using the ``list`` command. .. code:: bash testcloud instance list -Instances can be stopped, started and removed as well through this interface. To -see a list of options, run: +Note, that the above command will only list the **running** instances. To see all instances, use: .. code:: bash - testcloud instance -h + testcloud instance list --all -Options -------- +Alternatively, the instances can also be viewed and manipulated using the **virt-manager** tool. + + +Starting, stopping, and removing an instance +-------------------------------------------- + +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: + + .. code:: bash + + testcloud instance list --all + +#. Start the instance: -There are currently only two options (all optional) you can use when invoking -this script: '--ram' and '--no-graphic'. + .. code:: bash -The --ram option takes an int for how much ram you want the guest to have, the -``--no-graphic option`` is merely a flag to suppress a GUI from appearing. + testcloud instance start -Once the image has booted, you can log in from the GUI or ssh. To log in with -ssh, run the following command: +#. Stop the instance: + + .. code:: bash + + testcloud instance stop + +#. Remove the instance: + + .. code:: bash + + testcloud instance 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 +------------------------- + +#. Reboot the instance: + + .. code:: bash + + testcloud instance reboot + +#. Remove non-existing libvirt VMs from testcloud: + + .. code:: bash + + testcloud instance clean + +Logging into the instance +------------------------- + +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``. .. code:: bash - ssh fedora@ + ssh fedora@ + +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. + +Available options to create an instance +--------------------------------------- + +There are several options (all optional) that can be used to create a new instance using **testcloud**. -The user is 'fedora' and the password is 'passw0rd' +--ram RAM + To set the amount of RAM that will be available to the virtual machine (in MiB). +--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. +--atomic + This flag should be used if the instance is booted from an Atomic Host. +-u, --url URL + The URL from where the qcow2 image should be downloaded. **This option is compulsory.** +--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) -Now you have a working local cloud image to test against. Configuration ------------- From 71e01b15266b1902df91d507648ffb122ffb5440 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 07:24:05 +0000 Subject: [PATCH 2/11] Change info to comply with error messages. --- diff --git a/README.rst b/README.rst index 0b9e632..7762d26 100644 --- a/README.rst +++ b/README.rst @@ -25,11 +25,11 @@ Installation sudo usermod -a -G testcloud -#. Restart your user session to update the group privileges, or use the ``newgrp`` command to update them in the current session. +#. 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. .. code:: bash - newgrp - + su -i #. Now, you are ready to use **testcloud**. From 66dd7b5e340c12bf87cb168ca67cbd683d50659c Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 07:25:46 +0000 Subject: [PATCH 3/11] Delete redundant info. --- diff --git a/README.rst b/README.rst index 7762d26..4993e0b 100644 --- a/README.rst +++ b/README.rst @@ -7,13 +7,7 @@ Currently, only Fedora *qcow2* images are tested and supported. Installation ============ -#. Install required dependencies for ``testcloud``: - - .. code:: bash - - sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests - -#. Install the testcloud packages: +#. Install the **testcloud**: .. code:: bash From 3b059d4d80a4ea840cf354e9e4471607b3feeb74 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 07:31:08 +0000 Subject: [PATCH 4/11] Delete the --atomic switch as it is no longer valid. --- diff --git a/README.rst b/README.rst index 4993e0b..969097c 100644 --- a/README.rst +++ b/README.rst @@ -128,8 +128,6 @@ There are several options (all optional) that can be used to create a new instan This turns off the graphical display of the virtual machine. --vnc To open a VNC connection at the ``:1`` display of the instance. ---atomic - This flag should be used if the instance is booted from an Atomic Host. -u, --url URL The URL from where the qcow2 image should be downloaded. **This option is compulsory.** --timeout TIMEOUT From a3bc964124024fa429136adf7f4fd64599c29e00 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 10:22:30 +0000 Subject: [PATCH 5/11] Add development section. --- diff --git a/README.rst b/README.rst index 969097c..c291fa7 100644 --- a/README.rst +++ b/README.rst @@ -7,6 +7,12 @@ Currently, only Fedora *qcow2* images are tested and supported. 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: + #. Install the **testcloud**: .. code:: bash @@ -31,7 +37,6 @@ Installation Using testcloud =============== - Creating a new instance ----------------------- @@ -152,6 +157,99 @@ Note that in order for those new values to be picked up, the filename must be - ``~/.config/testcloud/settings.py`` - ``/etc/testcloud/settings.py`` +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 +------------- + +#. Install the dependencies for **testcloud**. + +.. code:: bash + + $ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2 + +#. Start **libvirtd**. + +.. code:: bash + + $ sudo systemctl start libvirtd + +#. Add the ``testcloud`` group to the system. + +.. code:: bash + + $ sudo groupadd testcloud + +#. Add a user into the ``testcloud`` group. + +.. code:: bash + + $ sudo usermod -a -G testcloud + +#. 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. + +.. code:: bash + + $ su - + +Installation +------------ + +#. Clone the **testcloud** repository. + +.. code:: bash + + $ git clone https://pagure.io/testcloud.git + +#. Create the application directories. + +.. code:: bash + + $ 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**. + +.. code:: bash + + $ 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. + +.. code:: bash + + $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/ + +Running testcloud +----------------- + +#. Navigate to your **testcloud** git repository. + +.. code:: bash + + $ cd testcloud + +#. Execute the ``run_testcloud.py`` script to run the **testcloud**. You can use any options as with the regular installation, for example: + +.. code:: bash + + $ ./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. + +.. code:: bash + + $ pip3 install -e . --user + Testing ------- From cf5ee8f1d4bf70f79d6d95fbdc3af914ac9c4d5d Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 12:21:57 +0000 Subject: [PATCH 6/11] Add development installation section. --- diff --git a/README.rst b/README.rst index c291fa7..0aec76b 100644 --- a/README.rst +++ b/README.rst @@ -157,6 +157,21 @@ Note that in order for those new values to be picked up, the filename must be - ``~/.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``: + +.. code:: python + + USER_DATA = """#cloud-config + users: + - default + - name: root + password: %s + chpasswd: { expire: False } + ssh-authorized-keys: + - + """ + Testcloud Development ===================== From 895328987e4f73a8b3805b06fa2015bdcdc6f573 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 12:48:05 +0000 Subject: [PATCH 7/11] Fix indentation. --- diff --git a/README.rst b/README.rst index 0aec76b..3c0e940 100644 --- a/README.rst +++ b/README.rst @@ -185,85 +185,85 @@ Prerequisites #. Install the dependencies for **testcloud**. -.. code:: bash + .. code:: bash - $ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2 + $ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2 #. Start **libvirtd**. -.. code:: bash - - $ sudo systemctl start libvirtd + .. code:: bash + + $ sudo systemctl start libvirtd #. Add the ``testcloud`` group to the system. -.. code:: bash - - $ sudo groupadd testcloud + .. code:: bash + + $ sudo groupadd testcloud #. Add a user into the ``testcloud`` group. -.. code:: bash - - $ sudo usermod -a -G testcloud + .. code:: bash + + $ sudo usermod -a -G testcloud #. 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. -.. code:: bash - - $ su - + .. code:: bash + + $ su - Installation ------------ #. Clone the **testcloud** repository. -.. code:: bash - - $ git clone https://pagure.io/testcloud.git + .. code:: bash + + $ git clone https://pagure.io/testcloud.git #. Create the application directories. -.. code:: bash - - $ 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 + .. code:: bash + + $ 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**. -.. code:: bash - - $ sudo chown qemu:testcloud /var/lib/testcloud - $ sudo chown qemu:testcloud /var/lib/testcloud/instances - $ sudo chown qemu:testcloud /var/lib/testcloud/backingstores + .. code:: bash + + $ 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. -.. code:: bash - - $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/ + .. code:: bash + + $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/ Running testcloud ----------------- #. Navigate to your **testcloud** git repository. -.. code:: bash - - $ cd testcloud + .. code:: bash + + $ cd testcloud #. Execute the ``run_testcloud.py`` script to run the **testcloud**. You can use any options as with the regular installation, for example: -.. code:: bash - - $ ./run_testcloud.py instance create ... + .. code:: bash + + $ ./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. -.. code:: bash - - $ pip3 install -e . --user + .. code:: bash + + $ pip3 install -e . --user Testing ------- From bad6b54d337d806e2c39887326a136ad0c481e0a Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 14:19:08 +0000 Subject: [PATCH 8/11] Change format to MarkDown I changed the format to MarkDown, because the rst format broke too easily with the Pagure interpreter. --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..b1ed984 --- /dev/null +++ b/README.md @@ -0,0 +1,316 @@ +# testcloud + +**testcloud** is a small helper script to download and boot cloud images +locally. Currently, only Fedora *qcow2* images are tested and supported. + +## 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 + ``` + +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 + ``` + +4. Now, you are ready to use **testcloud**. + +## Using testcloud + +### Creating a new instance + +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 +(). + +To create a new instance with the cloud image, run: + +``` +$ testcloud instance create -u +``` + +**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. + +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. + +### 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 instance list --all + ``` + +2. Start the instance: + + ``` + $ testcloud instance start + ``` + +3. Stop the instance: + + ``` + $ testcloud instance stop + ``` + +4. Remove the instance: + + ``` + $ testcloud instance 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 instance reboot + ``` + +2. Remove non-existing libvirt VMs from testcloud: + + ``` + $ testcloud instance clean + ``` + +### Logging into the instance + +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@ +``` + +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. + +### Available options to create an instance + +There are several options (all optional) that can be used to create a +new instance using **testcloud**. + +\--ram RAM + +: To set the amount of RAM that will be available to the virtual + machine (in MiB). + +\--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. + +-u, \--url URL + +: The URL from where the qcow2 image should be downloaded. **This option is compulsory.** + +\--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) + +### 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 install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2 + ``` + +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 + ``` + +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 - + ``` + +### 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. + +### Issue Tracking and Roadmap + +Our project tracker is on the Fedora QA-devel +[Pagure](https://pagure.io/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. diff --git a/README.rst b/README.rst deleted file mode 100644 index 3c0e940..0000000 --- a/README.rst +++ /dev/null @@ -1,294 +0,0 @@ -testcloud -########## - -**testcloud** is a small helper script to download and boot cloud images locally. -Currently, only Fedora *qcow2* images are tested and supported. - -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: - -#. Install the **testcloud**: - - .. code:: bash - - sudo dnf install testcloud - -#. Add yourself to the ``testcloud group``: - - .. code:: bash - - sudo usermod -a -G testcloud - -#. 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. - - .. code:: bash - - su -i - -#. Now, you are ready to use **testcloud**. - - -Using testcloud -=============== - -Creating a new instance ------------------------ - -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: - -.. code:: bash - - testcloud instance create -u - -**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. - -You will be able to see the instance using the ``list`` command. - -.. code:: bash - - testcloud instance list - -Note, that the above command will only list the **running** instances. To see all instances, use: - -.. code:: bash - - testcloud instance list --all - -Alternatively, the instances can also be viewed and manipulated using the **virt-manager** tool. - - -Starting, stopping, and removing an instance --------------------------------------------- - -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: - - .. code:: bash - - testcloud instance list --all - -#. Start the instance: - - .. code:: bash - - testcloud instance start - -#. Stop the instance: - - .. code:: bash - - testcloud instance stop - -#. Remove the instance: - - .. code:: bash - - testcloud instance 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 -------------------------- - -#. Reboot the instance: - - .. code:: bash - - testcloud instance reboot - -#. Remove non-existing libvirt VMs from testcloud: - - .. code:: bash - - testcloud instance clean - -Logging into the instance -------------------------- - -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``. - -.. code:: bash - - ssh fedora@ - -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. - -Available options to create an instance ---------------------------------------- - -There are several options (all optional) that can be used to create a new instance using **testcloud**. - ---ram RAM - To set the amount of RAM that will be available to the virtual machine (in MiB). ---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. --u, --url URL - The URL from where the qcow2 image should be downloaded. **This option is compulsory.** ---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) - - -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``: - -.. code:: python - - 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 -------------- - -#. Install the dependencies for **testcloud**. - - .. code:: bash - - $ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2 - -#. Start **libvirtd**. - - .. code:: bash - - $ sudo systemctl start libvirtd - -#. Add the ``testcloud`` group to the system. - - .. code:: bash - - $ sudo groupadd testcloud - -#. Add a user into the ``testcloud`` group. - - .. code:: bash - - $ sudo usermod -a -G testcloud - -#. 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. - - .. code:: bash - - $ su - - -Installation ------------- - -#. Clone the **testcloud** repository. - - .. code:: bash - - $ git clone https://pagure.io/testcloud.git - -#. Create the application directories. - - .. code:: bash - - $ 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**. - - .. code:: bash - - $ 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. - - .. code:: bash - - $ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/ - -Running testcloud ------------------ - -#. Navigate to your **testcloud** git repository. - - .. code:: bash - - $ cd testcloud - -#. Execute the ``run_testcloud.py`` script to run the **testcloud**. You can use any options as with the regular installation, for example: - - .. code:: bash - - $ ./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. - - .. code:: bash - - $ pip3 install -e . --user - -Testing -------- - -There is a small testsuite you can run with: - -.. code:: bash - - tox - -This is a good place to contribute if you're looking to help out. - -Issue Tracking and Roadmap --------------------------- - -Our project tracker is on the Fedora QA-devel -`Pagure `_ -instance. - -Credit ------- - -Thanks to `Oddshocks `_ for the koji downloader code :) - -License -------- - -This code is licensed GPLv2+. See the LICENSE file for details. From 416d2c279b883f1228a45274ee162e6c99e46c40 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 14:21:22 +0000 Subject: [PATCH 9/11] Split code --- diff --git a/README.md b/README.md index b1ed984..97d9666 100644 --- a/README.md +++ b/README.md @@ -250,7 +250,11 @@ To install **testcloud** for development purposes: ``` $ 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 ``` @@ -259,7 +263,11 @@ To install **testcloud** for development purposes: ``` $ sudo chown qemu:testcloud /var/lib/testcloud + ``` + ``` $ sudo chown qemu:testcloud /var/lib/testcloud/instances + ``` + ``` $ sudo chown qemu:testcloud /var/lib/testcloud/backingstores ``` From 4160084a87122dae57ad6752bdd293fb64216c17 Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 15 2020 14:22:33 +0000 Subject: [PATCH 10/11] Split code --- diff --git a/README.md b/README.md index 97d9666..8167839 100644 --- a/README.md +++ b/README.md @@ -251,9 +251,11 @@ To install **testcloud** for development purposes: ``` $ 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 ``` @@ -264,9 +266,11 @@ To install **testcloud** for development purposes: ``` $ sudo chown qemu:testcloud /var/lib/testcloud ``` + ``` $ sudo chown qemu:testcloud /var/lib/testcloud/instances ``` + ``` $ sudo chown qemu:testcloud /var/lib/testcloud/backingstores ``` From 63632bb3a0d69481bb71110f7d7d44bb0ae7807e Mon Sep 17 00:00:00 2001 From: Lukáš Růžička Date: Oct 19 2020 13:20:04 +0000 Subject: [PATCH 11/11] Change to BASH type variable to allow copypaste --- diff --git a/README.md b/README.md index 8167839..19cc6c0 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ To use **testcloud** on a production system: 2. Add yourself to the `testcloud group`. ``` - $ sudo usermod -a -G testcloud + $ sudo usermod -a -G testcloud $USER ``` 3. Restart your user session to update the group privileges, or use @@ -29,7 +29,7 @@ To use **testcloud** on a production system: settings will be updated. ``` - $ su -i + $ su -i $USER ``` 4. Now, you are ready to use **testcloud**. @@ -227,7 +227,7 @@ To install **testcloud** for development purposes: 4. Add a user into the `testcloud` group. ``` - $ sudo usermod -a -G testcloud + $ sudo usermod -a -G testcloud $USER ``` 5. Log out of the system and log in again to update the group @@ -235,7 +235,7 @@ To install **testcloud** for development purposes: terminal. ``` - $ su - + $ su - $USER ``` ### Installation