Aliyun ROS Command-Line Tools
=============================

Prepare
-------

Requires
~~~~~~~~

-  Python 2.7
-  aliyun-python-sdk-ros

Config
~~~~~~

When use ros command for the first time, the ros-cli will create a
default configuration where ros installed.

::

    [ACCESS]
    ACCESS_KEY_ID = YOUR_KEY_ID
    ACCESS_KEY_SECRET = YOUR_KEY_SECRET
    REGION_ID = YOUR_REGION

    [OTHER]
    JSON_INDENT = 2
    DEBUG = False

Please use ``ros set-userdata`` to set your default configuration.

You can also input the region when using ros cli. In many cases, the
default configuration will be used if you don't specify the region.

Set DEBUG True to read more output.

Install
~~~~~~~

::

    pip install aliyun-python-sdk-ros

    pip install aliyun-ros-cli

Tab Completion
~~~~~~~~~~~~~~

Support tab completion in bash. Put the ``ros_completion`` file at ``/etc/bash_completion.d/`` 
and run ``source /etc/bash_completion.d/ros_completion``

``ros_completion`` content:

::

    #! /usr/bin/bash
    #
    # put this file at `/etc/bash_completion.d/` and run `source /etc/bash_completion.d/ros_completion`
    #
    # Copyright (c) 2017 Aliyun.com All right reserved. This software is the
    # confidential and proprietary information of Aliyun.com ("Confidential
    # Information"). You shall not disclose such Confidential Information and shall
    # use it only in accordance with the terms of the license agreement you entered
    # into with Aliyun.com .
    #
    # created by quming on 07/24/2017

    _ros()
    {
        # cur prev ros_father
        local cur prev opts_top opts_cmds
        COMPREPLY=()
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
        opts_top="-h --help --json --config --region-id"
        opts_cmds="abandon-stack \
            create-stack \
            delete-stack \
            describe-stack describe-resource \
            get-template \
            list-stacks list-resources list-regions list-events \
            preview-stack \
            resource-type resource-type-detail resource-type-template \
            set-userdata \
            update-stack \
            validate-template"

        local opt_abandon_stack="-h --help --region-id --stack-name --stack-id"

        local opt_create_stack="-h --help --region-id --stack-name \
            --template-url --parameters --disable-rollback \
            --timeout-in-minutes"

        local opt_delete_stack="-h --help --region-id --stack-name --stack-id"
        local opt_describe_stack="-h --help --stack-name --stack-id"
        local opt_describe_resource="-h --help --stack-name --stack-id --resource-name"

        local opt_get_template="-h --help --stack-name --stack-id"

        local opt_list_stacks="-h --help --stack-name --stack-id --region-id \
            --status --page-number --page-size"
        local opt_list_resources="-h --help --stack-name --stack-id"
        local opt_list_regions="-h --help"
        local opt_list_events="-h --help --stack-name --stack-id --resource-status \
            --resource-name --resource-type --page-number --page-size"

        local opt_preview_stack="-h --help --region-id --stack-name --stack-id \
            --template-url --parameters --disable-rollback \
            --timeout-in-minutes"

        local opt_resource_type="-h --help --status"
        local opt_resource_type_detail="-h --help --name"
        local opt_resource_type_template="-h --help --name"

        local opt_set_userdata="-h --help --key-id --key-secret --json --region-id"

        local opt_update_stack="-h --help --region-id --stack-name --stack-id \
            --template-url --parameters --disable-rollback \
            --timeout-in-minutes"

        local opt_validate_template="-h --help --template-url"


        # if [ -z "${cur}" ]; then
        if [ "${prev}"x = "ros"x ]; then
            ros_father=""
        fi

        if [[ ${opts_cmds} = *${prev}* ]]; then
            ros_father=${prev}
        fi

        # echo "["${cur}"]["${prev}"]["${ros_father}"]"

        case "${ros_father}" in
            abandon-stack)
                COMPREPLY=($(compgen -W "${opt_abandon_stack}" -- ${cur}))
                return 0
                ;;
            create-stack)
                COMPREPLY=($(compgen -W "${opt_create_stack}" -- ${cur}))
                return 0
                ;;
            delete-stack)
                COMPREPLY=($(compgen -W "${opt_delete_stack}" -- ${cur}))
                return 0
                ;;
            describe-stack)
                COMPREPLY=($(compgen -W "${opt_describe_stack}" -- ${cur}))
                return 0
                ;;
            describe-resource)
                COMPREPLY=($(compgen -W "${opt_describe_resource}" -- ${cur}))
                return 0
                ;;
            get-template)
                COMPREPLY=($(compgen -W "${opt_get_template}" -- ${cur}))
                return 0
                ;;
            list-stacks)
                COMPREPLY=($(compgen -W "${opt_list_stacks}" -- ${cur}))
                return 0
                ;;
            list-resources)
                COMPREPLY=($(compgen -W "${opt_list_resources}" -- ${cur}))
                return 0
                ;;
            list-regions)
                COMPREPLY=($(compgen -W "${opt_list_regions}" -- ${cur}))
                return 0
                ;;
            list-events)
                COMPREPLY=($(compgen -W "${opt_list_events}" -- ${cur}))
                return 0
                ;;
            preview-stack)
                COMPREPLY=($(compgen -W "${opt_preview_stack}" -- ${cur}))
                return 0
                ;;
            resource-type)
                COMPREPLY=($(compgen -W "${opt_resource_type}" -- ${cur}))
                return 0
                ;;
            resource-type-detail)
                COMPREPLY=($(compgen -W "${opt_resource_type_detail}" -- ${cur}))
                return 0
                ;;
            resource-type-template)
                COMPREPLY=($(compgen -W "${opt_resource_type_template}" -- ${cur}))
                return 0
                ;;
            set-userdata)
                COMPREPLY=($(compgen -W "${opt_set_userdata}" -- ${cur}))
                return 0
                ;;
            update-stack)
                COMPREPLY=($(compgen -W "${opt_update_stack}" -- ${cur}))
                return 0
                ;;
            validate-template)
                COMPREPLY=($(compgen -W "${opt_validate_template}" -- ${cur}))
                return 0
                ;;
            *)
                if [[ ${cur} == -* ]] ; then
                    COMPREPLY=($(compgen -W "${opts_top}" -- ${cur}))
                    return 0
                else
                    COMPREPLY=($(compgen -W "${opts_cmds}" -- ${cur}))
                    return 0
                fi
            ;;
        esac
    }

    complete -F _ros ros

Help
----

If you want more details, please visit `ROS
API <https://help.aliyun.com/document_detail/28898.html?spm=5176.doc28910.3.2.NjqtWX>`__.

Top Class Commands
~~~~~~~~~~~~~~~~~~

::

    $ ros -h
    usage: ros [-h] [--config CONFIG_FILE] [--json] [--region-id REGION_ID]  ...

    optional arguments:
      -h, --help            show this help message and exit
      --config CONFIG_FILE  Location of config file
      --json                Print results as JSON format
      --region-id REGION_ID
                            Region ID, if not set, use config file's field

    commands:

        set-userdata        Set default Aliyun access info
        create-stack        Creates a stack as specified in the template
        delete-stack        Deletes the specified stack
        update-stack        Update a stack as specified in the template
        preview-stack       Preview a stack as specified in the template
        abandon-stack       Abandon the specified stack
        list-stacks         Returns the summary information for stacks whose
                            status matches the specified StackStatusFilter
        describe-stack      Returns the description for the specified stack
        list-resources      Returns descriptions of all resources of the specified
                            stack
        describe-resource   Returns a description of the specified resource in the
                            specified stack
        resource-type       Returns types of resources
        resource-type-detail
                            Returns detail of the specific resource type
        resource-type-template
                            Returns template of the specific resource type
        get-template        Returns the template body for a specified stack
        validate-template   Validates a specified template
        list-regions        Returns all regions avaliable
        list-events         Returns all stack related events for a specified stack
                            in reverse chronological order

Commands on stacks
~~~~~~~~~~~~~~~~~~

Create stack
^^^^^^^^^^^^

::

    $ ros create-stack -h
    usage: ros create-stack [-h] [--region-id REGION_ID] --stack-name STACK_NAME
                            --template-url TEMPLATE_URL [--parameters PARAMETERS]
                            [--disable-rollback DISABLE_ROLLBACK]
                            [--timeout-in-minutes TIMEOUT_IN_MINUTES]

    optional arguments:
      -h, --help            show this help message and exit
      --region-id REGION_ID
                            The region that is associated with the stack
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --template-url TEMPLATE_URL
                            Location of file containing the template body
      --parameters PARAMETERS
                            A list of Parameter structures that specify input
                            parameters for the stack. Synatax: key=value,key=value
      --disable-rollback DISABLE_ROLLBACK
                            Set to true to disable rollback of the stack if stack
                            creation failed
      --timeout-in-minutes TIMEOUT_IN_MINUTES
                            The amount of time that can pass before the stack
                            status becomes CREATE_FAILED

Delete stack
^^^^^^^^^^^^

::

    $ ros delete-stack -h
    usage: ros delete-stack [-h] --region-id REGION_ID --stack-name STACK_NAME
                            --stack-id STACK_ID

    optional arguments:
      -h, --help            show this help message and exit
      --region-id REGION_ID
                            The region that is associated with the stack
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack

Update stack
^^^^^^^^^^^^

::

    $ ros update-stack -h
    usage: ros update-stack [-h] --region-id REGION_ID --stack-name STACK_NAME
                            --stack-id STACK_ID --template-url TEMPLATE_URL
                            [--parameters PARAMETERS]
                            [--disable-rollback DISABLE_ROLLBACK]
                            [--timeout-in-minutes TIMEOUT_IN_MINUTES]

    optional arguments:
      -h, --help            show this help message and exit
      --region-id REGION_ID
                            The region that is associated with the stack
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack
      --template-url TEMPLATE_URL
                            Location of file containing the template body
      --parameters PARAMETERS
                            A list of Parameter structures that specify input
                            parameters for the stack. Synatax: key=value,key=value
      --disable-rollback DISABLE_ROLLBACK
                            Set to true to disable rollback of the stack if stack
                            creation failed
      --timeout-in-minutes TIMEOUT_IN_MINUTES
                            The amount of time that can pass before the stack
                            status becomes CREATE_FAILED

Preview stack
^^^^^^^^^^^^^

::

    $ ros preview-stack -h
    usage: ros preview-stack [-h] [--region-id REGION_ID] --stack-name STACK_NAME
                             --template-url TEMPLATE_URL [--parameters PARAMETERS]
                             [--disable-rollback DISABLE_ROLLBACK]
                             [--timeout-in-minutes TIMEOUT_IN_MINUTES]

    optional arguments:
      -h, --help            show this help message and exit
      --region-id REGION_ID
                            The region that is associated with the stack
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --template-url TEMPLATE_URL
                            Location of file containing the template body
      --parameters PARAMETERS
                            A list of Parameter structures that specify input
                            parameters for the stack. Synatax: key=value,key=value
      --disable-rollback DISABLE_ROLLBACK
                            Set to true to disable rollback of the stack if stack
                            creation failed
      --timeout-in-minutes TIMEOUT_IN_MINUTES
                            The amount of time that can pass before the stack
                            status becomes CREATE_FAILED

Abandon stack
^^^^^^^^^^^^^

::

    $ ros abandon-stack -h
    usage: ros abandon-stack [-h] --region-id REGION_ID --stack-name STACK_NAME
                             --stack-id STACK_ID

    optional arguments:
      -h, --help            show this help message and exit
      --region-id REGION_ID
                            The region that is associated with the stack
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack

List stacks
^^^^^^^^^^^

::

    $ ros list-stacks -h
    usage: ros list-stacks [-h] [--stack-name STACK_NAME] [--stack-id STACK_ID]
                           [--status {CREATE_COMPLETE,CREATE_FAILED,CREATE_IN_PROGRESS,DELETE_COMPLETE,DELETE_FAILED,DELETE_IN_PROGRESS,ROLLBACK_COMPLETE,ROLLBACK_FAILED,ROLLBACK_IN_PROGRESS}]
                           [--region-id REGION_ID] [--page-number PAGE_NUMBER]
                           [--page-size PAGE_SIZE]

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack
      --status {CREATE_COMPLETE,CREATE_FAILED,CREATE_IN_PROGRESS,DELETE_COMPLETE,DELETE_FAILED,DELETE_IN_PROGRESS,ROLLBACK_COMPLETE,ROLLBACK_FAILED,ROLLBACK_IN_PROGRESS}
                            status of stacks
      --region-id REGION_ID
                            The region of stacks
      --page-number PAGE_NUMBER
                            The page number of stack lists, start from 1, default
                            1
      --page-size PAGE_SIZE
                            Lines each page, max 100, default 10

Describe stack
^^^^^^^^^^^^^^

::

    $ ros describe-stack -h
    usage: ros describe-stack [-h] --stack-name STACK_NAME --stack-id STACK_ID

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack

Commands on resources
~~~~~~~~~~~~~~~~~~~~~

List resources
^^^^^^^^^^^^^^

::

    $ ros list-resources -h
    usage: ros list-resources [-h] --stack-name STACK_NAME --stack-id STACK_ID

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name of stack
      --stack-id STACK_ID   The id of stack

Describe resource
^^^^^^^^^^^^^^^^^

::

    $ ros describe-resource -h
    usage: ros describe-resource [-h] --stack-name STACK_NAME --stack-id STACK_ID
                                 --resource-name RESOURCE_NAME

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name of stack
      --stack-id STACK_ID   The id of stack
      --resource-name RESOURCE_NAME
                            The name of resource

Resource type
^^^^^^^^^^^^^

::

    $ ros resource-type -h
    usage: ros resource-type [-h]
                             [--status {UNKNOWN,SUPPORTED,DEPRECATED,UNSUPPORTED,HIDDEN}]

    optional arguments:
      -h, --help            show this help message and exit
      --status {UNKNOWN,SUPPORTED,DEPRECATED,UNSUPPORTED,HIDDEN}
                            The status of resource

Resource type detail
^^^^^^^^^^^^^^^^^^^^

::

    $ ros resource-type-detail -h
    usage: ros resource-type-detail [-h] --name NAME

    optional arguments:
      -h, --help   show this help message and exit
      --name NAME  The name of resource

Resource type template
^^^^^^^^^^^^^^^^^^^^^^

::

    $ ros resource-type-template -h
    usage: ros resource-type-template [-h] --name NAME

    optional arguments:
      -h, --help   show this help message and exit
      --name NAME  The name of resource

Commands on template
~~~~~~~~~~~~~~~~~~~~

Get template
^^^^^^^^^^^^

::

    $ ros get-template -h
    usage: ros get-template [-h] --stack-name STACK_NAME --stack-id STACK_ID

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack

Validate template
^^^^^^^^^^^^^^^^^

::

    $ ros validate-template -h
    usage: ros validate-template [-h] --template-url TEMPLATE_URL

    optional arguments:
      -h, --help            show this help message and exit
      --template-url TEMPLATE_URL
                            Location of file containing the template body

Other commands
~~~~~~~~~~~~~~

List regions
^^^^^^^^^^^^

List all regions and need no parameters.

::

    $ ros list-regions -h
    usage: ros list-regions [-h]

    optional arguments:
      -h, --help  show this help message and exit

List events
^^^^^^^^^^^

::

    $ ros list-events -h
    usage: ros list-events [-h] --stack-name STACK_NAME --stack-id STACK_ID
                           [--resource-status {COMPLETE,FAILED,IN_PROGRESS}]
                           [--resource-name RESOURCE_NAME]
                           [--resource-type RESOURCE_TYPE]
                           [--page-number PAGE_NUMBER] [--page-size PAGE_SIZE]

    optional arguments:
      -h, --help            show this help message and exit
      --stack-name STACK_NAME
                            The name that is associated with the stack
      --stack-id STACK_ID   The id that is associated with the stack
      --resource-status {COMPLETE,FAILED,IN_PROGRESS}
                            status of resources: COMPLETE\FAILED\IN_PROGRESS
      --resource-name RESOURCE_NAME
                            The name of resources
      --resource-type RESOURCE_TYPE
                            The type of resources
      --page-number PAGE_NUMBER
                            The page number of stack lists, start from 1, default
                            1
      --page-size PAGE_SIZE
                            Lines each page, max 100, default 10

Set userdata
^^^^^^^^^^^^

::

    $ ros set-userdata -h
    usage: ros set-userdata [-h] --key-id KEY_ID --key-secret KEY_SECRET
                        --region-id REGION_ID [--json-ident JSON_IDENT]
                        [--debug {False,True}]

    optional arguments:
      -h, --help            show this help message and exit
      --key-id KEY_ID       The default Aliyun access key id
      --key-secret KEY_SECRET
                            The default Aliyun access key region
      --region-id REGION_ID
                            The default region
      --json-ident JSON_IDENT
                            The default json indent when output in json format
      --debug {False,True}  Whether to read debug infos
