on GitHub in the pull request itself.
You can (and should) also test your modifications before you open a PR.
-Refer to the the `Testing`_ chapter for details.
+Refer to the `Testing`_ chapter for details.
Integration tests AKA ceph-qa-suite
-----------------------------------
Since Ceph is a complex beast, it may also be necessary to test your fix to
see how it behaves on real clusters running either on real or virtual
-hardware. Tests designed for this purpose live in the `ceph-qa-suite
-repository`_ and are run via the `teuthology framework`_.
+hardware. Tests designed for this purpose live in the `ceph/qa
+sub-directory`_ and are run via the `teuthology framework`_.
-.. _`ceph-qa-suite repository`: https://github.com/ceph/ceph-qa-suite/
+.. _`ceph/qa sub-directory`: https://github.com/ceph/ceph/tree/master/qa/
.. _`teuthology repository`: https://github.com/ceph/teuthology
.. _`teuthology framework`: https://github.com/ceph/teuthology
When a test requires multiple machines, root access or lasts for a
longer time (for example, to simulate a realistic Ceph deployment), it
is deemed to be an integration test. Integration tests are organized into
-"suites", which are defined in the `ceph-qa-suite repository`_ and run with
+"suites", which are defined in the `ceph/qa sub-directory`_ and run with
the ``teuthology-suite`` command.
The ``teuthology-suite`` command is part of the `teuthology framework`_.
installed on any machine running those platforms.
Teuthology has a `list of platforms that it supports
-<https://github.com/ceph/ceph-qa-suite/tree/master/distros/supported>`_ (as
+<https://github.com/ceph/ceph/tree/master/qa/distros/supported>`_ (as
of March 2016 the list consisted of "CentOS 7.2" and "Ubuntu 14.04"). It
expects to be provided pre-built Ceph packages for these platforms.
Teuthology deploys these platforms on machines (bare-metal or
Suites inventory
----------------
-The ``suites`` directory of the `ceph-qa-suite repository`_ contains
+The ``suites`` directory of the `ceph/qa sub-directory`_ contains
all the integration tests, for all the Ceph components.
-`ceph-deploy <https://github.com/ceph/ceph-qa-suite/tree/master/suites/ceph-deploy>`_
+`ceph-deploy <https://github.com/ceph/ceph/tree/master/qa/suites/ceph-deploy>`_
install a Ceph cluster with ``ceph-deploy`` (`ceph-deploy man page`_)
-`ceph-disk <https://github.com/ceph/ceph-qa-suite/tree/master/suites/ceph-disk>`_
+`ceph-disk <https://github.com/ceph/ceph/tree/master/qa/suites/ceph-disk>`_
verify init scripts (upstart etc.) and udev integration with
``ceph-disk`` (`ceph-disk man page`_), with and without `dmcrypt
<https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt>`_ support.
-`dummy <https://github.com/ceph/ceph-qa-suite/tree/master/suites/dummy>`_
+`dummy <https://github.com/ceph/ceph/tree/master/qa/suites/dummy>`_
get a machine, do nothing and return success (commonly used to
verify the integration testing infrastructure works as expected)
-`fs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/fs>`_
+`fs <https://github.com/ceph/ceph/tree/master/qa/suites/fs>`_
test CephFS
-`kcephfs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/kcephfs>`_
+`kcephfs <https://github.com/ceph/ceph/tree/master/qa/suites/kcephfs>`_
test the CephFS kernel module
-`krbd <https://github.com/ceph/ceph-qa-suite/tree/master/suites/krbd>`_
+`krbd <https://github.com/ceph/ceph/tree/master/qa/suites/krbd>`_
test the RBD kernel module
-`powercycle <https://github.com/ceph/ceph-qa-suite/tree/master/suites/powercycle>`_
+`powercycle <https://github.com/ceph/ceph/tree/master/qa/suites/powercycle>`_
verify the Ceph cluster behaves when machines are powered off
and on again
-`rados <https://github.com/ceph/ceph-qa-suite/tree/master/suites/rados>`_
+`rados <https://github.com/ceph/ceph/tree/master/qa/suites/rados>`_
run Ceph clusters including OSDs and MONs, under various conditions of
stress
-`rbd <https://github.com/ceph/ceph-qa-suite/tree/master/suites/rbd>`_
+`rbd <https://github.com/ceph/ceph/tree/master/qa/suites/rbd>`_
run RBD tests using actual Ceph clusters, with and without qemu
-`rgw <https://github.com/ceph/ceph-qa-suite/tree/master/suites/rgw>`_
+`rgw <https://github.com/ceph/ceph/tree/master/qa/suites/rgw>`_
run RGW tests using actual Ceph clusters
-`smoke <https://github.com/ceph/ceph-qa-suite/tree/master/suites/smoke>`_
+`smoke <https://github.com/ceph/ceph/tree/master/qa/suites/smoke>`_
run tests that exercise the Ceph API with an actual Ceph cluster
-`teuthology <https://github.com/ceph/ceph-qa-suite/tree/master/suites/teuthology>`_
+`teuthology <https://github.com/ceph/ceph/tree/master/qa/suites/teuthology>`_
verify that teuthology can run integration tests, with and without OpenStack
-`upgrade <https://github.com/ceph/ceph-qa-suite/tree/master/suites/upgrade>`_
+`upgrade <https://github.com/ceph/ceph/tree/master/qa/suites/upgrade>`_
for various versions of Ceph, verify that upgrades can happen
without disrupting an ongoing workload
---------------------------------
Integration tests are defined by yaml files found in the ``suites``
-subdirectory of the `ceph-qa-suite repository`_ and implemented by python
+subdirectory of the `ceph/qa sub-directory`_ and implemented by python
code found in the ``tasks`` subdirectory. Some tests ("standalone tests")
are defined in a single yaml file, while other tests are defined by a
directory tree containing yaml files that are combined, at runtime, into a
Here is a commented example using the integration test
`rados/singleton/all/admin-socket.yaml
-<https://github.com/ceph/ceph-qa-suite/blob/master/suites/rados/singleton/all/admin-socket.yaml>`_
+<https://github.com/ceph/ceph/blob/master/qa/suites/rados/singleton/all/admin-socket.yaml>`_
::
roles:
The body of the test is in the ``tasks`` array: each element is
evaluated in order, causing the corresponding python file found in the
``tasks`` subdirectory of the `teuthology repository`_ or
-`ceph-qa-suite repository`_ to be run. "Running" in this case means calling
+`ceph/qa sub-directory`_ to be run. "Running" in this case means calling
the ``task()`` function defined in that file.
In this case, the `install
-<https://github.com/ceph/teuthology/blob/master/teuthology/task/install.py>`_
+<https://github.com/ceph/teuthology/blob/master/teuthology/task/install/__init__.py>`_
task comes first. It installs the Ceph packages on each machine (as
defined by the ``roles`` array). A full description of the ``install``
task is `found in the python file
-<https://github.com/ceph/teuthology/blob/master/teuthology/task/install.py>`_
+<https://github.com/ceph/teuthology/blob/master/teuthology/task/install/__init__.py>`_
(search for "def task").
The ``ceph`` task, which is documented `here
-<https://github.com/ceph/ceph-qa-suite/blob/master/tasks/ceph.py>`_ (again,
+<https://github.com/ceph/ceph/blob/master/qa/tasks/ceph.py>`_ (again,
search for "def task"), starts OSDs and MONs (and possibly MDSs as well)
as required by the ``roles`` array. In this example, it will start one MON
(``mon.a``) and two OSDs (``osd.0`` and ``osd.1``), all on the same
``HEALTH_OK`` state.
The next task is ``admin_socket`` (`source code
-<https://github.com/ceph/ceph-qa-suite/blob/master/tasks/admin_socket.py>`_).
+<https://github.com/ceph/ceph/blob/master/qa/tasks/admin_socket.py>`_).
The parameter of the ``admin_socket`` task (and any other task) is a
structure which is interpreted as documented in the task. In this example
the parameter is a set of commands to be sent to the admin socket of
but not the same. In the case of a standalone test, like the one in
`Reading a standalone test`_, the test description is identical to the
relative path (starting from the ``suites/`` directory of the
-`ceph-qa-suite repository`_) of the yaml file defining the test.
+`ceph/qa sub-directory`_) of the yaml file defining the test.
Much more commonly, tests are defined not by a single yaml file, but by a
`directory tree of yaml files`. At runtime, the tree is walked and all yaml
In these cases, the description of each test consists of the
subdirectory under `suites/
-<https://github.com/ceph/ceph-qa-suite/tree/master/suites>`_ containing the
+<https://github.com/ceph/ceph/tree/master/qa/suites>`_ containing the
yaml facets, followed by an expression in curly braces (``{}``) consisting of
a list of yaml facets in order of concatenation. For instance the
test description::
As noted in the previous section, most tests are not defined in a single
yaml file, but rather as a `combination` of files collected from a
-directory tree within the ``suites/`` subdirectory of the `ceph-qa-suite repository`_.
+directory tree within the ``suites/`` subdirectory of the `ceph/qa sub-directory`_.
The set of all tests defined by a given subdirectory of ``suites/`` is
called an "integration test suite", or a "teuthology suite".
subdirectories below the directory containing the operator.
For example, the `ceph-disk suite
-<https://github.com/ceph/ceph-qa-suite/tree/jewel/suites/ceph-disk/>`_ is
+<https://github.com/ceph/ceph/tree/jewel/qa/suites/ceph-disk/>`_ is
defined by the ``suites/ceph-disk/`` tree, which consists of the files and
subdirectories in the following structure::
(which would of course be wrong in this case).
-Referring to the `ceph-qa-suite repository`_, you will notice that the
+Referring to the `ceph/qa sub-directory`_, you will notice that the
``centos_7.0.yaml`` and ``ubuntu_14.04.yaml`` files in the
``suites/ceph-disk/basic/distros/`` directory are implemented as symlinks.
By using symlinks instead of copying, a single file can appear in multiple
For even greater flexibility in sharing yaml files between suites, the
special file plus (``+``) can be used to concatenate files within a
directory. For instance, consider the `suites/rbd/thrash
-<https://github.com/ceph/ceph-qa-suite/tree/master/suites/rbd/thrash>`_
+<https://github.com/ceph/ceph/tree/master/qa/suites/rbd/thrash>`_
tree::
directory: rbd/thrash
When a few jobs fail and need to be run again, the ``--filter`` option
can be used to select tests with a matching description. For instance, if the
-``rados`` suite fails the `all/peer.yaml <https://github.com/ceph/ceph-qa-suite/blob/master/suites/rados/singleton/all/peer.yaml>`_ test, the following will only run the tests that contain this file::
+``rados`` suite fails the `all/peer.yaml <https://github.com/ceph/ceph/blob/master/qa/suites/rados/singleton/all/peer.yaml>`_ test, the following will only run the tests that contain this file::
teuthology-suite --suite rados --filter all/peer.yaml
Both ``--filter`` and ``--filter-out`` take a comma-separated list of strings (which
means the comma character is implicitly forbidden in filenames found in the
-`ceph-qa-suite repository`_). For instance::
+`ceph/qa sub-directory`_). For instance::
teuthology-suite --suite rados --filter all/peer.yaml,all/rest-api.yaml
will run tests that contain either
-`all/peer.yaml <https://github.com/ceph/ceph-qa-suite/blob/master/suites/rados/singleton/all/peer.yaml>`_
+`all/peer.yaml <https://github.com/ceph/ceph/blob/master/qa/suites/rados/singleton/all/peer.yaml>`_
or
-`all/rest-api.yaml <https://github.com/ceph/ceph-qa-suite/blob/master/suites/rados/singleton/all/rest-api.yaml>`_
+`all/rest-api.yaml <https://github.com/ceph/ceph/blob/master/qa/suites/rados/singleton/all/rest-api.yaml>`_
Each string is looked up anywhere in the test description and has to
be an exact match: they are not regular expressions.
The ``rados`` suite generates thousands of tests out of a few hundred
files. For instance, all tests in the `rados/thrash suite
-<https://github.com/ceph/ceph-qa-suite/tree/master/suites/rados/thrash>`_
+<https://github.com/ceph/ceph/tree/master/qa/suites/rados/thrash>`_
run for ``xfs``, ``btrfs`` and ``ext4`` because they are combined (via
special file ``%``) with the `fs directory
-<https://github.com/ceph/ceph-qa-suite/tree/master/suites/rados/thrash/fs>`_
+<https://github.com/ceph/ceph/tree/master/qa/suites/rados/thrash/fs>`_
All integration tests are required to be run before a Ceph release is published.
When merely verifying whether a contribution can be merged without
projects / ceph-ci.git / commitdiff