Yorc Command Line Interface¶
You can interact with a Yorc server using a command line interface (CLI). The same binary as for running a Yorc server is used for the CLI.
General Options¶
--yorc-api
: Specifies the host and port used to join the Yorc’ REST API. Defaults tolocalhost:8800
. Configuration entryyorc_api
and env varYORC_API
may also be used.--no-color
: Disable coloring output (By default coloring is enable).-s
or--secured
: Use HTTPS to connect to the Yorc REST API--ca-file
: This provides a file path to a PEM-encoded certificate authority. This implies the use of HTTPS to connect to the Yorc REST API.--skip-tls-verify
: skip-tls-verify controls whether a client verifies the server’s certificate chain and host name. If set to true, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing. This implies the use of HTTPS to connect to the Yorc REST API.
CLI Commands related to deployments¶
All deployments related commands are sub-commands of a command named deployments
.
In practice that means that the commands starts with
yorc deployments
For brevity deployments
supports the following aliases: depls
, depl
, deps
, dep
and d
.
Deploy a CSAR¶
Deploys a file or directory pointed by <csar_path> If <csar_path> point to a valid zip archive it is submitted to Yorc as it. If <csar_path> point to a file or directory it is zipped before beeing submitted to Yorc. If <csar_path> point to a single file it should be TOSCA YAML description.
yorc deployments deploy <csar_path> [flags]
Flags:
--id
, Specify a id for this deployment:
- Optional. If not provided, a unique ID is generated by Yorc.
- If this id already exists, a deployment update will be performed on a Yorc Premium version, an error wil be returned on the Open Source version.
- Should respect the following format:
^[-_0-9a-zA-Z]+$
and should be less than 36 characters long-e
,--stream-events
: Stream events after deploying the CSAR.-l
,--stream-logs
: Stream logs after deploying the CSAR. In this mode logs can’t be filtered, to use this feature see the “log” command.
Undeploy a deployment¶
Undeploy an application specifying the deployment ID.
yorc deployments undeploy <DeploymentId> [flags]
- Flags:
-p
,--purge
: To use if you want to purge instead of undeploy.-e
,--stream-events
: Stream events after deploying the CSAR.-l
,--stream-logs
: Stream logs after deploying the CSAR. In this mode logs can’t be filtered, to use this feature see the “log” command.--stop-on-error
: By default if an error occurs during the undeployment, the error is bypassed and the undeployment continues. This flag allows to stop if an error occurs.
Get information on a specific deployment¶
Display information about a given deployment. It prints the deployment status and the status of all the nodes contained in this deployment.
yorc deployments info <DeploymentId> [flags]
- Flags:
-d
,--detailed
: Add details to the info command making it less concise and readable.-f
,--follow
: Follow deployment info updates (without details) until the deployment is finished.
Get deployment events¶
Streams events for all or a given deployment id
yorc deployments events [<DeploymentId>] [flags]
- Flags:
-b
,--from-beginning
: Show events from the beginning of a deployment-n
,--no-stream
: Show events then exit. Do not stream events. It implies –from-beginning
Get deployment logs¶
Streams logs for all or a given deployment id. The log format is: [Timestamp][Level][DeploymentID][WorkflowID][ExecutionID][NodeID][InstanceID][InterfaceName][OperationName][TypeID]Content
yorc deployments logs [<DeploymentId>] [flags]
- Flags:
-b
,--from-beginning
: Show logs from the beginning of a deployment-n
,--no-stream
: Show logs then exit. Do not stream logs. It implies –from-beginning
Get deployment tasks¶
Display info about the tasks related to a given deployment. It prints the tasks ID, type and status.
yorc deployments tasks <DeploymentId> [flags]
Get deployment task info¶
Display information about a given task specifying the deployment id and the task id.
yorc deployments task info <DeploymentId> <TaskId> [flags]
- Flags:
-w
,--steps
: Show steps of the related workflow associated to the task
Cancel a deployment task¶
Cancel a task specifying the deployment id and the task id. The task should be in status “INITIAL” or “RUNNING” to be canceled.
yorc deployments tasks cancel <DeploymentId> <TaskId> [flags]
Resume a deployment task¶
Resume a task specifying the deployment id and the task id. The task should be in status “FAILED” to be resumed.
yorc deployments tasks resume <DeploymentId> <TaskId> [flags]
Fix a deployment task step¶
Fix a task step specifying the deployment id, the task id and the step name. The task step must be on error to be fixed.
yorc deployments tasks fix <DeploymentId> <TaskId> <StepName> [flags]
Scale a specific node¶
Scale a given node of a deployment <DeploymentId> by adding or removing the specified number of instances.
yorc deployments scale <DeploymentId> [flags]
- Flags:
-d
,--delta
: The non-zero number of instance to add (if > 0) or remove (if < 0).-n
,--node
: The name of the node that should be scaled.-e
,--stream-events
: Stream events after issuing the scaling request.-l
,--stream-logs
: Stream logs after issuing the scaling request. In this mode logs can’t be filtered, to use this feature see the “log” command.
Execute a custom command¶
Executes a custom command for a given node of a deployment <DeploymentId>.
yorc deployments custom <DeploymentId> [flags]
- Flags:
--custom
: Provide the custom command name (mandatory)--interface
: Provide the interface name (mandatory)-d
,--data
: Provide the JSON format of the custom command with node, interface, custom and inputs data-i
,--input
: Provide the input for the custom command-n
,--node
: Provide the node name (mandatory)
Example using --input
flags:
yorc deployments custom deployID --custom cmdName --interface interfaceName --node nodeName --input 'key1=["value1","value2"]' --input 'key2="value3"'
Example using --data
flag:
yorc deployments custom deployID --data '{"name":"cmdName","interface":"interfaceName",""node":"nodeName","inputs":{"key1":["value1","value2"],"key2":"value3"}}'
Example using --data
flag with instances selection:
yorc deployments custom deployID --data '{"name":"cmdName","interface":"interfaceName",""node":"nodeName","instances":["0"], "inputs":{"key1":["value1","value2"],"key2":"value3"}}'
List workflows of a given deployment¶
Lists workflows defined in a deployment <DeploymentId>.
yorc deployments workflows list <DeploymentId> [flags]
Show a workflow on a given deployment¶
Show a human readable textual representation of a given TOSCA workflow defined in deployment <DeploymentId>.
yorc deployments workflows show <DeploymentId> [flags]
- Flags:
-w
,--workflow-name
: The workflow name (mandatory)
- When used with flag
-w
or--workflow-name
, the command will show: - the worflow input parameters, if any
- the workflow steps
- the workflow output values, if any
Generate a graphical representation of a workflow on a given deployment¶
Generate a GraphViz Dot format representation of a given workflow. The output can be easily converted to an image by making use of the dot command provided by GraphViz:
yorc deployments workflows graph <DeploymentId> [flags]| dot -Tpng > graph.png
- Flags:
-w
,--workflow-name
: The workflows name (mandatory)--horizontal
: Draw graph with an horizontal layout. (layout is vertical by default)
Execute a workflow on a given deployment¶
Trigger a workflow on deployment <DeploymentId>.
yorc deployments workflows execute <DeploymentId> [flags]
- Flags:
-d
,--data
: Provide the JSON format of the node instances selection and inputs data--continue-on-error
: By default if an error occurs in a step of a workflow then other running steps are cancelled and the workflow is stopped. This flag allows to continue to the next steps even if an error occurs.-e
,--stream-events
: Stream events after riggering a workflow.-l
,--stream-logs
: Stream logs after triggering a workflow. In this mode logs can’t be filtered, to use this feature see the “log” command.-w
,--workflow-name
: The workflows name (mandatory)
The --data
flag allows to provide input parameters for the workflow, and if necessary, to select the target node instances.
Information about the inputs parameters can be obtained using the workflows show command.
The list of the available node instances can be obtained with the info command:
yorc deployments info -d deployID
Example how to trigger the execution of workflow <workflowName> on instance “1” selected for node “node1”, and workflow input parameters “key1” and “key2”.
yorc deployments workflows execute deployID -w workflowName --data '{"inputs":{"key1":["value1","value2"],"key2":"value3"}, "nodesinstances": [{ "name": "node1", "instances": [ "1" ] }]}'
Note that providing the target node instances is not mandatory. If not provided, Yorc will select all the instances available for the nodes concerned by the workflow execution.
yorc deployments workflows execute deployID -w workflowName --data '{"inputs": {"key1": ["value1","value2"], "key2": "value3"}}'
The exec command returns the ID of a task created by Yorc to execute the <workflowName> workflow.
You can then use the following command to get the status of this task, and workflow output values if any:
yorc deployments task info deployID taskId
CLI Commands related to locations¶
All locations related commands are sub-commands of a command named locations
.
In practice that means that the commands starts with
yorc locations
For brevity locations
supports the following aliases: locs
, loc
and l
.
List locations¶
This command allows to list all the locations with their complete definition: name, type and properties.
yorc locations list
Get information on a specific location¶
Display information about a given location (its type and properties).
yorc locations info <locationName>
Add a location¶
Add a location defininition in JSON format.
yorc locations add [flags]
- Flags:
--data
or-d
: Specify a JSON format for location definition to add.
Example of location definition “testname” using --data
flag:
yorc locations add --data '{"name": "testname", "type": "t", "properties" : { "p1" : "v1", "p2" : "v2" }}'
Update a location¶
Update a given location’s definition.
yorc locations update [flags]
- Flags:
--data
or-d
: Specify a JSON format for the location definition to update.
Example of “testname” location update using --data
flag:
yorc locations add --data '{"name": "testname", "type": "other", "properties" : { "p1" : "v111" }}'
Apply a locations configuration file¶
Applies location configurations provided in a YAML or JSON file. This command will compare and display the differences between the current configurations and the configurations specified in the file. A user confirmation can be asked before proceeding.
yorc locations apply <filename> [flags]
- Flags:
--auto-approve
: Skip interactive approval before applying the new locations configuration.
CLI Commands related to hosts pool¶
All hosts pool related commands are sub-commands of a command named hostspool
.
In practice that means that the commands starts with
yorc hostspool
For brevity hostspool
supports the following aliases: hostpool
, hostsp
, hpool
and hp
.
List hosts pools locations¶
List hosts pools locations managed by this Yorc cluster.
yorc hostspool locations
Add a host in a hosts pool location¶
Add host to a hosts pool location managed by this Yorc cluster. The <hostname> should not already exist. The connection object of the JSON request is mandatory while the labels list is optional. This labels list should be composed with elements with the “op” parameter set to “add” but it could be omitted.
yorc hostspool add <hostname> -l <locationName> [flags]
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)--data
or-d
: Specify a JSON format for the host pool to add. The JSON format for the host pool is described below.--key
or-k
: Specify a private key to access host if no host connection is defined in JSON format. (mandatory if no password is defined)--password
or-p
: Specify a password to access host if no host connection is defined in JSON format. (mandatory if no private key is defined)--host
: Hostname or ip address used to connect to the host. (defaults to the hostname in the hosts pool)--label
: Label in formkey=value
to add to the host. May be specified several time.--port
: Port used to connect to the host. (default 22)--user
: User used to connect to the host (default “root”)
Host pool (JSON):
{
"connection": {
"host": "defaults_to_<hostname>",
"user": "defaults_to_root",
"port": "defaults_to_22",
"private_key": "one_of_password_or_private_key_required",
"password": "one_of_password_or_private_key_required"
},
"labels": [
{"name": "os.type", "value": "linux"},
{"op": "add", "name": "host.mem_size", "value": "4G"}
]
}
Update a host in a hosts pool location¶
Update labels list or connection of a host of a hosts pool location managed by this Yorc cluster. The <hostname> should exists. Both connection and labels list object of the JSON request are optional. This labels list should be composed with elements with the “op” parameter set to “add” or “remove” but defaults to “add” if omitted. Adding a tag that already exists replace its value.
yorc hostspool update <hostname> -l <locationName> [flags]
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)--data
or-d
: Specify a JSON format for the host pool to update. The JSON format for the host pool is described below.--add-label
: Add a label in form ‘key=value’ to the host. May be specified several time.--host
: Hostname or ip address used to connect to the host. (defaults to the hostname in the hosts pool)--key
or-k
: At any time a host of the pool should have at least one of private key or password. To delete a registered private key use the “-” character.--password
or-p
: At any time a host of the pool should have at least one of private key or password. To delete a registered password use the “-” character.--port
: Port used to connect to the host. (defaults to the hostname in the hosts pool) (default 22)--remove-label
: Remove a label from the host. May be specified several time.--user
: User used to connect to the host (default “root”)
Host pool (JSON):
{
"connection": {
"host": "defaults_to_<hostname>",
"user": "defaults_to_root",
"port": "defaults_to_22",
"private_key": "one_of_password_or_private_key_required",
"password": "one_of_password_or_private_key_required"
},
"labels": [
{"name": "os.type", "value": "linux"},
{"op": "add", "name": "host.mem_size", "value": "4G"},
{"op": "remove", "name": "host.disk_size"}
]
}
Delete a host in a hosts pool location¶
Deletes a host from a hosts pool location managed by this Yorc cluster. The <hostname> should exists.
yorc hostspool delete <hostname> [<hostname>...] -l <locationName>
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)
List hosts in a hosts pool location¶
Lists hosts of a hosts pool location managed by this Yorc cluster.
yorc hostspool list -l <locationName> [flags]
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)--filter
or-f
: Filter hosts based on their labels. May be specified several time, filters are joined by a logical ‘and’. Please refer to Filter on label existence for more details. Note: If the filter expression contains a comma as in “mylabel in (v1,v2)”, wrap it with single quotes as in the example below:
yorc hp list -f '"mylabel in (v1, v2)"' -l <locationName>
Get information on a specific host in a hosts pool location¶
Gets the description of a host of a hosts pool location managed by this Yorc cluster.
yorc hostspool info <hostname> -l <locationName>
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)
Apply a Hosts Pool location configuration¶
Applies a Hosts Pool configuration for a specified location provided in a YAML or JSON file. This command will compare and display the differences between the current Hosts Pool configuration and the configuration specified in the file. A user confirmation will be asked before proceeding. The command will fail if the new configuration would result in the removal of a host currently allocated for a deployment.
yorc hostspool apply <filename> -l <locationName>
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)--auto-approve
: Skip interactive approval before applying the new Hosts Pool configuration.
YAML and JSON formats are accepted. The following properties are supported :
hosts
: List of hosts configuration. A host configuration supports the following properties,
name
: mandatory string identifying the host, no other host entry can have the same name value in the file
connection
: Connection configuration,
host
: Hostname or ip address used to connect to the host (defaults to thename
described above)user
: name of the user used to connect to the host (default “root”)password
: either a password or a private key should be providedprivate_key
: Path to a private key file (or private key file content), either a password or a private key should be providedport
: Port used to connect to the host (default 22)labels
: key/value pairs (see Filter on label existence for more details on labels)
Example of a YAML Hosts Pool configuration file :
hosts:
- name: host1
connection:
host: host1.example.com
user: test
private_key: /path/to/secrets/id_rsa
port: 22
labels:
environment: dev
testlabel: hello
host.cpu_frequency: 3 GHz
host.disk_size: 50 GB
host.mem_size: 4GB
host.num_cpus: "4"
os.architecture: x86_64
os.distribution: ubuntu
os.type: linux
os.version: "17.1"
- name: host2
connection:
host: host2.example.com
user: test
password: test
Export a Hosts Pool location configuration¶
Exports a Hosts Pool configuration for a specified location as a YAML or JSON representation, to the standard output or a file.
yorc hostspool export -l <locationName>
- Flags:
--location
or-l
: Need to provide the specified hosts pool location name. (mandatory)--output
or-o
: Output format,yaml
orjson
(defaultyaml
)--file
or-f
: Path to a file where to store the output (default standard output)