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 to localhost:8800. Configuration entry yorc_api and env var YORC_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.

List deployments

List active deployments. Giving there ids and statuses.

yorc deployments list

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" }}'

Delete a location

Delete a given location.

yorc locations delete <locationName>

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 form key=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 the name 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 provided
    • private_key: Path to a private key file (or private key file content), either a password or a private key should be provided
    • port: 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 or json (default yaml)
• --file or -f: Path to a file where to store the output (default standard output)