.. 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. This id should not already exist, should respect the following format: ``^[-_0-9a-zA-Z]+$`` and should be less than 36 characters long (Optional otherwise a unique ID is generated by Yorc) * ``-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. 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"}}' List workflows of a given deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lists workflows defined in a deployment . .. code-block:: bash yorc deployments workflows list [flags] Execute a workflow on a given deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Trigger a workflow on deployment . .. code-block:: bash yorc deployments workflows execute [flags] Flags: * ``--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**) 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 workflows name (**mandatory**) 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) .. _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``. Add a host pool ~~~~~~~~~~~~~~~ Adds a host to the hosts pool 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 [flags] Flags: * ``--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 pool ~~~~~~~~~~~~~~~~~~ Update labels list or connection of a host of the hosts pool 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 [flags] Flags: * ``--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 pool ~~~~~~~~~~~~~~~~~~ Deletes a host from the hosts pool managed by this Yorc cluster. The should exists. .. code-block:: bash yorc hostspool delete [...] List hosts in the pool ~~~~~~~~~~~~~~~~~~~~~~ Lists hosts of the hosts pool managed by this Yorc cluster. .. code-block:: bash yorc hostspool list [flags] Flags: * ``--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)"' Get information on a specific host in the pool ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Gets the description of a host of the hosts pool managed by this Yorc cluster. .. code-block:: bash yorc hostspool info Apply a Hosts Pool configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Applies a Hosts Pool configuration 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 Flags: * ``--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 configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Exports a Hosts Pool configuration as a YAML or JSON representation, to the standard output or a file. .. code-block:: bash yorc hostspool export Flags: * ``--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)