.. Copyright 2018 Bull S.A.S. Atos Technologies - Bull, Rue Jean Jaures, B.P.68, 78340, Les Clayes-sous-Bois, France. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- 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 .. code-block:: bash 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 If point to a valid zip archive it is submitted to Yorc as it. If point to a file or directory it is zipped before beeing submitted to Yorc. If point to a single file it should be TOSCA YAML description. .. code-block:: bash yorc deployments deploy [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. .. code-block:: bash yorc deployments undeploy [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. .. code-block:: bash 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. .. code-block:: bash yorc deployments info [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 .. code-block:: bash yorc deployments events [] [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 .. code-block:: bash yorc deployments logs [] [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. .. code-block:: bash yorc deployments tasks [flags] Get deployment task info ~~~~~~~~~~~~~~~~~~~~~~~~ Display information about a given task specifying the deployment id and the task id. .. code-block:: bash yorc deployments task info [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. .. code-block:: bash yorc deployments tasks cancel [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. .. code-block:: bash yorc deployments tasks resume [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. .. code-block:: bash yorc deployments tasks fix [flags] Scale a specific node ~~~~~~~~~~~~~~~~~~~~~ Scale a given node of a deployment by adding or removing the specified number of instances. .. code-block:: bash yorc deployments scale [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 . .. code-block:: bash yorc deployments custom [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: .. code-block:: bash yorc deployments custom deployID --custom cmdName --interface interfaceName --node nodeName --input 'key1=["value1","value2"]' --input 'key2="value3"' Example using ``--data`` flag: .. code-block:: bash yorc deployments custom deployID --data '{"name":"cmdName","interface":"interfaceName",""node":"nodeName","inputs":{"key1":["value1","value2"],"key2":"value3"}}' Example using ``--data`` flag with instances selection: .. code-block:: bash 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 . .. code-block:: bash yorc deployments workflows list [flags] Show a workflow on a given deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Show a human readable textual representation of a given TOSCA workflow defined in deployment . .. code-block:: bash yorc deployments workflows show [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: .. code-block:: bash yorc deployments workflows graph [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 . .. code-block:: bash yorc deployments workflows execute [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: .. code-block:: bash yorc deployments info -d deployID Example how to trigger the execution of workflow on instance "1" selected for node "node1", and workflow input parameters "key1" and "key2". .. code-block:: bash 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. .. code-block:: bash 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 workflow. You can then use the following command to get the status of this task, and workflow output values if any: .. code-block:: bash yorc deployments task info deployID taskId .. _yorc_cli_locations_section: 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 .. code-block:: bash 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. .. code-block:: bash yorc locations list Get information on a specific location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Display information about a given location (its type and properties). .. code-block:: bash yorc locations info Add a location ~~~~~~~~~~~~~~ Add a location defininition in JSON format. .. code-block:: bash 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: .. code-block:: bash yorc locations add --data '{"name": "testname", "type": "t", "properties" : { "p1" : "v1", "p2" : "v2" }}' Update a location ~~~~~~~~~~~~~~~~~ Update a given location's definition. .. code-block:: bash 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: .. code-block:: bash yorc locations add --data '{"name": "testname", "type": "other", "properties" : { "p1" : "v111" }}' Delete a location ~~~~~~~~~~~~~~~~~ Delete a given location. .. code-block:: bash yorc locations delete 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. .. code-block:: bash yorc locations apply [flags] Flags: * ``--auto-approve``: Skip interactive approval before applying the new locations configuration. .. _yorc_cli_hostspool_section: 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 .. code-block:: bash 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. .. code-block:: bash yorc hostspool locations Add a host in a hosts pool location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add host to a hosts pool location managed by this Yorc cluster. The 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. .. code-block:: bash yorc hostspool add -l [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): .. code-block:: JSON { "connection": { "host": "defaults_to_", "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 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. .. code-block:: bash yorc hostspool update -l [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): .. code-block:: JSON { "connection": { "host": "defaults_to_", "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 should exists. .. code-block:: bash yorc hostspool delete [...] -l 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. .. code-block:: bash yorc hostspool list -l [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 :ref:`yorc_infras_hostspool_filters_section` 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: .. code-block:: bash yorc hp list -f '"mylabel in (v1, v2)"' -l 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. .. code-block:: bash yorc hostspool info -l 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. .. code-block:: bash yorc hostspool apply -l 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 :ref:`yorc_infras_hostspool_filters_section` for more details on labels) Example of a YAML Hosts Pool configuration file : .. code-block:: YAML 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. .. code-block:: bash yorc hostspool export -l 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)