From 32caf4f550f90f929fc976ac5c5069e75eac1bb2 Mon Sep 17 00:00:00 2001 From: Bryan Strassner Date: Wed, 8 Nov 2017 17:35:28 -0600 Subject: [PATCH] Update docs and CLI options to match Updates the documentation of the CLI to match the options supported Also adds some type checking to the CLI for input UUID, and sets some default values for OS auth variables that can be reasonably defaulted Sets up the options on input to the output format to use 'cli' as the default instead of 'format', providing for a path to make more cli friendly outputs for actions (instead of raw json/yaml as appropriate). Fixes some markdown in html problems. Change-Id: Ie0eaa34ad1106b5a963b69ffc7eb727c13ede244 --- docs/CLI.md | 48 +++++++++++++------ shipyard_client/cli/commands.py | 22 +++++---- shipyard_client/cli/help/output.py | 12 +---- .../tests/unit/cli/test_shipyard_commands.py | 8 +++- 4 files changed, 54 insertions(+), 36 deletions(-) diff --git a/docs/CLI.md b/docs/CLI.md index ab9e44a4..082a17e9 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -4,18 +4,23 @@ All commands will utilize the following environment variables to determine necessary information for execution, unless otherwise noted.
-
Openstack Keystone Authorization Environment variables
+
Openstack Keystone Authorization environment variables
The Shipyard CLI/API Client will check for the presence of appropriate environment setup to do authentication on behalf of the user. The openrc variables that will be used are as follows:
- OS_PROJECT_DOMAIN_NAME
- OS_USER_DOMAIN_NAME
+ OS_PROJECT_DOMAIN_NAME ("default" if not specified)
+ OS_USER_DOMAIN_NAME ("default" if not specified)
OS_PROJECT_NAME
OS_USERNAME
OS_PASSWORD
- OS_AUTH_URL
- OS_IDENTITY_API_VERSION
+ OS_AUTH_URL - The fully qualified identity endpoint. + E.g. http://keystone.ucp.fully.qualified.name:80/v3
+
+
Openstack Keystone Authorization environment variables not used
+
+ OS_IDENTITY_API_VERSION -- this value will be ignored as Shipyard only + supports version 3 at this time
@@ -28,8 +33,9 @@ shipyard <--these options> subcommands... shipyard [--context-marker=] - [--os_{various}=] [--debug/--no-debug] + [--os_{various}=] + [--output-format=[format | raw | cli]] (default = cli) ```
@@ -40,22 +46,35 @@ shipyard interaction. If not specified, Shipyard will supply a new UUID to serve as this marker. (optional) +
--debug | --no-debug (default)
+
+ Enable/disable debugging of this CLI and API client. +
--os_{various}=<value>
See supported Openstack Keystone Authorization Environment variables above for the list of supported names, converting to a downcase version of the environment variable.
- E.g.: --os_auth_url=http://...:80/v3 - While these options are optional, if not specified, the environment - variables will be used instead. The Keystone os_auth_url should reference - the exposed keystone:port for the target Shipyard environment, as this - Keystone will be used to discover the instance of Shipyard. + E.g.: --os_auth_url=http://keystone.ucp:80/v3
+ If not specified, the environment variables matching these actions will be + used instead. The Keystone os_auth_url should reference the exposed + keystone:port for the target Shipyard environment, as this Keystone will + be used to discover the instance of Shipyard. For most invocations other + than help, a valid combination of values must be resolved to authenticate + and authorize the user's invocation. +
+
--output-format=[format | raw | cli] (default = cli)
+
+ Specifies the desired output formating such that:
+ format: Display the raw ouptut from the invoked Shipyard API in a + column restricted mode.
+ raw: Display the result from the invoked Shipyard API as-is, without + modification.
+ cli: (default) Display results in a plain text interpretation of the + response from the invoked Shipyard API.
-## Context Marker - - # Commit Commands ## commit configdocs Attempts to commit the Shipyard Buffer documents, first invoking validation @@ -147,7 +166,6 @@ Example:
<action command>
The action to invoke. - See [Action Commands](API_action_commands.md) for supported actions
--param=<parameter>
diff --git a/shipyard_client/cli/commands.py b/shipyard_client/cli/commands.py index 5ee064a6..da23df5d 100644 --- a/shipyard_client/cli/commands.py +++ b/shipyard_client/cli/commands.py @@ -35,20 +35,24 @@ from shipyard_client.cli.input_checks import check_control_action, check_id ' logs, transactions, etc. in downstream activities triggered by this' ' interaction. If not specified, Shipyard will supply a new UUID to serve' ' as this marker. (optional)', - required=False) + required=False, + type=click.UUID) @click.option('--debug/--no-debug', default=False, help='Turn Debug on.') @click.option( '--output-format', 'output_format', required=False, - type=click.Choice(['format', 'raw'])) + type=click.Choice(['format', 'raw', 'cli']), + default='cli') # Supported Environment Variables -@click.option( - '--os_project_domain_name', - envvar='OS_PROJECT_DOMAIN_NAME', - required=False) -@click.option( - '--os_user_domain_name', envvar='OS_USER_DOMAIN_NAME', required=False) +@click.option('--os_project_domain_name', + envvar='OS_PROJECT_DOMAIN_NAME', + required=False, + default='default') +@click.option('--os_user_domain_name', + envvar='OS_USER_DOMAIN_NAME', + required=False, + default='default') @click.option('--os_project_name', envvar='OS_PROJECT_NAME', required=False) @click.option('--os_username', envvar='OS_USERNAME', required=False) @click.option('--os_password', envvar='OS_PASSWORD', required=False) @@ -94,7 +98,7 @@ def shipyard(ctx, context_marker, debug, os_project_domain_name, ctx.obj['API_PARAMETERS'] = { 'auth_vars': auth_vars, - 'context_marker': context_marker, + 'context_marker': str(context_marker) if context_marker else None, 'debug': debug } diff --git a/shipyard_client/cli/help/output.py b/shipyard_client/cli/help/output.py index 8c43e6a9..5c05fa04 100644 --- a/shipyard_client/cli/help/output.py +++ b/shipyard_client/cli/help/output.py @@ -32,24 +32,16 @@ For information of the following topics, run shipyard help def actions(): return '''ACTIONS - - -Supported Actions -No supported actions at this time. - - -Actions Under Development +The workflow actions that may be invoked using Shipyard deploy_site: Triggers the initial deployment of a site using the latest committed configuration documents. update_site: Triggers the initial deployment of a site, using the latest committed configuration documents. - Steps: - (same as deploy_site) redeploy_server: Using parameters to indicate which server(s), triggers a - redeployment of server to the last known good design and + redeployment of servers to the last committed design and secrets. ''' diff --git a/shipyard_client/tests/unit/cli/test_shipyard_commands.py b/shipyard_client/tests/unit/cli/test_shipyard_commands.py index f393516d..aa115407 100644 --- a/shipyard_client/tests/unit/cli/test_shipyard_commands.py +++ b/shipyard_client/tests/unit/cli/test_shipyard_commands.py @@ -21,7 +21,7 @@ from shipyard_client.api_client.shipyardclient_context import \ def test_shipyard(): - context_marker = '--context-marker=UUID' + context_marker = '--context-marker=88888888-4444-4444-4444-121212121212' debug = '--debug' os_project_domain_name = ( '--os_project_domain_name=OS_PROJECT_DOMAIN_NAME_test') @@ -47,4 +47,8 @@ def test_shipyard(): os_project_name, os_username, os_password, os_auth_url, debug, 'commit', 'configdocs' ]) - mock_method.assert_called_once_with(auth_vars, 'UUID', True) + mock_method.assert_called_once_with( + auth_vars, + '88888888-4444-4444-4444-121212121212', + True + )