airship
/
shipyard
Code Issues Proposed changes

Merge "Add samples to CLI command documentation"

This commit is contained in:
Mark Burnett 2017-11-28 12:04:34 -05:00 committed by Gerrit Code Review
parent 01069aab17 958e3b5fea
commit 9d44c2e87a
2 changed files with 229 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
docs/CLI.md
View File

@ -89,10 +89,19 @@ Example:
<dl> <dl>
<dt>--force</dt> <dt>--force</dt>
<dd> <dd>
Force the commit to occur, even if validations fail. Force the commit to occur, even if validations fail. Note that while this
allows for bypassing validations, it does not bypass a failure to
communicate with the systems that provide the validations.
</dd> </dd>
</dl> </dl>
### Sample
```
TBD
```
---
# Control commands # Control commands
## pause, unpause, stop ## pause, unpause, stop
Three separate commands with a common format that allow for controlling Three separate commands with a common format that allow for controlling
@ -146,9 +155,24 @@ Example:
<dd> <dd>
The qualified name of the item to take the specified action upon The qualified name of the item to take the specified action upon
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard pause action/01BZZMEXAVYGG7BT0BMA3RHYY7
pause successfully submitted for action 01BZZMEXAVYGG7BT0BMA3RHYY7
```
A failed command:
```
$ shipyard pause action/01BZZK07NF04XPC5F4SCTHNPKN
Error: Unable to pause action
Reason: dag_run state must be running, but is failed
- Error: dag_run state must be running, but is failed
```
---
# Create Commands # Create Commands
## create action ## create action
Invokes the specified workflow through Shipyard. Invokes the specified workflow through Shipyard.
@ -173,6 +197,15 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard create action deploy_site
Name Action Lifecycle
deploy_site action/01BZZK07NF04XPC5F4SCTHNPKN None
```
---
## create configdocs ## create configdocs
Load documents into the Shipyard Buffer. The use of one or more filename or Load documents into the Shipyard Buffer. The use of one or more filename or
a single directory option must be specified. a single directory option must be specified.
@ -223,6 +256,30 @@ specified for the same invocation of shipyard.
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard create configdocs coll1 --filename=/home/ubuntu/yaml/coll1.yaml
Configuration documents added.
Status: Validations succeeded
Reason: Validation
```
Attempting to load the same collection into the uncommitted buffer.
```
$ shipyard create configdocs coll1 --filename=/home/ubuntu/yaml/coll1.yaml
Error: Invalid collection specified for buffer
Reason: Buffermode : rejectoncontents
- Error: Buffer is either not empty or the collection already exists in buffer. Setting a different buffermode may provide the desired functionality
```
Replace the buffer with --replace
```
$ shipyard create configdocs coll1 --replace --filename=/home/ubuntu/yaml/coll1.yaml
Configuration documents added.
Status: Validations succeeded
Reason: Validation
```
---
# Describe Commands # Describe Commands
## describe ## describe
Retrieves the detailed information about the supplied namespaced item Retrieves the detailed information about the supplied namespaced item
@ -249,6 +306,8 @@ Example:
shipyard describe workflow deploy_site__2017-01-01T12:34:56.123456 shipyard describe workflow deploy_site__2017-01-01T12:34:56.123456
``` ```
---
## describe action ## describe action
Retrieves the detailed information about the supplied action id. Retrieves the detailed information about the supplied action id.
``` ```
@ -259,6 +318,35 @@ Example:
shipyard describe action 01BTG32JW87G0YKA1K29TKNAFX shipyard describe action 01BTG32JW87G0YKA1K29TKNAFX
``` ```
### Sample
```
$ shipyard describe action/01BZZK07NF04XPC5F4SCTHNPKN
Name: deploy_site
Action: action/01BZZK07NF04XPC5F4SCTHNPKN
Lifecycle: Failed
Parameters: {}
Datetime: 2017-11-27 20:34:24.610604+00:00
Dag Status: failed
Context Marker: 71d4112e-8b6d-44e8-9617-d9587231ffba
User: shipyard
Steps Index State
step/01BZZK07NF04XPC5F4SCTHNPKN/action_xcom 1 success
step/01BZZK07NF04XPC5F4SCTHNPKN/dag_concurrency_check 2 success
step/01BZZK07NF04XPC5F4SCTHNPKN/deckhand_get_design_version 3 failed
step/01BZZK07NF04XPC5F4SCTHNPKN/validate_site_design 4 None
step/01BZZK07NF04XPC5F4SCTHNPKN/deckhand_get_design_version 5 failed
step/01BZZK07NF04XPC5F4SCTHNPKN/deckhand_get_design_version 6 failed
step/01BZZK07NF04XPC5F4SCTHNPKN/drydock_build 7 None
Commands User Datetime
invoke shipyard 2017-11-27 20:34:34.443053+00:00
Validations: None
```
---
## describe step ## describe step
Retrieves the step details associated with an action and step. Retrieves the step details associated with an action and step.
``` ```
@ -280,6 +368,22 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard describe step/01BZZK07NF04XPC5F4SCTHNPKN/action_xcom
Name: action_xcom
Task ID: step/01BZZK07NF04XPC5F4SCTHNPKN/action_xcom
Index: 1
State: success
Start Date: 2017-11-27 20:34:45.604109
End Date: 2017-11-27 20:34:45.818946
Duration: 0.214837
Try Number: 1
Operator: PythonOperator
```
---
## describe validation ## describe validation
Retrieves the validation details associated with an action and validation id Retrieves the validation details associated with an action and validation id
``` ```
@ -302,6 +406,13 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
TBD
```
---
## describe workflow ## describe workflow
Retrieves the details for a workflow that is running or has run in the workflow Retrieves the details for a workflow that is running or has run in the workflow
engine. engine.
@ -319,6 +430,46 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard describe workflow deploy_site__2017-11-27T20:34:33.000000
Workflow: deploy_site__2017-11-27T20:34:33.000000
State: failed
Dag ID: deploy_site
Execution Date: 2017-11-27 20:34:33
Start Date: 2017-11-27 20:34:33.979594
End Date: None
External Trigger: True
Steps State
action_xcom success
dag_concurrency_check success
deckhand_get_design_version failed
validate_site_design None
deckhand_get_design_version failed
deckhand_get_design_version failed
drydock_build None
Subworkflows:
Workflow: deploy_site.deckhand_get_design_version__2017-11-27T20:34:33.000000
State: failed
Dag ID: deploy_site.deckhand_get_design_version
Execution Date: 2017-11-27 20:34:33
Start Date: 2017-11-27 20:35:06.281825
End Date: None
External Trigger: False
Workflow: deploy_site.deckhand_get_design_version.deckhand_get_design_version__2017-11-27T20:34:33.000000
State: failed
Dag ID: deploy_site.deckhand_get_design_version.deckhand_get_design_version
Execution Date: 2017-11-27 20:34:33
Start Date: 2017-11-27 20:35:20.725506
End Date: None
External Trigger: False
```
---
# Get Commands # Get Commands
## get actions ## get actions
Lists the actions that have been invoked. Lists the actions that have been invoked.
@ -326,6 +477,16 @@ Lists the actions that have been invoked.
shipyard get actions shipyard get actions
``` ```
### Sample
```
$ shipyard get actions
Name Action Lifecycle
deploy_site action/01BZZK07NF04XPC5F4SCTHNPKN Failed
update_site action/01BZZKMW60DV2CJZ858QZ93HRS Processing
```
---
## get configdocs ## get configdocs
Retrieve documents loaded into Shipyard, either committed or from the Retrieve documents loaded into Shipyard, either committed or from the
Shipyard Buffer. Shipyard Buffer.
@ -356,6 +517,24 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard get configdocs coll1
data:
chart_groups: [kubernetes-proxy, container-networking, dns, kubernetes, kubernetes-rbac]
release_prefix: ucp
id: 1
metadata:
layeringDefinition: {abstract: false, layer: site}
name: cluster-bootstrap-1
schema: metadata/Document/v1.0
storagePolicy: cleartext
schema: armada/Manifest/v1.0
status: {bucket: coll1, revision: 1}
```
---
## get renderedconfigdocs ## get renderedconfigdocs
Retrieve the rendered version of documents loaded into Shipyard. Rendered Retrieve the rendered version of documents loaded into Shipyard. Rendered
documents are the "final" version of the documents after applying Deckhand documents are the "final" version of the documents after applying Deckhand
@ -379,6 +558,24 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard get renderedconfigdocs
data:
chart_groups: [kubernetes-proxy, container-networking, dns, kubernetes, kubernetes-rbac]
release_prefix: ucp
id: 1
metadata:
layeringDefinition: {abstract: false, layer: site}
name: cluster-bootstrap-1
schema: metadata/Document/v1.0
storagePolicy: cleartext
schema: armada/Manifest/v1.0
status: {bucket: coll1, revision: 1}
```
---
## get workflows ## get workflows
Retrieve workflows that are running or have run in the workflow engine. This Retrieve workflows that are running or have run in the workflow engine. This
includes processses that may not have been started as an action includes processses that may not have been started as an action
@ -399,6 +596,16 @@ Example:
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard get workflows
Workflows State
deploy_site__2017-11-27T20:34:33.000000 failed
update_site__2017-11-27T20:45:47.000000 running
```
---
# help commands # help commands
Provides topical help for shipyard. Note that --help will provide more Provides topical help for shipyard. Note that --help will provide more
specific command help. specific command help.
@ -416,3 +623,22 @@ Example:
the list of avaialable topics will be displayed. the list of avaialable topics will be displayed.
</dd> </dd>
</dl> </dl>
### Sample
```
$ shipyard help
THE SHIPYARD COMMAND
The base shipyard command supports options that determine cross-CLI behaviors.
FORMAT
shipyard [--context-marker=<uuid>] [--os_{various}=<value>]
[--debug/--no-debug] [--output-format] <subcommands>
Please Note: --os_auth_url is required for every command except shipyard help
<topic>.
TOPICS
For information of the following topics, run shipyard help <topic>
actions
configdocs
```

2
shipyard_client/cli/describe/actions.py
View File

@ -49,7 +49,7 @@ class DescribeAction(CliAction):
cli_format_common.gen_action_details(resp_j), cli_format_common.gen_action_details(resp_j),
cli_format_common.gen_action_steps(resp_j.get('steps'), cli_format_common.gen_action_steps(resp_j.get('steps'),
resp_j.get('id')), resp_j.get('id')),
cli_format_common.gen_action_commands(resp_j.get('commands')), cli_format_common.gen_action_commands(resp_j.get('command_audit')),
cli_format_common.gen_action_validations( cli_format_common.gen_action_validations(
resp_j.get('validations') resp_j.get('validations')
) )