=========
OS-Faults
=========
**OpenStack fault-injection library**
The library does destructive actions inside an OpenStack cloud. It provides
an abstraction layer over different types of cloud deployments. The actions
are implemented as drivers (e.g. DevStack driver, Fuel driver, Libvirt driver,
IPMI driver, Universal driver).
* Free software: Apache license
* Documentation: https://os-faults.readthedocs.io/
* Source: https://opendev.org/performa/os-faults/
* Bugs: https://bugs.launchpad.net/os-faults
Installation
------------
Requirements
~~~~~~~~~~~~
Ansible is required and should be installed manually system-wide or in virtual
environment. Please refer to [https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html]
for installation instructions.
Regular installation::
pip install os-faults
The library contains optional libvirt driver [https://pypi.org/project/libvirt-python/], if you plan to use it,
please use the following command to install os-faults with extra dependencies::
pip install os-faults libvirt-python
Configuration
-------------
The cloud deployment configuration is specified in JSON/YAML format or Python dictionary.
The library operates with 2 types of objects:
* `service` - is a software that runs in the cloud, e.g. `nova-api`
* `container` - is a software that runs in the cloud, e.g. `neutron_api`
* `nodes` - nodes that host the cloud, e.g. a server with a hostname
Example 1. DevStack
~~~~~~~~~~~~~~~~~~~
Connection to DevStack can be specified using the following YAML file:
.. code-block:: yaml
cloud_management:
driver: devstack
args:
address: devstack.local
auth:
username: stack
private_key_file: cloud_key
iface: enp0s8
OS-Faults library will connect to DevStack by address `devstack.local` with user `stack`
and SSH key located in file `cloud_key`. Default networking interface is specified with
parameter `iface`. Note that user should have sudo permissions (by default DevStack user has them).
DevStack driver is responsible for service discovery. For more details please refer
to driver documentation: http://os-faults.readthedocs.io/en/latest/drivers.html#devstack-systemd-devstackmanagement
Example 2. An OpenStack with services, containers and power management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An arbitrary OpenStack can be handled too with help of `universal` driver.
In this example os-faults is used as Python library.
.. code-block:: python
cloud_config = {
'cloud_management': {
'driver': 'universal',
},
'node_discover': {
'driver': 'node_list',
'args': [
{
'ip': '192.168.5.127',
'auth': {
'username': 'root',
'private_key_file': 'openstack_key',
}
},
{
'ip': '192.168.5.128',
'auth': {
'username': 'root',
'private_key_file': 'openstack_key',
}
}
]
},
'services': {
'memcached': {
'driver': 'system_service',
'args': {
'service_name': 'memcached',
'grep': 'memcached',
}
}
},
'containers': {
'neutron_api': {
'driver': 'docker_container',
'args': {
'container_name': 'neutron_api',
}
}
},
'power_managements': [
{
'driver': 'libvirt',
'args': {
'connection_uri': 'qemu+unix:///system',
}
},
]
}
The config contains all OpenStack nodes with credentials and all
services/containers. OS-Faults will automatically figure out the mapping
between services/containers and nodes. Power management configuration is
flexible and supports mixed bare-metal / virtualized deployments.
First let's establish a connection to the cloud and verify it:
.. code-block:: python
cloud_management = os_faults.connect(cloud_config)
cloud_management.verify()
The library can also read configuration from a file in YAML or JSON format.
The configuration file can be specified in the `OS_FAULTS_CONFIG` environment
variable. By default the library searches for file `os-faults.{json,yaml,yml}`
in one of locations:
* current directory
* ~/.config/os-faults
* /etc/openstack
Now let's make some destructive action:
.. code-block:: python
cloud_management.get_service(name='memcached').kill()
cloud_management.get_container(name='neutron_api').restart()
Human API
---------
Human API is simplified and self-descriptive. It includes multiple commands
that are written like normal English sentences.
**Service-oriented** command performs specified `action` against `service` on
all, on one random node or on the node specified by FQDN::
<action> <service> service [on (random|one|single|<fqdn> node[s])]
Examples:
* `Restart Keystone service` - restarts Keystone service on all nodes.
* `kill nova-api service on one node` - kills Nova API on one
randomly-picked node.
**Container-oriented** command performs specified `action` against `container`
on all, on one random node or on the node specified by FQDN::
<action> <container> container [on (random|one|single|<fqdn> node[s])]
Examples:
* `Restart neutron_ovs_agent container` - restarts neutron_ovs_agent
container on all nodes.
* `Terminate neutron_api container on one node` - stops Neutron API
container on one randomly-picked node.
**Node-oriented** command performs specified `action` on node specified by FQDN
or set of service's nodes::
<action> [random|one|single|<fqdn>] node[s] [with <service> service]
Examples:
* `Reboot one node with mysql` - reboots one random node with MySQL.
* `Reset node-2.domain.tld node` - resets node `node-2.domain.tld`.
**Network-oriented** command is a subset of node-oriented and performs network
management operation on selected nodes::
<action> <network> network on [random|one|single|<fqdn>] node[s]
[with <service> service]
Examples:
* `Disconnect management network on nodes with rabbitmq service` - shuts
down management network interface on all nodes where rabbitmq runs.
* `Connect storage network on node-1.domain.tld node` - enables storage
network interface on node-1.domain.tld.
Extended API
------------
1. Service actions
~~~~~~~~~~~~~~~~~~
Get a service and restart it:
.. code-block:: python
cloud_management = os_faults.connect(cloud_config)
service = cloud_management.get_service(name='glance-api')
service.restart()
Available actions:
* `start` - start Service
* `terminate` - terminate Service gracefully
* `restart` - restart Service
* `kill` - terminate Service abruptly
* `unplug` - unplug Service out of network
* `plug` - plug Service into network
2. Container actions
~~~~~~~~~~~~~~~~~~~~
Get a container and restart it:
.. code-block:: python
cloud_management = os_faults.connect(cloud_config)
container = cloud_management.get_container(name='neutron_api')
container.restart()
Available actions:
* `start` - start Container
* `terminate` - terminate Container gracefully
* `restart` - restart Container
3. Node actions
~~~~~~~~~~~~~~~
Get all nodes in the cloud and reboot them:
.. code-block:: python
nodes = cloud_management.get_nodes()
nodes.reboot()
Available actions:
* `reboot` - reboot all nodes gracefully
* `poweroff` - power off all nodes abruptly
* `reset` - reset (cold restart) all nodes
* `disconnect` - disable network with the specified name on all nodes
* `connect` - enable network with the specified name on all nodes
4. Operate with nodes
~~~~~~~~~~~~~~~~~~~~~
Get all nodes where a service runs, pick one of them and reset:
.. code-block:: python
nodes = service.get_nodes()
one = nodes.pick()
one.reset()
Get nodes where l3-agent runs and disable the management network on them:
.. code-block:: python
fqdns = neutron.l3_agent_list_hosting_router(router_id)
nodes = cloud_management.get_nodes(fqdns=fqdns)
nodes.disconnect(network_name='management')
5. Operate with services
~~~~~~~~~~~~~~~~~~~~~~~~
Restart a service on a single node:
.. code-block:: python
service = cloud_management.get_service(name='keystone')
nodes = service.get_nodes().pick()
service.restart(nodes)
6. Operate with containers
~~~~~~~~~~~~~~~~~~~~~~~~~~
Terminate a container on a random node:
.. code-block:: python
container = cloud_management.get_container(name='neutron_ovs_agent')
nodes = container.get_nodes().pick()
container.restart(nodes)
License notes
-------------
Ansible is distributed under GPL-3.0 license and thus all programs
that link with its code are subject to GPL restrictions [1].
However these restrictions are not applied to os-faults library
since it invokes Ansible as process [2][3].
Ansible modules are provided with Apache license (compatible to GPL) [4].
Those modules import part of Ansible runtime (modules API) and executed
on remote hosts. os-faults library does not import these module
neither static nor dynamic.
[1] https://www.gnu.org/licenses/gpl-faq.html#GPLModuleLicense
[2] https://www.gnu.org/licenses/gpl-faq.html#GPLPlugins
[3] https://www.gnu.org/licenses/gpl-faq.html#MereAggregation
[4] https://www.apache.org/licenses/GPL-compatibility.html
Raw data
{
"_id": null,
"home_page": "http://os-faults.readthedocs.io/",
"name": "os-faults",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "OpenStack",
"author_email": "openstack-discuss@lists.openstack.org",
"download_url": "https://files.pythonhosted.org/packages/0e/fa/4f96e72bede494f7af3b574a2a5d4512f2d3a663db17190541e28061cdb4/os_faults-0.3.0.tar.gz",
"platform": null,
"description": "=========\nOS-Faults\n=========\n\n**OpenStack fault-injection library**\n\nThe library does destructive actions inside an OpenStack cloud. It provides\nan abstraction layer over different types of cloud deployments. The actions\nare implemented as drivers (e.g. DevStack driver, Fuel driver, Libvirt driver,\nIPMI driver, Universal driver).\n\n* Free software: Apache license\n* Documentation: https://os-faults.readthedocs.io/\n* Source: https://opendev.org/performa/os-faults/\n* Bugs: https://bugs.launchpad.net/os-faults\n\n\nInstallation\n------------\n\nRequirements\n~~~~~~~~~~~~\n\nAnsible is required and should be installed manually system-wide or in virtual\nenvironment. Please refer to [https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html]\nfor installation instructions.\n\nRegular installation::\n\n pip install os-faults\n\nThe library contains optional libvirt driver [https://pypi.org/project/libvirt-python/], if you plan to use it,\nplease use the following command to install os-faults with extra dependencies::\n\n pip install os-faults libvirt-python\n\n\nConfiguration\n-------------\n\nThe cloud deployment configuration is specified in JSON/YAML format or Python dictionary.\n\nThe library operates with 2 types of objects:\n * `service` - is a software that runs in the cloud, e.g. `nova-api`\n * `container` - is a software that runs in the cloud, e.g. `neutron_api`\n * `nodes` - nodes that host the cloud, e.g. a server with a hostname\n\n\nExample 1. DevStack\n~~~~~~~~~~~~~~~~~~~\n\nConnection to DevStack can be specified using the following YAML file:\n\n.. code-block:: yaml\n\n cloud_management:\n driver: devstack\n args:\n address: devstack.local\n auth:\n username: stack\n private_key_file: cloud_key\n iface: enp0s8\n\nOS-Faults library will connect to DevStack by address `devstack.local` with user `stack`\nand SSH key located in file `cloud_key`. Default networking interface is specified with\nparameter `iface`. Note that user should have sudo permissions (by default DevStack user has them).\n\nDevStack driver is responsible for service discovery. For more details please refer\nto driver documentation: http://os-faults.readthedocs.io/en/latest/drivers.html#devstack-systemd-devstackmanagement\n\nExample 2. An OpenStack with services, containers and power management\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAn arbitrary OpenStack can be handled too with help of `universal` driver.\nIn this example os-faults is used as Python library.\n\n.. code-block:: python\n\n cloud_config = {\n 'cloud_management': {\n 'driver': 'universal',\n },\n 'node_discover': {\n 'driver': 'node_list',\n 'args': [\n {\n 'ip': '192.168.5.127',\n 'auth': {\n 'username': 'root',\n 'private_key_file': 'openstack_key',\n }\n },\n {\n 'ip': '192.168.5.128',\n 'auth': {\n 'username': 'root',\n 'private_key_file': 'openstack_key',\n }\n }\n ]\n },\n 'services': {\n 'memcached': {\n 'driver': 'system_service',\n 'args': {\n 'service_name': 'memcached',\n 'grep': 'memcached',\n }\n }\n },\n 'containers': {\n 'neutron_api': {\n 'driver': 'docker_container',\n 'args': {\n 'container_name': 'neutron_api',\n }\n }\n },\n 'power_managements': [\n {\n 'driver': 'libvirt',\n 'args': {\n 'connection_uri': 'qemu+unix:///system',\n }\n },\n ]\n }\n\nThe config contains all OpenStack nodes with credentials and all\nservices/containers. OS-Faults will automatically figure out the mapping\nbetween services/containers and nodes. Power management configuration is\nflexible and supports mixed bare-metal / virtualized deployments.\n\nFirst let's establish a connection to the cloud and verify it:\n\n.. code-block:: python\n\n cloud_management = os_faults.connect(cloud_config)\n cloud_management.verify()\n\nThe library can also read configuration from a file in YAML or JSON format.\nThe configuration file can be specified in the `OS_FAULTS_CONFIG` environment\nvariable. By default the library searches for file `os-faults.{json,yaml,yml}`\nin one of locations:\n\n * current directory\n * ~/.config/os-faults\n * /etc/openstack\n\nNow let's make some destructive action:\n\n.. code-block:: python\n\n cloud_management.get_service(name='memcached').kill()\n cloud_management.get_container(name='neutron_api').restart()\n\n\nHuman API\n---------\n\nHuman API is simplified and self-descriptive. It includes multiple commands\nthat are written like normal English sentences.\n\n**Service-oriented** command performs specified `action` against `service` on\nall, on one random node or on the node specified by FQDN::\n\n <action> <service> service [on (random|one|single|<fqdn> node[s])]\n\nExamples:\n * `Restart Keystone service` - restarts Keystone service on all nodes.\n * `kill nova-api service on one node` - kills Nova API on one\n randomly-picked node.\n\n**Container-oriented** command performs specified `action` against `container`\non all, on one random node or on the node specified by FQDN::\n\n <action> <container> container [on (random|one|single|<fqdn> node[s])]\n\nExamples:\n * `Restart neutron_ovs_agent container` - restarts neutron_ovs_agent\n container on all nodes.\n * `Terminate neutron_api container on one node` - stops Neutron API\n container on one randomly-picked node.\n\n**Node-oriented** command performs specified `action` on node specified by FQDN\nor set of service's nodes::\n\n <action> [random|one|single|<fqdn>] node[s] [with <service> service]\n\nExamples:\n * `Reboot one node with mysql` - reboots one random node with MySQL.\n * `Reset node-2.domain.tld node` - resets node `node-2.domain.tld`.\n\n**Network-oriented** command is a subset of node-oriented and performs network\nmanagement operation on selected nodes::\n\n <action> <network> network on [random|one|single|<fqdn>] node[s]\n [with <service> service]\n\nExamples:\n * `Disconnect management network on nodes with rabbitmq service` - shuts\n down management network interface on all nodes where rabbitmq runs.\n * `Connect storage network on node-1.domain.tld node` - enables storage\n network interface on node-1.domain.tld.\n\n\nExtended API\n------------\n\n1. Service actions\n~~~~~~~~~~~~~~~~~~\n\nGet a service and restart it:\n\n.. code-block:: python\n\n cloud_management = os_faults.connect(cloud_config)\n service = cloud_management.get_service(name='glance-api')\n service.restart()\n\nAvailable actions:\n * `start` - start Service\n * `terminate` - terminate Service gracefully\n * `restart` - restart Service\n * `kill` - terminate Service abruptly\n * `unplug` - unplug Service out of network\n * `plug` - plug Service into network\n\n2. Container actions\n~~~~~~~~~~~~~~~~~~~~\n\nGet a container and restart it:\n\n.. code-block:: python\n\n cloud_management = os_faults.connect(cloud_config)\n container = cloud_management.get_container(name='neutron_api')\n container.restart()\n\nAvailable actions:\n * `start` - start Container\n * `terminate` - terminate Container gracefully\n * `restart` - restart Container\n\n3. Node actions\n~~~~~~~~~~~~~~~\n\nGet all nodes in the cloud and reboot them:\n\n.. code-block:: python\n\n nodes = cloud_management.get_nodes()\n nodes.reboot()\n\nAvailable actions:\n * `reboot` - reboot all nodes gracefully\n * `poweroff` - power off all nodes abruptly\n * `reset` - reset (cold restart) all nodes\n * `disconnect` - disable network with the specified name on all nodes\n * `connect` - enable network with the specified name on all nodes\n\n4. Operate with nodes\n~~~~~~~~~~~~~~~~~~~~~\n\nGet all nodes where a service runs, pick one of them and reset:\n\n.. code-block:: python\n\n nodes = service.get_nodes()\n one = nodes.pick()\n one.reset()\n\nGet nodes where l3-agent runs and disable the management network on them:\n\n.. code-block:: python\n\n fqdns = neutron.l3_agent_list_hosting_router(router_id)\n nodes = cloud_management.get_nodes(fqdns=fqdns)\n nodes.disconnect(network_name='management')\n\n5. Operate with services\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nRestart a service on a single node:\n\n.. code-block:: python\n\n service = cloud_management.get_service(name='keystone')\n nodes = service.get_nodes().pick()\n service.restart(nodes)\n\n6. Operate with containers\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTerminate a container on a random node:\n\n.. code-block:: python\n\n container = cloud_management.get_container(name='neutron_ovs_agent')\n nodes = container.get_nodes().pick()\n container.restart(nodes)\n\n\nLicense notes\n-------------\n\nAnsible is distributed under GPL-3.0 license and thus all programs\nthat link with its code are subject to GPL restrictions [1].\nHowever these restrictions are not applied to os-faults library\nsince it invokes Ansible as process [2][3].\n\nAnsible modules are provided with Apache license (compatible to GPL) [4].\nThose modules import part of Ansible runtime (modules API) and executed\non remote hosts. os-faults library does not import these module\nneither static nor dynamic.\n\n [1] https://www.gnu.org/licenses/gpl-faq.html#GPLModuleLicense\n [2] https://www.gnu.org/licenses/gpl-faq.html#GPLPlugins\n [3] https://www.gnu.org/licenses/gpl-faq.html#MereAggregation\n [4] https://www.apache.org/licenses/GPL-compatibility.html\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenStack fault-injection library",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://bugs.launchpad.net/os-faults",
"Documentation": "http://os-faults.readthedocs.io/",
"Download": "https://pypi.org/project/os-faults/",
"Homepage": "http://os-faults.readthedocs.io/",
"Source Code": "https://opendev.org/performa/os-faults/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0c47ae02a4474a056c1876f8e8865630e7b1c8281af5247e109526114b8d4ba",
"md5": "4c938ca25e8ad92a2d10f68604bd4dc2",
"sha256": "629e9915e07aec9a575e0873c830b398e4e55330a95dc3099c6852163a14c8e6"
},
"downloads": -1,
"filename": "os_faults-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c938ca25e8ad92a2d10f68604bd4dc2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 88294,
"upload_time": "2024-11-27T21:57:17",
"upload_time_iso_8601": "2024-11-27T21:57:17.081325Z",
"url": "https://files.pythonhosted.org/packages/e0/c4/7ae02a4474a056c1876f8e8865630e7b1c8281af5247e109526114b8d4ba/os_faults-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0efa4f96e72bede494f7af3b574a2a5d4512f2d3a663db17190541e28061cdb4",
"md5": "a5809ca3c7a14fad203a961b289598f8",
"sha256": "6381aa3e2287cad16f30c1a51907bb0620af518f013e0bb4ac6e948f95837426"
},
"downloads": -1,
"filename": "os_faults-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a5809ca3c7a14fad203a961b289598f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 79381,
"upload_time": "2024-11-27T21:57:19",
"upload_time_iso_8601": "2024-11-27T21:57:19.097372Z",
"url": "https://files.pythonhosted.org/packages/0e/fa/4f96e72bede494f7af3b574a2a5d4512f2d3a663db17190541e28061cdb4/os_faults-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-27 21:57:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "os-faults"
}
JSON