diff options
| -rw-r--r-- | docs/index.rst | 11 | ||||
| -rw-r--r-- | docs/open_cli_schema_version_1_0.rst | 835 |
2 files changed, 843 insertions, 3 deletions
diff --git a/docs/index.rst b/docs/index.rst index 833e1aa9..9aba9c6b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,13 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 Huawei Technologies Co., Ltd. + +.. _cli_index: + +CLI Documentation +================== -TODO Add files to toctree and delete this header ------------------------------------------------- .. toctree:: :maxdepth: 1 - + open_cli_schema_version_1_0.rst diff --git a/docs/open_cli_schema_version_1_0.rst b/docs/open_cli_schema_version_1_0.rst new file mode 100644 index 00000000..98a0cafb --- /dev/null +++ b/docs/open_cli_schema_version_1_0.rst @@ -0,0 +1,835 @@ +.. _open_cli_schema_version_1_0: +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 Huawei Technologies Co., Ltd. + +Open Command Line Interface (CLI) Schema Version 1.0 +==================================================== + +Open CLI Platfrom (OCLIP) provides model based framework to implement +Linux Commands for any given software products, by using YAML template +based on the schematics defined in this document. In version 1.0, +following aspects of commands are modeled as YAML schematics: + +* Basic Command information + +* Command line arguments + +* Command outputs + +* Software product information + +* REST API details + +* Command usage + +open_cli_schema_version +----------------------- +OCLIP considers any YAML file with first line having the following entry +as proper template. + + open_cli_schema_version: 1.0 + +Here, 1.0 version is first version of this schema. In future, this version +number will get incremented based on addition of new schematics or update of +existing schematics. + +name +---- +*name* entry allows to set the command name and it is recommended to use the +following format: + + <entity>-<action> + + entity - Resource or a feature, for which command is provided + + action - Functionality performed on the entity + + For example, to implement a command to *start* a given *service*. + set the name as: + + **name** : **service-start** + +*CAUTION*: name should not have any space character in it. + +description +----------- +*description* entry allows to write detailed usage of the command. It could be +a line or a paragraph as given example here. + +**a line** + + description: Start the given service + +**a paragraph** + + description: | + Start the given service. To see the available services in the system + use the command *service-list* + +version +------- +*version* entry allows to tag the command template with the software product +name and version, for which command is implemented and is recommanded to use +the following format: + + <product>-<version> + + product - Short name of the product + + action - Version of the product + + For example, to implement a command for Open Network Automation Platform + (onap) version 1.1, set the version as: + + **version** : **onap-1.1** + +*CAUTION*: version should not have any space character in it. + +service +------- +Whether its information technology(IT) domain or communication technology(CT) +domain, every software product is made of one or more service components. For +example, onap has different components like aai, msb, etc and these components +provides different kind of resources/features and functionalities. + +*service* entry allows to mention the details of the given software product's +service. This is an section and is having entries defined in below sections. + +name +~~~~ +*name* entry allows to configure the service name. For example, to configure +service component 'aai' in onap-1.1 product, + + service: + name: aai + +*CAUTION*: This entry is very signification to disover this service from the +service catalog and name should be matching with the service name registered +in the catalog. + +version +~~~~~~~ +*version* entry allows to mention the particular version of service for which +command is implemented. For example, the service 'aai' in the product +'onap-1.1' having versions like v11. + + service: + version: v11 + +*CAUTION*: This entry is very signification to disover this service from the +service catalog and version should be matching with the service version +registered in the catalog. + +mode +~~~~ +Some oftware product provides catalog service , where all service of that +product could be discovered. While other product does not. OCLIP provides +support for both kind of these products to implement commands and *mode* +entry allows to configure this mode of operation. + +CLIP supports in two different mode. + +In *catalog* mode, OCLIP will discover the service details based on given +*name* and *version* from the configured *host-url* parameter. For example, +the product 'onap-1.1' provides the service 'msb' as the catalog service where +all other services will get registered. so OCLIP can discover the given +service such as 'aai' from the catalog service 'msb'. In this mode, *host-url* +will be configured with the *msb* service url. In this case: + + service: + mode: catalog + +*NOTE*: To see the details of *host-url*, refer the section default_parameters + +In *direct* mode, OCLIP will not perform the discovery operation and consider +the given *host-url* as the direct service url. In this case: + + service: + mode: direct + +*NOTE*: To see the details of *host-url*, refer the section default_parameters + +-------------------- + +auth +---- +There are different kind of authedication and authorization approach exist and +for OCLIP provides support for following approaches. Based on the approach +configufed in the template, OCLIP will login before executing the command and +logout afterwards. + +none +~~~~ +In this approach, no login and logout will be performed. This is useful during +the development cycle, as well as some services are available in public +without authedication of user. In this approach, OCLIP ignores the given +*host-username* and *host-password*. So the none auth is defined by: + + service: + auth: none + +*NOTE*: To see the details of *host-username* and *host-password*, refer the +section default_parameters + + +basic +~~~~~ +This is HTTP basic authedication approach and given *host-username* and +*host-password* values are used to find the hash and use it as Authendication +value. So the none auth is defined by: + + service: + auth: basic + +*NOTE*: To see the details of *host-username* and *host-password*, refer the +section default_parameters + +-------------------- + +paramters +--------- +Every command has set of arguments to provide the input values and *parameters* +section allows to add the required arguments details such as name, description, +etc as list of entries. + +name +~~~~ +*name* entry uniquely identifies the given argument. It can be of any +alphanumerical characters and dash(-). For example to provide the http port of +an service, the parameter could be: + + parameters: + \- **name: service-port** + +description +~~~~~~~~~~~ +*description* entry allows to provide the details of the parameter. Its +supported in similar approach with command *description* defined in above +section. For example service-port could be described as: + + parameters: + \- name: service-port + + **description: Service HTTP port.** + +is_optional +~~~~~~~~~~~ +*is_optional* entry allows to set the parameter is mandatory or not. By default, +this entry is false. For example service-port could be made as as optional: + + parameters: + \- name: service-port + + description: Service HTTP port. + + **is_optional: true** + +is_secured +~~~~~~~~~~~ +*is_secured* entry allows to set the parameter is secured or not. By default, +this entry is false. This is very useful for password kind of parameters. + +For example service-port could be made as insecured: + + parameters: + \- name: service-port + + description: Service HTTP port. + + is_optional: true + + **is_secured: false** + +default_value +~~~~~~~~~~~~~ +*default_value* entry helps to provide the default value for the given parameter +when that parameter is not provided during command execution. + +Based on the *type* of parameter, default values are assigned as: + ++---------------+------------------------------------------------------------+ +| Type | Default value | ++===============+============================================================+ +| bool | false | ++---------------+------------------------------------------------------------+ +| uuid | Auto-generated uuid-4 string | ++---------------+------------------------------------------------------------+ +| string | Blank. Also it can be set default values from the system | +| | environment variable by mentioning it in the form of : | +| | | +| | parameters: | +| | - default_value: ${ENV-VARIABLE-NAME} | ++---------------+------------------------------------------------------------+ + +For example to provide the http port of an service, the parameter could be: + + parameters: + \- name: service-port + + description: Service HTTP port. + + is_optional: true + + is_secured: false + + **default_value: 8080** + + +type +---- +*type* entry allows to set the type of parameter such as boolean, integer, etc. +For example to provide the http port of an service, the parameter type could be: + + parameters: + \- name: service-port + + description: Service HTTP port. + + is_optional: true + + is_secured: false + + default_value: 8080 + + **type: long** + +Platform supports following types of parameter: + +string +~~~~~~ +Any parameter value having a work or a line, string type is appropriate one. By +default it is set to blank. + +digit +~~~~~~ +Any parameter value having digit such as integers or floating values. For this +type of parameter, platform does not set any default value. so while writing +the parameter schematics, author should set the *default_value* if needed. + +json +~~~~~~ +To set the value of parameter as JSON. Platform allows to input the JSON values +either as direct one line string for simple json or complete file path for +providing the complex json value. While user execute the command, based on the +value of the JSON parameter, it could given as string or file path. + +File path could start in the form of file://, http://, ftp://. + +text +~~~~~~ +To set the value of parameter as text. Platform allows to input the text values +either as direct one line string for simple text or complete file path for +providing the complex text value. While user execute the command, based on the +value of the text parameter, it could given as string or file path. + +File path could start in the form of file://, http://, ftp://. + +yaml +~~~~~~ +To set the value of parameter as yaml content. Platform allows to input the +yaml values as complete file path. While user execute the command, YAML file +needs to be created and provided that file's complete path as input value. + +File path could start in the form of file://, http://, ftp://. + +bool +~~~~~~ +This type allows to set the parameter value to either true or false. By +default, its value is false, So, when user wants to input the boolean parameter +its sufficient to mention the parameter option with out mentoinging 'true'. +For example, assume that command named 'login' defines the boolean input +parameter 'is_secure_connection' to set the service connection is secured or +not. For this command, while user input the value for parameter +'is_secure_connection', it is sufficient to mention the parameter without +passing value. Both of the following command will have same effect: + + login --is_secure_connection + + login --is_secure_connection true + +uuid +^^^^ +*uuid* type allows to make the parameter value as UUID. By default platform auto +generates uuid-4 formated string. + +url +^^^ +*url* type allows to make the parameter value of URL/URI. Platform does not +provide any default value for this type. so Author should provide the +*default_value*, if needed during the template is created. + +binary +~~~~~~ +*binary* type is very useful to pass the parameter as binary file and user +should pass the complete path of the file. + +array +~~~~~~ +To provide the same parameter mutiple times array type helps. For example, when +the command 'rm' is used, mutiple file paths could be provided to remove all of +them. In this kind of scenarios, array type supports and each parameter type +is *string* + +map +~~~~~~ +This is similar to *array* type and only differs the way the values are passed. +In this type, values should be in the form of +'<parameter-name>=<parameter-value>' + + +Optional and Positional parameters +---------------------------------- +The input arguments for a given command usually provided with prefixing options +names or directly giving the value. Earlier case is called optional arguments +and later is called as positional arguments. OCLIP platform supports both the +type. + +For optional arguments, two type of options are supported: + +*short option*: option name is usually single character and when user input +the corresponding parameter, who will prefix with single dash(-). + +*long option*: option name is usually more than one characters and when user +input the corresponding parameter, who will prefix with double dash(-). + +For example, the service port could be defined as : + + parameters: + \ - name: service-port + + description: Service HTTP port. + + is_optional: true + + is_secured: false + + default_value: 8080 + + type: long + + **short_option: p** + + **long_option: service-port** + +When user inputs the service port, it could either of following formats + + --service-port 8080 + + -p 8080 + +For postional arguments, author should not define both *short_option* and +*long_option* and when OCLIP process this template, it will consider as +positional arguments. There could be more than one positional arguments could +be defined for a command, and OCLIP treats the sequence of the postional +parameters defined under *parameters* section is consider as it's position. For +example, consider the below example: + + parameters: + \- name: param1 + + short_option: p1 + + long_option: param1 + + \- name: param2 + + \- name: param3 + + short_option: p3 + + long_option: param3 + + \- name: param4 + + \- name: param5 + + short_option: p5 + + long_option: param5 + +In this case, param2 and param4 are positional arguments as they are defined +with out short and long options. so postion of param2 is 1, for param4, it's 2. +When user inputs the value as : + + --param1 v1 -p3 v3 v2 -p5 v5 v4 + +OCLIP platform identifies the positions in sequence. so for param2, value v2 +will be assigned and for param4, value v4 will be assigned. + +*NOTE*: User should only concern on the sequence of positional arguments while +giving the values and no need to worry about the position at which value should +be provided. so all of below sequence will yeild the same result. + + --param1 v1 -p3 v3 **v2** -p5 v5 **v4** + + **v2** --param1 v1 **v4** -p5 v5 -p3 v3 + + --param1 v1 -p3 -p5 v5 v3 **v2** **v4** + +default_parameters +------------------ +OCLIP platform provides following default parameters for every command and +author is allowed to customize the inclution or exclution of these input +parameters for a given command. + +name: onap-username +~~~~~~~~~~~~~~~~~~~ + + type: string + + description: Onap user name + + short_option: u + + long_option: onap-username + + default_value: ${ONAP_USERNAME} + + is_optional: false + +name: onap-password +~~~~~~~~~~~~~~~~~~~ + + type: string + + description: Onap user password + + short_option: p + + long_option: onap-password + + default_value: ${ONAP_PASSWORD} + + is_secured: true + + is_optional: false + +name: host-url +~~~~~~~~~~~~~~ + type: url + + description: Onap host url + + short_option: m + + long_option: host-url + + is_optional: false + + default_value: ${ONAP_HOST_URL} + +name: help +~~~~~~~~~~ + type: string + + description: Onap command help message + + short_option: h + + long_option: help + + default_value: false + +name: version +~~~~~~~~~~~~~ + type: string + + description: Onap command service version + + short_option: v + + long_option: version + + default_value: false + +name: debug +~~~~~~~~~~~ + type: bool + + description: Enable debug output + + short_option: d + + long_option: debug + + default_value: false + +name: format +~~~~~~~~~~~~ + type: string + + description: Output formats, supported formats such as table, csv, json, + yaml + + short_option: f + + long_option: format + + default_value: table + +name: long +~~~~~~~~~~~ + type: bool + + description: whether to print all attributes or only short attributes + + short_option: s + + long_option: long + + default_value: false + +name: no-title +~~~~~~~~~~~~~~ + type: bool + + description: whether to print title or not + + short_option: t + + long_option: no-title + + default_value: true + +name: no-auth +~~~~~~~~~~~~~ + type: bool + + description: whether to authenticate user or not + + short_option: a + + long_option: no-auth + + default_value: false + +For example, OCLIP platfrom provides a command called 'schema-validate' to +validate schematics of template against the specificatio defined in this +document. For this command, host-url, onap-username, onap-password, no-auth +parameters are required. so author could exclude these parameters by defining +as : + + default_parameters: + exclude: + \- onap-username + + \- onap-password + + \- host-url + + \- no-auth + +*NOTE*: no-auth parameter is very helpful to by-pass the login and logout phase +of each commands. Please refere *service* section to find more details on login +and logout. + +results +------- +Every command produces the output and *results* section helps to define the +details of command outputs such as list of output attributes, the direction in +which, result could be printed. More details are as follows. + +direction +~~~~~~~~~ +*direction* entity allows to configure the direction in which the results to be +printed. It can be: + +* *portrait* : To print the results in two columns. First column is the name of +the attribute and second column is the value of the attribute. It's more useful +while command does operations like creation of resource, viewing of resources. + +* *landscape* : To print the results row vise in landscape mode. It's more +useful while command does operations like listing of resource. + +attributes +---------- +name +~~~~ +*name* entry uniquely identifies the given attribute. It can be of any +alphanumerical characters and dash(-). For example to print the status of an +service, the attribute could be: + + attributes: + \- **name: service-status** + +description +~~~~~~~~~~~ +*description* entry allows to provide the details of the attribute. It's +supported in similar approach with command *description* defined in above +section. For example service-status could be described as: + + attributes: + \- name: service-status + + **description: Service current status.** + +type +~~~~ +*type* entry allows to set the type of attribute such as string, digit, etc. +Similar to the parameter's type. currently it supports only string type. + +For example, service-status could be: + + attributes: + + \- name: service-status + + description: Service current status. + + **type: string** + +scope +~~~~~ +When a given command produces many results, most of the time no need to print +all the attributes. SO OCLIP platform provides this *scope* entry to configure +the attribute is printed by default or user should request to print it. So +there are two scopes: + +* *short* : attribute configured with this option will always printed by default + +* *long* : attriuted configured with this option will get printed only when +user inputs the default parameter *long*, defined in *default_parameters* +section. So to print all attributes of a command, user will input parameter: + + --long + +A sample attribute for service-status could be: + + attributes: + \- name: service-status + + description: Service current status. + + type: string + + **scope: short** + +http +---- +OCLIP is enhanced to support REST API based products and *http* section is +provided to capture all required details for performing http operation for the +given command. + +request +------- +*request* section captures all HTTP request information as: + +uri +~~~ +*uri* entry allows to mention the REST API URI. Based on the *service mode*, +this entry will vary. * when the mode is 'direct', it should be configured with +out *host-url* portion in it. For example, if the REST API is +'<host-url>/v1/service1/resource1, in which + +* /v1/service1 - base path +* /resource1 - service resource path. + +then this entry will be: + + request: + uri: /v1/service1/resource1 + +when the mode is 'catalog', OCLIP will discover the base path from the +'catalog' service, so this entry need to be configured only with resource path +as: + + request: + uri: /resource1 + +method +~~~~~~ +*method* entry allows to configure the HTTP methods GET, PUT, POST, DELETE, +etc. For example, to get the resource1: + + request: + uri: /resource1 + + method: GET + +body +~~~~ +*body* entry allows to mention the request body in json format, by default. +And OCLIP adds 'application/json' header in the HTTP request. Otherwise, body +could have complete path to binary file, in case request body is binary and +*multipart_entity_name* should be configured with entity name provided by REST +API. + +headers +~~~~~~~~ +*headers* entry allows to add REST API specific headers. By default OCLIP adds +'application/json' as content-type and accept, also it will adds authedication +headers such as 'Authendication' in case *auth* is of type 'basic'. + +For example, to add the sample header : + + request: + uri: /resource1 + + method: GET + + headers: + header1: value1 + + header2: value2 + +queries +~~~~~~~~ +*queries* entry allows to add REST API specific queries. For example, to add +the sample queries : + + request: + uri: /resource1 + + method: GET + + queries: + q1: value1 + + q2: value2 + +success_codes +^^^^^^^^^^^^^ +Every REST API has set of success codes and OCLIP will treat the HTTP request +made based on the value configured in these http sections, only if +*success_codes* contains the HTTP response status code. + +result_map +~~~~~~~~~~ +This section allows to configure the require 'jpath' expression to retrieve the +values from the HTTP response body. + +*NOTE*: Currently only http response body is supported only with json type. + +For example, if a http response '{"service_status": "green"} then to retrieve +the service status and assign to result *attribute* service_status as : + + result_map: + service_status: $b{$.service_status} + +Here, $b is detailed in section 'macros' of this document. and +'$.service_status' is jpath expression. + +sample_response +~~~~~~~~~~~~~~~ +This entry allows to keep the sample HTTP resonse as refrence to understand +the result_map jpath expressions. OCLIP does not use this entry and is optional. + +macros +~~~~~~ +OCLIP platform provides various marcos to fill *http* entries with the value +of *parameters*, *headers* , etc Every macro is in the form of <macro name> +followed by {<macro details>}Followings are the supported macros: + ++----------------+------------------------------------------------------------+ +| Macro | Definitions | ++================+============================================================+ +| ${param-name} | To retrieve the value from parameter named 'param-name' | ++----------------+------------------------------------------------------------+ +| $h{header-name}| To retrieve the value from header named 'header-name' | ++----------------+------------------------------------------------------------+ +| $q{query-name} | To retrieve the value from query named 'query-name' | ++----------------+------------------------------------------------------------+ +| $b{jpath} | To retrieve the value from response body using the 'jpath' | +| | expression. | ++----------------+------------------------------------------------------------+ |