From 89cfc55870963c23b76913727305efe5d92fc094 Mon Sep 17 00:00:00 2001 From: "David.T" Date: Tue, 24 May 2016 15:19:31 +0200 Subject: [PATCH] Update Watcher CLI documentation I updated, in this patchset, some examples of wacher CLI, because option format has changed (we have no more '-' character in keywords) I added a new page for the openstack client + our watcher plugin. Change-Id: Ia2ae148e4357eb64c8e3df1f3036dc992e85714c --- .gitignore | 1 + README.rst | 48 ++++++++++++++++----- doc/source/api/autoindex.rst | 13 +++--- doc/source/cli.rst | 30 ++++++------- doc/source/index.rst | 1 + doc/source/installation.rst | 2 +- doc/source/openstack_cli.rst | 81 ++++++++++++++++++++++++++++++++++++ 7 files changed, 144 insertions(+), 32 deletions(-) create mode 100644 doc/source/openstack_cli.rst diff --git a/.gitignore b/.gitignore index 727198e..4bb30b7 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ output/*/index.html # Sphinx doc/build +doc/source/api # pbr generates these AUTHORS diff --git a/README.rst b/README.rst index 8bb2044..0666675 100644 --- a/README.rst +++ b/README.rst @@ -49,9 +49,17 @@ You can install the Watcher CLI with the following command: .. code:: - pip install python-watcherclient + sudo pip install python-watcherclient +You can also use the `OpenStack client `_ +with Watcher (our watcher plugin for OpenStack client is included in the +python-watcherclient package). To install it, you have just to run this command: + +.. code:: + + sudo pip install python-openstackclient + Configuration ============= @@ -73,31 +81,48 @@ Source these credentials into your current shell session: # source creds -You should be able to launch the following command which gets the list of previously created Audit Templates: +You should be able to launch the following command which gets the list of +previously created Audit Templates: .. code:: - # watcher audit-template-list - +------+------+ - | UUID | Name | - +------+------+ - +------+------+ + # watcher audittemplate list -You can view the entire list of available Watcher commands and options using this command: +or:: + + # openstack optimize audittemplate list + +--------------------------------+------+----------------------+----------+ + | UUID | Name | Goal | Strategy | + +--------------------------------+------+----------------------+----------+ + +--------------------------------+------+----------------------+----------+ + + +You can view the entire list of available Watcher commands and options using +this command: .. code:: # watcher help +or:: + + # openstack help optimize + Troubleshootings ================ -If any watcher command fails, you can obtain more details with the **--debug** option : +If any watcher command fails, you can obtain more details with the **--debug** +option : .. code:: - # watcher --debug audit-template-list + # watcher --debug audittemplate list + +or:: + + # openstack --debug optimize audittemplate list + Install the openstack CLI : @@ -105,7 +130,8 @@ Install the openstack CLI : # pip install python-openstackclient -Make sure that your OpenStack credentials are correct. If so, you should be able to verify that the watcher user has been declared in your OpenStack keystone : +Make sure that your Openstack credentials are correct. If so, you should be able +to verify that the watcher user has been declared in your Openstack keystone : .. code:: diff --git a/doc/source/api/autoindex.rst b/doc/source/api/autoindex.rst index ecc5e8d..7421277 100644 --- a/doc/source/api/autoindex.rst +++ b/doc/source/api/autoindex.rst @@ -1,23 +1,25 @@ .. toctree:: :maxdepth: 1 + watcherclient._i18n.rst watcherclient.client.rst watcherclient.common.apiclient.base.rst watcherclient.common.apiclient.exceptions.rst watcherclient.common.base.rst watcherclient.common.cliutils.rst + watcherclient.common.command.rst watcherclient.common.http.rst - watcherclient.common.i18n.rst watcherclient.common.utils.rst watcherclient.exceptions.rst + watcherclient.plugin.rst watcherclient.shell.rst watcherclient.tests.keystone_client_fixtures.rst watcherclient.tests.test_client.rst watcherclient.tests.test_http.rst watcherclient.tests.test_import.rst - watcherclient.tests.test_shell.rst watcherclient.tests.test_utils.rst watcherclient.tests.utils.rst + watcherclient.tests.v1.base.rst watcherclient.tests.v1.test_action.rst watcherclient.tests.v1.test_action_plan.rst watcherclient.tests.v1.test_action_plan_shell.rst @@ -29,7 +31,8 @@ watcherclient.tests.v1.test_goal.rst watcherclient.tests.v1.test_goal_shell.rst watcherclient.tests.v1.test_metric_collector.rst - watcherclient.tests.v1.test_metric_collector_shell.rst + watcherclient.tests.v1.test_strategy.rst + watcherclient.tests.v1.test_strategy_shell.rst watcherclient.v1.action.rst watcherclient.v1.action_plan.rst watcherclient.v1.action_plan_shell.rst @@ -42,7 +45,7 @@ watcherclient.v1.goal.rst watcherclient.v1.goal_shell.rst watcherclient.v1.metric_collector.rst - watcherclient.v1.metric_collector_shell.rst watcherclient.v1.resource_fields.rst - watcherclient.v1.shell.rst + watcherclient.v1.strategy.rst + watcherclient.v1.strategy_shell.rst watcherclient.version.rst diff --git a/doc/source/cli.rst b/doc/source/cli.rst index 9ab1738..a7cc4a9 100644 --- a/doc/source/cli.rst +++ b/doc/source/cli.rst @@ -19,7 +19,7 @@ DESCRIPTION =========== The :program:`watcher` command-line interface (CLI) interacts with the -OpenStack TODEFINE Service (Watcher). +OpenStack infra-optim Service (Watcher). In order to use the CLI, you must provide your OpenStack username, password, project (historically called tenant), and auth endpoint. You can use @@ -28,26 +28,26 @@ configuration options :option:`--os-username`, :option:`--os-password`, and :option:`--os-auth-url`, or set the corresponding environment variables:: - export OS_USERNAME=user - export OS_PASSWORD=password - export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b # or OS_TENANT_NAME - export OS_TENANT_NAME=project # or OS_TENANT_ID - export OS_AUTH_URL=http://auth.example.com:5000/v2.0 + $ export OS_USERNAME=user + $ export OS_PASSWORD=password + $ export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b # or OS_TENANT_NAME + $ export OS_TENANT_NAME=project # or OS_TENANT_ID + $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0 The command-line tool will attempt to reauthenticate using the provided credentials for every request. You can override this behavior by manually supplying an auth token using :option:`--watcher-url` and :option:`--os-auth-token`, or by setting the corresponding environment variables:: - export WATCHER_URL=http://watcher.example.org:9322/ - export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 + $ export WATCHER_URL=http://watcher.example.org:9322/ + $ export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 Since Keystone can return multiple regions in the Service Catalog, you can specify the one you want with :option:`--os-region-name` or set the following environment variable. (It defaults to the first in the list returned.) :: - export OS_REGION_NAME=region + $ export OS_REGION_NAME=region Watcher CLI supports bash completion. The command-line tool can automatically fill partially typed commands. To use this feature, source the below file @@ -55,7 +55,7 @@ fill partially typed commands. To use this feature, source the below file https://git.openstack.org/cgit/openstack/python-watcherclient/tree/tools/watcher.bash_completion) to your terminal and then bash completion should work:: - source watcher.bash_completion + $ source watcher.bash_completion To avoid doing this every time, add this to your ``.bashrc`` or copy the watcher.bash_completion file to the default bash completion scripts directory @@ -66,11 +66,11 @@ OPTIONS To get a list of available (sub)commands and options, run:: - watcher help + $ watcher help To get usage and options of a command, run:: - watcher help + $ watcher help EXAMPLES @@ -78,12 +78,12 @@ EXAMPLES Get information about the audit-create command:: - watcher help audit-create + $ watcher help audit create Get a list of available goal:: - watcher goal-list + $ watcher goal list Get a list of audits:: - watcher audit-list + $ watcher audit list diff --git a/doc/source/index.rst b/doc/source/index.rst index ef3d586..4dcd041 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,7 @@ Contents: installation api_v1 cli + openstack_cli contributing Contributing diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 0fde6b4..a8f125f 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -2,7 +2,7 @@ Installation ============ -Or, if you have `virtualenvwrapper `_ installed:: +If you have `virtualenvwrapper `_ installed:: $ mkvirtualenv python-watcherclient $ git clone https://git.openstack.org/openstack/python-watcherclient diff --git a/doc/source/openstack_cli.rst b/doc/source/openstack_cli.rst new file mode 100644 index 0000000..6085123 --- /dev/null +++ b/doc/source/openstack_cli.rst @@ -0,0 +1,81 @@ +===================================================================== +:program:`openstack` Command-Line Interface (CLI) with Watcher plugin +===================================================================== + +.. program:: openstack +.. highlight:: bash + +SYNOPSIS +======== + +:program:`openstack` [options] :program:`optimize` [command-options] + +:program:`openstack help optimize` + +:program:`openstack help optimize` + + +DESCRIPTION +=========== + +The :program:`openstack` command-line interface (CLI) can interact with the +OpenStack infra-optim Service (Watcher), by using our additional plugin +(included into the python-watcherclient package). + +In order to use the CLI, you must provide your OpenStack username, password, +project (historically called tenant), and auth endpoint. You can use +configuration options :option:`--os-username`, :option:`--os-password`, +:option:`--os-tenant-id` (or :option:`--os-tenant-name`), +and :option:`--os-auth-url`, or set the corresponding +environment variables:: + + $ export OS_USERNAME=user + $ export OS_PASSWORD=password + $ export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b # or OS_TENANT_NAME + $ export OS_TENANT_NAME=project # or OS_TENANT_ID + $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0 + +The command-line tool will attempt to reauthenticate using the provided +credentials for every request. You can override this behavior by manually +supplying an auth token using :option:`--watcher-url` and +:option:`--os-auth-token`, or by setting the corresponding environment variables:: + + export WATCHER_URL=http://watcher.example.org:9322/ + export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 + +Since Keystone can return multiple regions in the Service Catalog, you can +specify the one you want with :option:`--os-region-name` or set the following +environment variable. (It defaults to the first in the list returned.) +:: + + $ export OS_REGION_NAME=region + +OPTIONS +======= + +To get a list of available (sub)commands and options, run:: + + $ openstack help optimize + +To get usage and options of a command, run:: + + $ openstack help optimize + + +EXAMPLES +======== + +Get information about the audit-create command:: + + $ openstack help optimize audit create + + +Get a list of available goal:: + + $ openstack optimize goal list + + +Get a list of audits:: + + $ openstack optimize audit list +