diff --git a/doc/source/api.rst b/doc/source/api.rst index 03cb8ad..45dde67 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -1,6 +1,6 @@ -========== -Public API -========== +============= +API Reference +============= .. automodule:: os_faults :members: diff --git a/doc/source/cli.rst b/doc/source/cli.rst index 2aa2e1c..61eb62c 100644 --- a/doc/source/cli.rst +++ b/doc/source/cli.rst @@ -2,4 +2,38 @@ CLI reference ============= + +os-inject-fault +--------------- + .. program-output:: os-inject-fault --help + + +os-faults +--------- + +.. program-output:: os-faults --help + + +os-faults verify +---------------- + +.. program-output:: os-faults verify --help + + +os-faults discover +------------------ + +.. program-output:: os-faults discover --help + + +os-faults nodes +--------------- + +.. program-output:: os-faults nodes --help + + +os-faults drivers +----------------- + +.. program-output:: os-faults drivers --help diff --git a/doc/source/conf.py b/doc/source/conf.py index ff26e2e..5fb7c4e 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,16 +21,21 @@ sys.path.insert(0, os.path.abspath('..')) sys.path.insert(0, os.path.abspath('../..')) # -- General configuration ---------------------------------------------------- +on_zuul = "ZUUL_PROJECT" in os.environ + # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosectionlabel', #'sphinx.ext.intersphinx', 'sphinxcontrib.programoutput', - 'oslosphinx', 'ext.driver_doc', ] +if on_zuul: + extensions.append('oslosphinx') + version = os_faults.get_version() # The full version, including alpha/beta/rc tags. release = os_faults.get_release() @@ -69,6 +74,8 @@ modindex_common_prefix = ['os_faults.'] # html_theme_path = ["."] # html_theme = '_theme' # html_static_path = ['static'] +if not on_zuul: + html_theme = "sphinx_rtd_theme" # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project diff --git a/doc/source/drivers.rst b/doc/source/drivers.rst index 6ba3e62..706a2a1 100644 --- a/doc/source/drivers.rst +++ b/doc/source/drivers.rst @@ -26,8 +26,8 @@ Node discover .. driver_doc:: node_list -Services --------- +Service drivers +--------------- .. driver_doc:: process diff --git a/doc/source/index.rst b/doc/source/index.rst index 6b34374..4f0a241 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,13 +13,12 @@ Contents ======== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 - installation - usage + quickstart/index cli - api drivers + api contributing Release Notes diff --git a/doc/source/usage.rst b/doc/source/quickstart/api.rst similarity index 72% rename from doc/source/usage.rst rename to doc/source/quickstart/api.rst index 35c1fe6..bd15a4b 100644 --- a/doc/source/usage.rst +++ b/doc/source/quickstart/api.rst @@ -1,56 +1,6 @@ -===== -Usage -===== - -Configuration -------------- - -The cloud deployment configuration schema is an extension to the cloud config -used by the `os-client-config `_ -library: - -.. code-block:: python - - cloud_config = { - 'cloud_management': { - 'driver': 'devstack', - 'args': { - 'address': 'devstack.local', - 'username': 'root', - } - }, - 'power_managements': [ - { - 'driver': 'libvirt', - 'args': { - 'connection_uri': 'qemu+unix:///system', - } - } - ] - } - -Establish a connection to the cloud and verify it: - -.. code-block:: python - - destructor = os_faults.connect(cloud_config) - destructor.verify() - -The library can also read configuration from a file and the file can be in the -following three formats: os-faults.{json,yaml,yml}. The configuration file can -be specified in the `OS_FAULTS_CONFIG` environment variable or can be read from -one of the default locations: - - * current directory - * ~/.config/os-faults - * /etc/openstack - -Make some destructive actions: - -.. code-block:: python - - destructor.get_service(name='keystone').restart() - +=== +API +=== The library operates with 2 types of objects: @@ -63,6 +13,13 @@ Simplified API Simplified API is used to inject faults in a human-friendly form. +.. code-block:: python + + import os_faults + destructor = os_faults.connect(config_filename='os-faults.yaml') + os_faults.human_api(destructor, 'restart keystone service') + + **Service-oriented** command performs specified `action` against `service` on all, on one random node or on the node specified by FQDN:: diff --git a/doc/source/quickstart/basics.rst b/doc/source/quickstart/basics.rst new file mode 100644 index 0000000..d635981 --- /dev/null +++ b/doc/source/quickstart/basics.rst @@ -0,0 +1,68 @@ +====== +Basics +====== + + +Configuration file +------------------ + +The cloud deployment configuration schema is an extension to the cloud config +used by the `os-client-config `_ +library: + +.. code-block:: yaml + + cloud_management: + driver: devstack + args: + address: 192.168.1.240 + username: ubuntu + iface: enp0s3 + + power_managements: + - driver: libvirt + args: + connection_uri: qemu+ssh://ubuntu@10.0.1.50/system + + +By default, the library reads configuration from a file and the file can be in +the following three formats: ``os-faults.{json,yaml,yml}``. The configuration +file will be searched in the default locations: + + * current directory + * ~/.config/os-faults + * /etc/openstack + +Also, the configuration file can be specified in the ``OS_FAULTS_CONFIG`` +environment variable:: + + $ export OS_FAULTS_CONFIG=/home/alex/my-os-faults-config.yaml + + +Running +------- + +Establish a connection to the cloud and verify it: + +.. code-block:: python + + import os_faults + destructor = os_faults.connect(config_filename='os-faults.yaml') + destructor.verify() + + +or via CLI:: + + $ os-faults verify -c os-faults.yaml + + +Make some destructive actions: + +.. code-block:: python + + destructor.get_service(name='keystone').restart() + + +or via CLI:: + + $ os-inject-fault -c os-faults.yaml restart keystone service diff --git a/doc/source/quickstart/config_spec.rst b/doc/source/quickstart/config_spec.rst new file mode 100644 index 0000000..484607d --- /dev/null +++ b/doc/source/quickstart/config_spec.rst @@ -0,0 +1,158 @@ +=========================== +Configuration specification +=========================== + +Configuration file contains the following parameters: + + * cloud_management + * power_managements + * node_discover + * services + +Each parameter specifies a driver or a list of drivers. + +Example configuration: + +.. code-block:: yaml + + cloud_management: + driver: devstack + args: + address: 192.168.1.240 + username: ubuntu + iface: enp0s3 + + power_managements: + - driver: libvirt + args: + connection_uri: qemu+ssh://ubuntu@10.0.1.50/system + + - driver: ipmi + args: + fqdn_to_bmc: + node-1.domain.tld: + address: 120.10.30.65 + username: alex + password: super-secret + + node_discover: + driver: node_list + args: + - fqdn: node-1.domain.tld + ip: 192.168.1.240 + mac: 1e:24:c3:75:dd:2c + + services: + glance-api: + driver: screen + args: + grep: glance-api + window_name: g-api + hosts: + - 192.168.1.240 + + +cloud_management +---------------- + +This parameter specifies cloud managment driver and its argumanets. +``cloud_management`` is responsible for configuring connection to nodes +and contains arguments such as SSH username/password/key/proxy. + +.. code-block:: yaml + + cloud_management: + driver: devstack # name of the driver + args: # arguments for the driver + address: 192.168.1.240 + username: ubuntu + iface: enp0s3 + + +Also, such drivers can support discovering of cloud nodes. For example, +``fuel``, ``tcpcloud`` drives allow discovering information about nodes +through master/config node of the cloud. + +List of supported drivers for cloud_management: :ref:`Cloud management` + + +power_managements +----------------- + +This parameter specifies list of power management drivers. Such drivers +allow controlling power state of cloud nodes. + +.. code-block:: yaml + + power_managements: + - driver: libvirt # name of the driver + args: # arguments for the driver + connection_uri: qemu+ssh://ubuntu@10.0.1.50/system + + - driver: ipmi # name of the driver + args: # arguments for the driver + fqdn_to_bmc: + node-1.domain.tld: + address: 120.10.30.65 + username: alex + password: super-secret + + +List of supported drivers for power_managements: :ref:`Power management` + + +node_discover +------------- + +This parameter specifies node discover driver. ``node_discover`` is responsible +for fetching list of hosts for the cloud. If ``node_discover`` is specified in +configuration then ``cloud_management`` will only control connection options to +the nodes. + +.. code-block:: yaml + + node_discover: + driver: node_list + args: + - fqdn: node-1.domain.tld + ip: 192.168.1.240 + mac: 1e:24:c3:75:dd:2c + +List of supported drivers for node_discover: :ref:`Node discover` + + +services +-------- + +This parameter specifies list of services and their types. This parameter +allows updating/adding services which are embedded in ``cloud_management`` +driver. + +.. code-block:: yaml + + services: + glance-api: # name of the service + driver: screen # name of the service driver + args: # arguments for the driver + grep: glance-api + window_name: g-api + hosts: # list of hosts where this service running + - 192.168.1.240 + mysql: # name of the service + driver: process # name of the service driver + args: # arguments for the driver + grep: mysqld + port: + - tcp + - 3307 + restart_cmd: sudo service mysql restart + start_cmd: sudo service mysql start + terminate_cmd: sudo service mysql stop + + +Service driver contains optional ``hosts`` parameter which controls discovering +of hosts where the service is running. If ``hosts`` specified, then service +discovering is disabled for this service and hosts specified in ``hosts`` will +be used, otherwise, service will be searched across all nodes. + +List of supported drivers for services: :ref:`Service drivers` diff --git a/doc/source/quickstart/index.rst b/doc/source/quickstart/index.rst new file mode 100644 index 0000000..f481bd2 --- /dev/null +++ b/doc/source/quickstart/index.rst @@ -0,0 +1,13 @@ +========== +Quickstart +========== + +This section describes how to start using os-faults. + +.. toctree:: + :maxdepth: 2 + + installation + basics + api + config_spec diff --git a/doc/source/installation.rst b/doc/source/quickstart/installation.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/quickstart/installation.rst diff --git a/test-requirements.txt b/test-requirements.txt index a8c3590..8871145 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -14,6 +14,7 @@ mock>=2.0 # BSD python-subunit>=0.0.18 # Apache-2.0/BSD sphinx>=1.5.1 # BSD sphinxcontrib-programoutput # BSD +sphinx_rtd_theme # MIT oslosphinx>=4.7.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 testrepository>=0.0.18 # Apache-2.0/BSD diff --git a/tox.ini b/tox.ini index fc1da5a..9e1f0c6 100644 --- a/tox.ini +++ b/tox.ini @@ -31,7 +31,7 @@ commands = flake8 . doc/ext [testenv:pep8-constraints] install_command = {[testenv:common-constraints]install_command} -commands = flake8 . doc/ext +commands = {[testenv:pep8]commands} [testenv:venv] commands = {posargs} @@ -48,12 +48,12 @@ commands = [testenv:cover-constraints] install_command = {[testenv:common-constraints]install_command} -commands = python setup.py test --coverage --testr-args='{posargs}' +commands = {[testenv:cover]commands} [testenv:docs] commands = rm -rf doc/build - python setup.py build_sphinx + python setup.py build_sphinx --warning-is-error [testenv:releasenotes] commands = @@ -61,14 +61,15 @@ commands = [testenv:docs-constraints] install_command = {[testenv:common-constraints]install_command} -commands = python setup.py build_sphinx +commands = {[testenv:docs]commands} [testenv:debug] commands = oslo_debug_helper {posargs} [testenv:debug-constraints] install_command = {[testenv:common-constraints]install_command} -commands = oslo_debug_helper {posargs} +commands = {[testenv:debug]commands} + [flake8] # E123 skipped because it is ignored by default in the default pep8.