From 7412c085f0a3f4ddc6426ee623ed9d120b2e154d Mon Sep 17 00:00:00 2001 From: Alfredo Deza Date: Wed, 12 Apr 2017 13:12:00 -0400 Subject: [PATCH] docs: scenario files and section descriptions Signed-off-by: Alfredo Deza --- docs/source/testing/scenarios.rst | 121 +++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 1 deletion(-) diff --git a/docs/source/testing/scenarios.rst b/docs/source/testing/scenarios.rst index b65029a9a..3d0f1161a 100644 --- a/docs/source/testing/scenarios.rst +++ b/docs/source/testing/scenarios.rst @@ -3,16 +3,135 @@ Test Scenarios ============== +Scenarios are distinct environments that describe a Ceph deployment and +configuration. Scenarios are isolated as well, and define what machines are +needed aside from any ceph-ansible configuration. .. _scenario_files: Scenario Files --------------- +============== +The scenario is described in a ``vagrant_variables.yml`` file, which is +consumed by ``Vagrant`` when bringing up an environment. + +This yaml file is loaded in the ``Vagrantfile`` so that the settings can be +used to bring up the boxes and pass some configuration to ansible when running. + +.. note:: The basic layout of a scenario is covered in :ref:`layout` +There are just a handful of required files, this is the most basic layout +nece + +There are a few sections in the ``vagrant_variables.yml`` file which are easy +to follow (most of them are 1 line settings). + + +* **docker**: (bool) Indicates if the scenario will deploy docker daemons + +* **VMS**: (int) These integer values are just a count of how many machines will be + needed. Each supported type is listed, defaulting to 0:: + + mon_vms: 0 + osd_vms: 0 + mds_vms: 0 + rgw_vms: 0 + nfs_vms: 0 + rbd_mirror_vms: 0 + client_vms: 0 + iscsi_gw_vms: 0 + mgr_vms: 0 + + For a deployment that needs 1 MON and 1 OSD, the list would look like:: + + mon_vms: 1 + osd_vms: 1 + +* **RESTAPI**: (bool) Deploy RESTAPI on each of the monitor(s) +restapi: true + +* **CEPH SOURCE**: (string) indicate whether a ``dev`` or ``stable`` release is + needed. A ``stable`` release will use the latest stable release of Ceph, + a ``dev`` will use ``shaman`` (http://shaman.ceph.com) + +* **SUBNETS**: These are used for configuring the network availability of each + server that will be booted as well as being used as configuration for + ceph-ansible (and eventually ceph). The two values that are **required**:: + + public_subnet: 192.168.13 + cluster_subnet: 192.168.14 + +* **MEMORY**: Memory requirements (in megabytes) for each server, e.g. + ``memory: 512`` + +* **interfaces**: some vagrant boxes (and linux distros) set specific + interfaces. For Ubuntu releases older than Xenial it was common to have + ``eth1``, for CentOS and some Xenial boxes ``enp0s8`` is used. **However** + the public Vagrant boxes normalize the interface to ``eth1`` for all boxes, + making it easier to configure them with Ansible later. + +.. warning:: Do *not* change the interface from ``eth1`` unless absolutely + certain that is needed for a box. Some tests that depend on that + naming will fail. + +* **disks**: The disks that will be created for each machine, for most + environments ``/dev/sd*`` style of disks will work, like: ``[ '/dev/sda', '/dev/sdb' ]`` + +* **vagrant_box**: We have published our own boxes to normalize what we test + against. These boxes are published in Atlas + (https://atlas.hashicorp.com/ceph/). Currently valid values are: + ``ceph/ubuntu-xenial``, and ``ceph/centos7`` + +The following aren't usually changed/enabled for tests, since they don't have +an impact, however they are documented here for general knowledge in case they +are needed: + +* **ssh_private_key_path** : The path to the ``id_rsa`` (or other private SSH + key) that should be used to connect to these boxes. + +* **vagrant_sync_dir** : what should be "synced" (made available on the new + servers) from the host. + +* **vagrant_disable_synced_folder** : (bool) when disabled, it will make + booting machines faster because no files need to be synced over. + +* **os_tuning_params** : These are passed onto ceph-ansible as part of the + variables for "system tunning". These shouldn't be changed. + .. _scenario_wiring: Scenario Wiring --------------- +Scenarios are just meant to provide the Ceph environment for testing, but they +do need to be defined in the ``tox.ini`` so that they are available to the test +framework. To see a list of available scenarios, the following command (ran +from the root of the project) will list them, shortened for brevity:: + + $ tox -l + ... + jewel-ansible2.2-centos7_cluster + ... + + These scenarios are made from different variables, in the above command there + are 3: + +* jewel: the Ceph version to test +* ansible2.2: the Ansible version to install +* ``centos7_cluster``: the name of the scenario + +The last one is important in the *wiring up* of the scenario. It is a variable +that will define in what path the scenario lives. For example, the +``changedir`` section for ``centos7_cluster`` that looks like:: + + centos7_cluster: {toxinidir}/tests/functional/centos/7/cluster + +The actual tests are written for specific daemon types, for all daemon types, +and for specific use cases (e.g. journal collocation), those have their own +conventions as well which are explained in detail in :ref:`test_conventions` +and :ref:`test_files`. + +As long as a test scenario defines OSDs and MONs, the OSD tests and MON tests +will run. + .. _scenario_conventions: