# check that it's there
./ceph health
+Architecture
+============
+
+Ceph is a collection of components built on top of RADOS and provide
+services (RBD, RGW, CephFS) and APIs (S3, Swift, POSIX) for the user to
+store and retrieve data.
+
+See :doc:`/architecture` for an overview of Ceph architecture. The
+following sections treat each of the major architectural components
+in more detail, with links to code and tests.
+
+.. FIXME The following are just stubs. These need to be developed into
+ detailed descriptions of the various high-level components (RADOS, RGW,
+ etc.) with breakdowns of their respective subcomponents.
+
+.. FIXME Later, in the Testing chapter I would like to take another look
+ at these components/subcomponents with a focus on how they are tested.
+
+RADOS
+-----
+
+RADOS stands for "Reliable, Autonomic Distributed Object Store". In a Ceph
+cluster, all data are stored in objects, and RADOS is the component responsible
+for that.
+
+RADOS itself can be further broken down into Monitors, Object Storage Daemons
+(OSDs), and client APIs (librados). Monitors and OSDs are introduced at
+:doc:`/start/intro`. The client library is explained at
+:doc:`/rados/api/index`.
+
+RGW
+---
+
+RGW stands for RADOS Gateway. Using the embedded HTTP server civetweb_, RGW
+provides a REST interface to RADOS objects.
+
+.. _civetweb: https://github.com/civetweb/civetweb
+
+A more thorough introduction to RGW can be found at :doc:`/radosgw/index`.
+
+RBD
+---
+
+RBD stands for RADOS Block Device. It enables a Ceph cluster to store disk
+images, and includes in-kernel code enabling RBD images to be mounted.
+
+To delve further into RBD, see :doc:`/rbd/rbd`.
+
+CephFS
+------
+
+CephFS is a distributed file system that enables a Ceph cluster to be used as a NAS.
+
+File system metadata is managed by Meta Data Server (MDS) daemons. The Ceph
+file system is explained in more detail at :doc:`/cephfs/index`.
Issue tracker
=============
See `Redmine issue tracker`_ for a brief introduction to the Ceph Issue Tracker.
+Ceph developers use the issue tracker to
+
+1. keep track of issues - bugs, fix requests, feature requests, backport
+requests, etc.
+
+2. communicate with other developers as they work on issues and keep them
+informed on progress toward their resolution.
+
Issue tracker conventions
-------------------------
one.
The tracker is there to explain the issue (bug) to your fellow Ceph
-developers, so take care to provide a descriptive title as well as
-sufficient information and details in the description.
+developers and keep them informed as you make progress toward resolution.
+To this end, then, provide a descriptive title as well as sufficient
+information and details in the description.
If you have sufficient tracker permissions, assign the bug to yourself by
changing the ``Assignee`` field. If your tracker permissions have not yet
-been elevated, simply add a comment to the issue to let the other
-developers know you are working on the bug.
+been elevated, simply add a comment to the issue with a short message like
+"I am working on this issue".
Upstream code
-------------
$ git clone https://github.com/mygithubaccount/ceph
-While it is possible to clone the upstream repo directly, in this case we
-must fork it first, because that (forking) makes it possible to open a
-GitHub pull request.
+While it is possible to clone the upstream repo directly, in this case you
+must fork it first. Forking is what enables us to open a `GitHub pull
+request`_.
For more information on using GitHub, refer to `GitHub Help
<https://help.github.com/>`_.
Local environment
-----------------
-In the local environment created in the previous step, we now have a
+In the local environment created in the previous step, you now have a
copy of the ``master`` branch in ``remotes/origin/master``. Since the fork
(https://github.com/mygithubaccount/ceph.git) is frozen in time and the
upstream repo (https://github.com/ceph/ceph.git, typically abbreviated to
-``ceph/ceph.git``) is updated frequently by other developers, we will need
-to add the upstream repo as a "remote" so we can fetch from it:
-
-.. code::
+``ceph/ceph.git``) is updated frequently by other developers, you will need
+to sync your fork periodically. To do this, first add the upstream repo as
+a "remote" and fetch it::
$ git remote add ceph https://github.com/ceph/ceph.git
$ git fetch ceph
-After running these commands, all the branches from ``ceph/ceph.git`` are
-downloaded to the local git repo as ``remotes/ceph/$BRANCH_NAME`` and can be
-referenced as ``ceph/$BRANCH_NAME`` in certain git commands.
+Fetching downloads all objects (commits, branches) that were added since
+the last sync. After running these commands, all the branches from
+``ceph/ceph.git`` are downloaded to the local git repo as
+``remotes/ceph/$BRANCH_NAME`` and can be referenced as
+``ceph/$BRANCH_NAME`` in certain git commands.
For example, your local ``master`` branch can be reset to the upstream Ceph
-``master`` branch by doing:
-
-.. code::
+``master`` branch by doing::
$ git fetch ceph
$ git checkout master
$ git reset --hard ceph/master
-The ``master`` branch of your fork can then be synced to upstream master by
-doing:
-
-.. code::
+Finally, the ``master`` branch of your fork can then be synced to upstream
+master by::
$ git push -u origin master
fix. If you don't have permission to change that field, your comment that
you are working on the issue is sufficient.
-In the best case, your fix is very simple and requires only minimal testing.
-In the typical worst case, fixing the bug is an iterative process involving
-trial and error, not to mention skill. Fixing bugs is beyond the scope
-of the current discussion.
+Possibly, your fix is very simple and requires only minimal testing.
+More likely, it will be an iterative process involving trial and error, not
+to mention skill. An explanation of how to fix bugs is beyond the
+scope of this document. Instead, we focus on the mechanics of the process
+in the context of the Ceph project.
-For a more detailed discussion of the tools available for validating your
-bugfixes, see the `Testing`_ chapter.
+A detailed discussion of the tools available for validating your bugfixes,
+see the `Testing`_ chapter.
For now, let us just assume that you have finished work on the bugfix and
that you have tested it and believe it works. Commit the changes to your local
-branch and push the changes to your fork like so:
+branch using the ``--sign`` option::
-.. code::
+ $ git commit -as
+
+and push the changes to your fork::
$ git push origin fix_1
-------------------
The next step is to open a GitHub pull request. The purpose of this step is
-to make your bugfix available to the community of Ceph developers.
-Additional testing will be done on it, and it will undergo code review.
+to make your bugfix available to the community of Ceph developers. They
+will review it and may do additional testing on it.
+
In short, this is the point where you "go public" with your modifications.
+Psychologically, you should be prepared to receive suggestions and
+constructive criticism. Don't worry! In our experience, the Ceph project is
+a friendly place!
If you are uncertain how to use pull requests, you may read
`this GitHub pull request tutorial`_.
.. _`Git Commit Good Practice`: https://wiki.openstack.org/wiki/GitCommitMessages
.. _`OpenStack Project Wiki`: https://wiki.openstack.org/wiki/Main_Page
-Once your pull request is opened, update the `Issue tracker`_ by adding a
-comment to the bug. The update can be as simple as:
-
-.. code::
+Once your pull request (PR) is opened, update the `Issue tracker`_ by
+adding a comment to the bug pointing the other developers to your PR. The
+update can be as simple as::
*PR*: https://github.com/ceph/ceph/pull/$NUMBER_OF_YOUR_PULL_REQUEST
.. _`teuthology framework`: https://github.com/ceph/teuthology
If you have access to an OpenStack tenant, you are encouraged to run the
-integration tests yourself using `ceph-workbench ceph-qa-suite`_
-and post the test results to the PR.
+integration tests yourself using `ceph-workbench ceph-qa-suite`_,
+and to post the test results to the PR.
.. _`ceph-workbench ceph-qa-suite`: http://ceph-workbench.readthedocs.org/
-The Ceph community also uses the `Sepia lab
-<http://ceph.github.io/sepia/>`_ where the integration tests can be run on
+The Ceph community has access to the `Sepia lab
+<http://ceph.github.io/sepia/>`_ where integration tests can be run on
real hardware. Other developers may add tags like "needs-qa" to your PR.
This allows PRs that need testing to be merged into a single branch and
tested all at the same time. Since teuthology suites can take hours
(even days in some cases) to run, this can save a lot of time.
-Integration tests are discussed in more detail in the `Testing`_ chapter.
+Integration testing is discussed in more detail in the `Testing`_ chapter.
Code review
-----------
After the changes are committed locally (to the ``fix_1`` branch in our
example), they need to be pushed to GitHub so they appear in the PR.
-Often it is necessary to modify the PR after it has been opened. This is
-done by adding commits to the ``fix_1`` branch and rebasing to modify the
-branch's git history. See `this tutorial
+Modifying the PR is done by adding commits to the ``fix_1`` branch upon
+which it is based, often followed by rebasing to modify the branch's git
+history. See `this tutorial
<https://www.atlassian.com/git/tutorials/rewriting-history>`_ for a good
-introduction to rebasing. When you are done with your modifications,
-you will need to force push your branch with:
+introduction to rebasing. When you are done with your modifications, you
+will need to force push your branch with:
.. code::
When this happens, it is a signal for you (or the lead who merged the PR)
to change the `Issue tracker`_ status to "Resolved". Some issues may be
flagged for backporting, in which case the status should be changed to
-"Pending Backport" (see the ``Backporting``_ chapter for details).
+"Pending Backport" (see the `Backporting`_ chapter for details).
Testing
=======
Ceph has two types of tests: "make check" tests and integration tests.
-The former are run via ``GNU Make <https://www.gnu.org/software/make/>``,
+The former are run via `GNU Make <https://www.gnu.org/software/make/>`,
and the latter are run via the `teuthology framework`_. The following two
chapters examine the "make check" and integration tests in detail.
$ ./run-make-check.sh
You will need a minimum of 8GB of RAM and 32GB of free disk space for this
-command to complete successfully. Depending on your hardware, it can take
-from 20 minutes to three hours to complete, but it's worth the wait.
+command to complete successfully on x86_64 (other architectures may have
+different constraints). Depending on your hardware, it can take from 20
+minutes to three hours to complete, but it's worth the wait.
When you fix a bug, it's a good idea to add a test. See the `Writing make
check tests`_ chapter.
the `teuthology-suite`_ command.
A number of integration tests are run on a regular basis in the `Sepia
-lab`_ against the official Ceph repositories (on the master development
+lab`_ against the official Ceph repositories (on the ``master`` development
branch and the stable branches). Traditionally, these tests are called "the
nightlies" because the Ceph core developers used to live and work in
the same time zone and from their perspective the tests were run overnight.
-The results of the nightlies are published at http://pulpito.ceph.com/
-and http://pulpito.ovh.sepia.ceph.com:8081/, and are also reported on the
-`ceph-qa mailing list <http://ceph.com/resources/mailing-list-irc/>`_ for
-analysis.
+The results of the nightlies are published at http://pulpito.ceph.com/ and
+http://pulpito.ovh.sepia.ceph.com:8081/. The developer nick shows in the
+test results URL and in the first column of the Pulpito dashboard. The
+results are also reported on the `ceph-qa mailing list
+<http://ceph.com/resources/mailing-list-irc/>`_ for analysis.
+
+Suites inventory
+----------------
+
+The ``suites`` directory of the `ceph-qa-suite repository`_ contains
+all the integration tests, for all the Ceph components.
+
+`ceph-deploy <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
+ 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>`_
+ get a machine, do nothing and return success (commonly used to
+ verify the integration testing infrastructure works as expected)
+ expected
+
+`fs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/fs>`_
+ test CephFS
+
+`kcephfs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/kcephfs>`_
+ test the CephFS kernel module
+
+`krbd <https://github.com/ceph/ceph-qa-suite/tree/master/suites/krbd>`_
+ test the RBD kernel module
+
+`powercycle <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
+ run Ceph clusters including OSDs and MONs, under various conditions of
+ stress
+
+`rbd <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
+ run RGW tests using actual Ceph clusters
+
+`smoke <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
+ verify that teuthology can run integration tests, with and without OpenStack
+
+`upgrade <https://github.com/ceph/ceph-qa-suite/tree/master/suites/upgrade>`_
+ for various versions of Ceph, verify that upgrades can happen
+ without disrupting an ongoing workload
+
+.. _`ceph-deploy man page`: ../../man/8/ceph-deploy
+.. _`ceph-disk man page`: ../../man/8/ceph-disk
+
+teuthology-describe-tests
+-------------------------
+
+In February 2016, a new feature called ``teuthology-describe-tests`` was
+added to the `teuthology framework`_ to facilitate documentation and better
+understanding of integration tests (`feature announcement
+<http://article.gmane.org/gmane.comp.file-systems.ceph.devel/29287>`_).
+
+The upshot is that tests can be documented by embedding ``meta:``
+annotations in the yaml files used to define the tests. The results can be
+seen in the `ceph-qa-suite wiki
+<http://tracker.ceph.com/projects/ceph-qa-suite/wiki/>`_.
Running integration tests
-------------------------
-Some Ceph developers have access to the `Sepia lab`_ and are allowed to
-schedule integration tests there. The developer nick shows in the test
-results URL and in the first column of the Pulpito dashboard.
+Given that - as a new Ceph developer - you will typically not have access
+to the `Sepia lab`_, you may rightly ask how you can run the integration
+tests in your own environment.
-"How can I run the integration tests in my own environment?" you may ask.
One option is to set up a teuthology cluster on bare metal. Though this is
a non-trivial task, it `is` possible. Here are `some notes
<http://docs.ceph.com/teuthology/docs/LAB_SETUP.html>`_ to get you started
if you decide to go this route.
-If you have access to an OpenStack tenant, you have another option:
-teuthology has an OpenStack backend, which is documented `here
+If you have access to an OpenStack tenant, you have another option: the
+`teuthology framework`_ has an OpenStack backend, which is documented `here
<https://github.com/dachary/teuthology/tree/openstack#openstack-backend>`_.
This OpenStack backend can build packages from a given git commit or
-branch, provision VMs in a public or private OpenStack
-instance (sometimes referred to as a "cloud"), install the packages and run
-integration tests on those VMs. This process is controlled using a tool
-called `ceph-workbench ceph-qa-suite`_. This tool also automates publishing
-of test results at http://teuthology-logs.public.ceph.com.
+branch, provision VMs in a public or private OpenStack instance (sometimes
+referred to as a "cloud"), install the packages and run integration tests
+on those VMs. This process is controlled using a tool called
+`ceph-workbench ceph-qa-suite`_. This tool also automates publishing of
+test results at http://teuthology-logs.public.ceph.com.
Running integration tests on your code contributions and publishing the
results allows reviewers to verify that changes to the code base do not
Integration tests are defined by yaml files found in the ``suites``
subdirectory of the `ceph-qa-suite repository`_ and implemented by python
code found in the ``tasks`` subdirectory. Some tests ("standalone tests")
-are defined in a single yaml file, while in others the definition is spread
-over multiple files placed within a single directory.
+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
+larger yaml file.
+
+Let us first examine a standalone test, or "singleton".
Reading a standalone test
-------------------------
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. The `install
+`ceph-qa-suite repository`_ 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>`_
-task comes first and installs the Ceph packages on each machine (as
+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>`_
The ``ceph`` task, which is documented `here
<https://github.com/ceph/ceph-qa-suite/blob/master/tasks/ceph.py>`_ (again,
-search for "def tasks"), starts OSDs and MONs (and possibly MDSs as well)
+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
-machine.
+machine. Control moves to the next task when the Ceph cluster reaches
+``HEALTH_OK`` state.
-Once the Ceph cluster is healthy, the ``admin_socket`` task (`source code
-<https://github.com/ceph/ceph-qa-suite/blob/master/tasks/admin_socket.py>`_)
-starts. 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 parameters are a set of commands to be sent
-to the admin socket of ``osd.0``. The task verifies that each of them returns
-on success (i.e. exit code zero).
+The next task is ``admin_socket`` (`source code
+<https://github.com/ceph/ceph-qa-suite/blob/master/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
+``osd.0``. The task verifies that each of them returns on success (i.e.
+exit code zero).
This test can be run with::
- teuthology-suite --suite rados/singleton/all/admin-socket.yaml
+ $ teuthology-suite --suite rados/singleton/all/admin-socket.yaml
Test descriptions
-----------------
-In the previous example, the test was defined by a single yaml file. In
-this case, the test description is simply the relative path to the yaml
-file in question.
+Each test has a "test description". In the case of a standalone test, like
+the one in the previous example, the test description is identical to the
+relative path of the yaml file starting from the ``suites/`` directory of
+the `ceph-qa-suite repository`_.
-Much more commonly, tests are defined as the concatenation of several yaml
-files. In these cases, the description of each test consists of the
+Much more commonly, tests are defined not by a single yaml file, but by a
+`directory tree of yaml files`. At runtime, the yaml files (facets) are
+combined into a single yaml file that controls the test and is reproduced
+in full at the beginning of the test log.
+
+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
-yaml files followed by an expression in curly braces (``{}``) consisting of
-a list of yaml files to be concatenated. For instance 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::
ceph-disk/basic/{distros/centos_7.0.yaml tasks/ceph-disk.yaml}
-------------------------------------
As noted in the previous section, most tests are not defined in a single
-yaml file, but rather as the concatenation of files collected from a
-directory tree within `ceph-qa-suite`_.
+yaml file, but rather as a `combination` of files collected from a
+directory tree within the ``suites/`` subdirectory of the `ceph-qa-suite repository`_.
+
+The set of all tests generated from a given subdirectory of ``suites/``
+is called an "integration test suite", or a "teuthology suite".
-The set of all tests generated from a given subdirectory of
-`ceph-qa-suite`_ is called an "integration test suite", or a "teuthology
-suite".
+Combination of yaml facets is controlled by special files (``%`` and
+``+``) that are placed within the directory tree and serve as "operators".
+The ``%`` file is the "convolution" operator and ``+`` signifies
+concatenation. This is best explained by example.
-Concatenation is triggered by the presence of special files (``%`` and
-``+``) within the directory tree in question. This is best explained by
-example.
+Convolution operator
+--------------------
-Concatenation using percent
----------------------------
+The convolution operator, implemented as an empty file called ``%``, tells
+teuthology to construct a test matrix from yaml facets found in
+subdirectories below the directory containing the operator.
-For instance, the `ceph-disk suite
+The `ceph-disk suite
<https://github.com/ceph/ceph-qa-suite/tree/master/suites/ceph-disk/>`_ is
-defined by the ``suites/ceph-disk/`` tree, which consists of the
-files and subdirectories in the following structure:
+defined by the ``suites/ceph-disk/`` tree, which consists of the files and
+subdirectories in the following structure::
directory: ceph-disk/basic
file: %
directory: tasks
file: ceph-disk.yaml
-This is interpreted as two tests: (1) the concatenation of centos_7.0.yaml
-and ceph-disk.yaml, and (2) the concatenation of ubuntu_14.04.yaml and
-ceph-disk.yaml. In accordance with teuthology usage, the test descriptions
-are:
+This is interpreted as a 2x1 matrix consisting of two tests:
1. ceph-disk/basic/{distros/centos_7.0.yaml tasks/ceph-disk.yaml}
2. ceph-disk/basic/{distros/ubuntu_14.04.yaml tasks/ceph-disk.yaml}
-(In human terms, this means that the task found in ``ceph-disk.yaml`` is
-intended to run on both CentOS 7.0 and Ubuntu 14.04.)
-
-If you look up these files in the `ceph-qa-suite`_ repo, 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
-to ``distros/centos_7.0.yaml`` and ``distros/ubuntu_14.04.yaml``,
-respectively. The practice of using symlinks instead of files enables a
-single file to be used in multiple suites.
+i.e. the concatenation of centos_7.0.yaml and ceph-disk.yaml and
+the concatenation of ubuntu_14.04.yaml and ceph-disk.yaml, respectively.
+In human terms, this means that the task found in ``ceph-disk.yaml`` is
+intended to run on both CentOS 7.0 and Ubuntu 14.04.
-The special file percent (``%``) is interpreted as a requirement to
-generate tests combining all files found in the current directory and
-in its direct subdirectories. Without the file percent, the
-``ceph-disk`` tree would be interpreted as three standalone tests:
+Without the file percent, the ``ceph-disk`` tree would be interpreted as
+three standalone tests:
* ceph-disk/basic/distros/centos_7.0.yaml
* ceph-disk/basic/distros/ubuntu_14.04.yaml
* ceph-disk/basic/tasks/ceph-disk.yaml
+Referring to the `ceph-qa-suite repository`_, 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
+suites. This eases the maintenance of the test framework as a whole.
+
All the tests generated from the ``suites/ceph-disk/`` directory tree
(also known as the "ceph-disk suite") can be run with::
--suite ceph-disk/basic \
--filter 'ceph-disk/basic/{distros/ubuntu_14.04.yaml tasks/ceph-disk.yaml}'
-Concatenation using plus
-------------------------
+Concatenation operator
+----------------------
For even greater flexibility in sharing yaml files between suites, the
special file plus (``+``) can be used to concatenate files within a
(``+``), all the other files in that subdirectory (``fixed-2.yaml`` and
``openstack.yaml`` in this case) are concatenated together
and treated as a single file. Without the special file plus, they would
-have been combined with the files from the workloads directory to create
-a matrix of four tests:
+have been convolved with the files from the workloads directory to create
+a 2x2 matrix:
* rbd/thrash/{clusters/openstack.yaml workloads/rbd_api_tests_copy_on_read.yaml}
* rbd/thrash/{clusters/openstack.yaml workloads/rbd_api_tests.yaml}
------------------------------------
When a few jobs fail and need to be run again, the ``--filter`` option
-will select the tests with a matching description. For instance if the
+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::
teuthology-suite --suite rados --filter all/peer.yaml
The ``--filter-out`` option does the opposite (it matches tests that do
-not contain a given string), and can be combined with the ``--filter``
+`not` contain a given string), and can be combined with the ``--filter``
option.
Both ``--filter`` and ``--filter-out`` take a comma-separated list of strings (which
special file ``%``) with the `fs directory
<https://github.com/ceph/ceph-qa-suite/tree/master/suites/rados/thrash/fs>`_
-All these tests are required before a Ceph release is published but it
-is too much when verifying a contribution can be merged without
-risking a trivial regression. The ``--subset`` option can be used to
+All integration tests are required to be run before a Ceph release is published.
+When merely verifying whether a contribution can be merged without
+risking a trivial regression, it is enough to run a subset. The ``--subset`` option can be used to
reduce the number of tests that are triggered. For instance::
teuthology-suite --suite rados --subset 0/4000
-will run as few tests as possible. The tradeoff is that some tests
-will only run on ``ext4`` and not on ``btrfs``, but all files in the
-suite will be in at least one test. Understanding the actual logic that
-drives this requires reading the teuthology source code.
+will run as few tests as possible. The tradeoff in this case is that some tests
+will only run on ``ext4`` and not on ``btrfs``, but no matter how small a
+ratio is provided in the ``--subset``, teuthology will still ensure that
+all files in the suite are in at least one test. Understanding the actual
+logic that drives this requires reading the teuthology source code.
The ``--limit`` option only runs the first ``N`` tests in the suite:
-this is however rarely useful because there is no way to control which test
-will be first.
-
-Suites inventory
-----------------
-
-The ``suites`` directory of the `ceph-qa-suite repository`_ contains
-all the integration tests, for all the Ceph components.
-
-`ceph-deploy <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
- 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>`_
- get a machine, do nothing and return success (commonly used to
- verify the integration testing infrastructure works as expected)
- expected
-
-`fs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/fs>`_
- test CephFS
-
-`kcephfs <https://github.com/ceph/ceph-qa-suite/tree/master/suites/kcephfs>`_
- test the CephFS kernel module
-
-`krbd <https://github.com/ceph/ceph-qa-suite/tree/master/suites/krbd>`_
- test the RBD kernel module
-
-`powercycle <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
- run Ceph clusters including OSDs and MONs, under various conditions of
- stress
-
-`rbd <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
- run RGW tests using actual Ceph clusters
-
-`smoke <https://github.com/ceph/ceph-qa-suite/tree/master/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>`_
- verify that teuthology can run integration tests, with and without OpenStack
-
-`upgrade <https://github.com/ceph/ceph-qa-suite/tree/master/suites/upgrade>`_
- for various versions of Ceph, verify that upgrades can happen
- without disrupting an ongoing workload
-
-.. _`ceph-deploy man page`: ../../man/8/ceph-deploy
-.. _`ceph-disk man page`: ../../man/8/ceph-disk
-
-Architecture
-============
-
-Ceph is a collection of components built on top of RADOS and provide
-services (RBD, RGW, CephFS) and APIs (S3, Swift, POSIX) for the user to
-store and retrieve data.
-
-See :doc:`/architecture` for an overview of Ceph architecture. The
-following sections treat each of the major architectural components
-in more detail, with links to code and tests.
-
-.. FIXME The following are just stubs. These need to be developed into
- detailed descriptions of the various high-level components (RADOS, RGW,
- etc.) with breakdowns of their respective subcomponents.
-
-.. FIXME Later, in the Testing chapter I would like to take another look
- at these components/subcomponents with a focus on how they are tested.
-
-RADOS
------
-
-RADOS stands for "Reliable, Autonomic Distributed Object Store". In a Ceph
-cluster, all data are stored in objects, and RADOS is the component responsible
-for that.
-
-RADOS itself can be further broken down into Monitors, Object Storage Daemons
-(OSDs), and client APIs (librados). Monitors and OSDs are introduced at
-:doc:`/start/intro`. The client library is explained at
-:doc:`/rados/api/index`.
-
-RGW
----
-
-RGW stands for RADOS Gateway. Using the embedded HTTP server civetweb_, RGW
-provides a REST interface to RADOS objects.
-
-.. _civetweb: https://github.com/civetweb/civetweb
-
-A more thorough introduction to RGW can be found at :doc:`/radosgw/index`.
-
-RBD
----
-
-RBD stands for RADOS Block Device. It enables a Ceph cluster to store disk
-images, and includes in-kernel code enabling RBD images to be mounted.
-
-To delve further into RBD, see :doc:`/rbd/rbd`.
-
-CephFS
-------
-
-CephFS is a distributed file system that enables a Ceph cluster to be used as a NAS.
-
-File system metadata is managed by Meta Data Server (MDS) daemons. The Ceph
-file system is explained in more detail at :doc:`/cephfs/index`.
+this is rarely useful, however, because there is no way to control which
+test will be first.
.. WIP
.. ===
..
+.. Backporting
+.. -----------
+..
.. Building RPM packages
.. ---------------------
..
projects / ceph.git / commitdiff