diff --git a/README.rst b/README.rst index 75ae657..62fc045f 100644 --- a/README.rst +++ b/README.rst @@ -1,36 +1,70 @@ -ospurge: OpenStack project resources cleaner -******************************************** +OpenStack project resources cleaner +=================================== -``ospurge`` is a standalone, client-side, Python script that aims at -deleting all resources (taking into account their interdependencies) -in a specified OpenStack project. OSPurge ensures in a quick and -automated way that no resource is left behind when a project is -deleted. +* ``ospurge`` is a standalone, client-side, operators tool that aims at + deleting all resources, taking into account their interdependencies, + in a specified OpenStack project. + +* ``ospurge`` ensures in a quick and automated way that no resource is + left behind when a project is deleted. + +* ``ospurge`` can be used by a cloud administrator, this means a user with the + admin role, to cleanup any project or by a non-privileged user to cleanup his + own project. + + +Supported resources +------------------- + +At the moment it is possible to purge the following resources from a project: + +* Ceilometer alarms +* floating IP addresses +* images / snapshots +* instances +* networks +* routers +* security groups +* Swift containers +* Swift objects +* volumes / snapshots + + +Error codes +----------- + +The following error codes are returned when ``ospurge`` encounters +an error: + +* ``Code 0``: Process exited sucessfully +* ``Code 1``: Unknown error +* ``Code 2``: Project doesn't exist +* ``Code 3``: Authentication failed (e.g. bad username or password) +* ``Code 4``: Resource deletion failed +* ``Code 5``: Connection error while deleting a resource (e.g. service not + available) +* ``Code 6``: Connection to endpoint failed (e.g. wrong authentication URL) -``ospurge`` can be used by a cloud administrator (with the admin role) -to cleanup any project or by a non-privileged user to cleanup his own -project. Installation -============ +------------ -Create a Python virtual environment (requires package virtualenvwrapper):: +Create a Python virtual environment (requires the +`virtualenvwrapper `_): + +.. code-block:: console $ mkvirtualenv ospurge -Install ``ospurge``:: +Install ``ospurge`` with ``pip``: + +.. code-block:: console $ pip install ospurge -The script is installed and can be launched:: +Available options can be displayed by using ``ospurge -h``: - $ ospurge -h - - -Usage -===== - -Available options can be displayed by using ``ospurge -h``:: +.. code-block:: console $ ospurge -h usage: ospurge [-h] [--verbose] [--dry-run] [--dont-delete-project] @@ -80,23 +114,8 @@ Available options can be displayed by using ``ospurge -h``:: with caution. -Error codes -=========== - -The following error codes are returned when ``ospurge`` encounters -an error: - -* Code 2: Project doesn't exist -* Code 3: Authentication failed (e.g. Bad username or password) -* Code 4: Resource deletion failed -* Code 5: Connection error while deleting a resource (e.g. Service not available) -* Code 6: Connection to endpoint failed (e.g. authentication url) -* Code 1: Unknown error -* Code 0: Process exited sucessfully - - -Example -======= +Example usage +------------- To remove a project, credentials have to be provided. The usual OpenStack environment variables can be used. When @@ -105,16 +124,20 @@ to be provided, by using either the ``--cleanup-project`` option or the ``--own-project`` option. When the command returns, any resources associated to the project will have been definitively deleted. -Setting OpenStack credentials:: +* Setting OpenStack credentials: + +.. code-block:: console $ export OS_USERNAME=admin $ export OS_PASSWORD=password $ export OS_TENANT_NAME=admin $ export OS_AUTH_URL=http://localhost:5000/v2.0 -Checking resources of the target project:: +* Checking resources of the target project: - $ ./ospurge --dry-run --cleanup-project florent-demo +.. code-block:: console + + $ ./ospurge --dry-run --cleanup-project demo * Resources type: CinderSnapshots * Resources type: NovaServers @@ -142,11 +165,13 @@ Checking resources of the target project:: * Resources type: CeilometerAlarms -Removing resources without deleting the project:: +* Removing resources without deleting the project: - $ ./ospurge --verbose --dont-delete-project --cleanup-project florent-demo +.. code-block:: console + + $ ./ospurge --verbose --dont-delete-project --cleanup-project demo INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone.usr.lab0.aub.cw-labs.net - INFO:root:* Granting role admin to user e7f562a29da3492baba2cc7c5a1f2d84 on project florent-demo. + INFO:root:* Granting role admin to user e7f562a29da3492baba2cc7c5a1f2d84 on project demo. INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net @@ -174,9 +199,11 @@ Removing resources without deleting the project:: INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): cinder.usr.lab0.aub.cw-labs.net INFO:root:* Purging CeilometerAlarms -Checking that resources have been correctly removed:: +* Checking that resources have been correctly removed: - $ ./ospurge --dry-run --cleanup-project florent-demo +.. code-block:: console + + $ ./ospurge --dry-run --cleanup-project demo * Resources type: CinderSnapshots * Resources type: NovaServers @@ -201,41 +228,26 @@ Checking that resources have been correctly removed:: * Resources type: CeilometerAlarms -Removing project:: +* Removing project: - $ ./ospurge --cleanup-project florent-demo - $ ./ospurge --cleanup-project florent-demo - Project florent-demo doesn't exist +.. code-block:: console + $ ./ospurge --cleanup-project demo + $ ./ospurge --cleanup-project demo + Project demo doesn't exist -Deleted resources -================= +* Users can be deleted by using the ``python-keystoneclient`` command-line + interface: -The following resources will be removed: - -* ceilometer alarms -* floating IPs -* images / snapshots -* instances -* networks -* routers -* security groups -* swift containers -* swift objects -* volumes / snapshots - - -Notes -===== - -Users can be deleted by using the ``python-keystoneclient`` CLI:: +.. code-block:: console $ keystone user-delete How to contribute -================= +----------------- -Ospurge is hosted on Stackforge and is using Gerrit to manage -contributions. You can contribute to the project by following the -following workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow +OSpurge is hosted on the OpenStack infrastructure and is using +`Gerrit `_ to manage contributions. You can +contribute to the project by following the +`OpenStack Development workflow `_. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..1fc4ddb --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,28 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys +import openstackdocstheme + +copyright = u'2015, OpenStack contributors' +html_copy_source = False +html_last_updated_fmt = '%Y-%m-%d %H:%M' +html_show_sourcelink = False +html_theme = 'openstackdocs' +html_theme_path = [openstackdocstheme.get_html_theme_path()] +html_use_index = False +master_doc = 'index' +project = u'OpenStack project resources cleaner' +pygments_style = 'sphinx' +source_suffix = '.rst' diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/test-requirements.txt b/test-requirements.txt index b527706..ead92bd 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -4,3 +4,6 @@ testtools nose requests testrepository +sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 +doc8 +openstackdocstheme>=1.0.3 diff --git a/tox.ini b/tox.ini index 7149868..90cbd08 100644 --- a/tox.ini +++ b/tox.ini @@ -15,15 +15,19 @@ deps = -r{toxinidir}/requirements.txt commands = python setup.py testr --testr-args='{posargs}' whitelist_externals = flake8 -[testenv:pep8] -commands = flake8 - [testenv:venv] commands = {posargs} +[testenv:pep8] +commands = flake8 + [flake8] # E501 line too long ignore = E501 show-source = True exclude = .venv,.tox,dist,doc,*egg,build +[testenv:docs] +commands = + doc8 -e .rst doc README.rst + python setup.py build_sphinx -b html