diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 00000000..cfd144de --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,350 @@ +# Supported Environment Variables + +All commands will utilize the following environment variables to determine +necessary information for execution, unless otherwise noted. + +
+
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_NAME
+ OS_USERNAME
+ OS_PASSWORD
+ OS_AUTH_URL
+ OS_IDENTITY_API_VERSION
+
+
+ +# Shipyard command options +The base shipyard command supports options that determine cross-CLI behaviors. +These options are positionally immediately following the shipyard command as +shown here: +``` +shipyard <--these options> subcommands... + +shipyard + [--context-marker=] + [--os_{various}=] + [--debug/--no-debug] + +``` +
+
--context-marker=<uuid>
+
+ Specifies a UUID (8-4-4-4-12 format) that will be used to correlate 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) +
+
--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. +
+
+ +## Context Marker + + +# Commit Commands +## commit configdocs +Attempts to commit the Shipyard Buffer documents, first invoking validation +by downstream components. +``` +shipyard commit configdocs + [--force] + +Example: + shipyard commit configdocs +``` +
+
--force
+
+ Force the commit to occur, even if validations fail. +
+
+ +# Control commands +## pause, unpause, stop +Three separate commands with a common format that allow for controlling +the processing of actions created in Shipyard. +
+
pause
+
pause something in progress e.g. an executing action
+
unpause
+
unpause something paused e.g. a paused action
+
stop
+
stops an executing or paused item e.g. an action
+
+ +``` +shipyard pause + + + +shipyard unpause + + + +shipyard stop + + + +shipyard + pause|unpause|stop + + +Example: + + shipyard pause action 01BTG32JW87G0YKA1K29TKNAFX + + shipyard unpause action 01BTG32JW87G0YKA1K29TKNAFX + + shipyard stop action 01BTG32JW87G0YKA1K29TKNAFX + + shipyard pause action/01BTG32JW87G0YKA1K29TKNAFX +``` +
+
<type>
+
+ The type of entity to take action upon. Currently supports: action +
+
<id>
+
+ The id of the entity to take action upon. +
+
<qualified name>
+
+ The qualified name of the item to take the specified action upon +
+ +
+ +# Create Commands +## create action +Invokes the specified workflow through Shipyard. +See [Action Commands](API_action_commands.md) for supported actions +Returns the id of the action invoked so that it can be queried subsequently. +``` +shipyard create action + + --param= (repeatable) + +Example: + shipyard create action redeploy_server --param="server-name=mcp" +``` +
+
<action command>
+
+ The action to invoke. + See [Action Commands](API_action_commands.md) for supported actions +
+
--param=<parameter>
+
+ A parameter to be provided to the action being invoked. (repeatable) +
+
+ +## create configdocs +Load documents into the Shipyard Buffer. +``` +shipyard create configdocs + + [--append | --replace] + [--filename= (repeatable) + | + --directory=] + +Example: + shipyard create configdocs design --append --filename=site_design.yaml +``` +
+
<collection>
+
+ The collection to load. +
+
--append
+
+ Add the collection to the Shipyard Buffer. This will fail if the + collection already exists. +
+
--replace
+
+ Clear the shipyard buffer and replace it with the specified contents. +
+
--filename=<filename>
+
+ The file name to use as the contents of the collection. (repeatable) + If any documents specified fail basic validation, all of the documents + will be rejected. +
+
--directory=<directory>
+
+ A directory containing documents that will be joined and loaded as a + collection. Any documents that fail basic validation will reject the + whole set. +
+
+ +# Describe Commands +## describe +Retrieves the detailed information about the supplied namespaced item +``` +shipyard describe + + +Example: + shipyard describe action/01BTG32JW87G0YKA1K29TKNAFX + Equivalent to: + shipyard describe action/01BTG32JW87G0YKA1K29TKNAFX + + shipyard describe step/01BTG32JW87G0YKA1K29TKNAFX/preflight + Equivalent to: + shipyard describe step preflight --action=01BTG32JW87G0YKA1K29TKNAFX + + shipyard describe validation/01BTG32JW87G0YKA1K29TKNAFX/01BTG3PKBS15KCKFZ56XXXBGF2 + Equivalent to: + shipyard describe validation 01BTG3PKBS15KCKFZ56XXXBGF2 \ + --action=01BTG32JW87G0YKA1K29TKNAFX +``` + +## describe action +Retrieves the detailed information about the supplied action id. +``` +shipyard describe action + + +Example: + shipyard describe action 01BTG32JW87G0YKA1K29TKNAFX +``` + +## describe step +Retrieves the step details associated with an action and step. +``` +shipyard describe step + + --action= + +Example: + shipyard describe step preflight --action=01BTG32JW87G0YKA1K29TKNAFX +``` +
+
<step id>
+
+ The id of the step found in the describe action response. +
+
--action=<action id>
+
+ The action id that provides the context for this step. +
+
+ +## describe validation +Retrieves the validation details assocaited with an action and validation id +``` +shipyard describe validation + + --action= + +Example: + shipyard describe validation 01BTG3PKBS15KCKFZ56XXXBGF2 \ + --action=01BTG32JW87G0YKA1K29TKNAFX +``` +
+
<step id>
+
+ The id of the validation found in the describe action response. +
+
--action=<action id>
+
+ The action id that provides the context for this validation. +
+
+ +# Get Commands +## get actions +Lists the actions that have been invoked. +``` +shipyard get actions +``` + +## get configdocs +Retrieve documents loaded into Shipyard, either committed or from the +Shipyard Buffer. +``` +shipyard get configdocs + + [--committed | --buffer] + +Example: + shipyard get configdocs design +``` +
+
<collection>
+
+ The collection to retrieve for viewing. +
+
--committed
+
+ Retrieve the documents that have last been committed for this + collection +
+
--buffer
+
+ Retrive the documents that have been loaded into Shipyard + since the prior commit. If no documents have been loaded + into the buffer for this collection, this will return an empty + response (default) +
+
+ +## get renderedconfigdocs +Retrieve the rendered version of documents loaded into Shipyard. Rendered +documents are the "final" version of the documents after applying Deckhand +layering and substitution. +``` +shipyard get renderedconfigdocs + [--committed | --buffer] + +Example: + shipyard get renderedconfigdocs +``` +
+
--committed
+
+ Retrieve the documents that have last been committed. +
+
--buffer
+
+ Retrieve the documents that have been loaded into Shipyard + since the prior commit. (default) +
+
+ +# help commands +Provides topical help for shipyard. Note that --help will provide more +specific command help. +``` +shipyard help + [] + +Example: + shipyard help configdocs +``` +
+
[<topic>]
+
+ The topic of the help to be displayed. If this parameter is not specified + the list of avaialable topics will be displayed. +
+