-.. _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_schema_version_1_0:
+
+Open Command Line Interface (CLI) Schema Version (OCS) 1.0
+==========================================================
Open CLI Platform (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
+* Software product/service information
* Command line arguments
* Command outputs
-* Software product information
-
-* REST API details
+* Command execution details like HTTP, SNMP (profiles)
-* Command usage
+* Command usage and samples
open_cli_schema_version
-----------------------
OCLIP considers any YAML file with first line having the following entry
-as proper template.
+as OCS template.
open_cli_schema_version: 1.0
Start the given service. To see the available services in the system
use the command *service-list*
-version
+info
-------
-*version* entry allows to tag the command template with the software product
+product
+~~~~~~~~
+*product* entry allows to tag the command template with the software product
name and version, for which command is implemented and is recommended to use
the following format:
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 discover 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 discover this service from the
-service catalog and version should be matching with the service version
-registered in the catalog.
-
-mode
-~~~~
-Some software 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:
+ (onap) version amsterdam, set the version as:
- 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
-
---------------------
+ **product** : **onap-amsterdam**
-auth
-~~~~
-There are different kind of authentication and authorization approach exist and
-for OCLIP provides support for following approaches. Based on the approach
-configured in the template, OCLIP will login before executing the command and
-logout afterwards.
+*CAUTION*: product should not have any space character in it.
-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 authentication 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 authentication approach and given *host-username* and
-*host-password* values are used to find the hash and use it as Authentication
-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
+parameters
---------
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,
author is allowed to customize the inclusion or exclusion of these input
parameters for a given command.
-name: onap-username
+name: host-username
~~~~~~~~~~~~~~~~~~~
type: string
- description: Onap user name
+ description: Host user name
short_option: u
- long_option: onap-username
+ long_option: host-username
- default_value: ${ONAP_USERNAME}
+ default_value: ${OPEN_CLI_HOST_USERNAME}
is_optional: false
-name: onap-password
+name: host-password
~~~~~~~~~~~~~~~~~~~
type: string
- description: Onap user password
+ description: Host user password
short_option: p
- long_option: onap-password
+ long_option: host-password
- default_value: ${ONAP_PASSWORD}
+ default_value: ${OPEN_CLI_HOST_PASSWORD}
is_secured: true
~~~~~~~~~~~~~~
type: url
- description: Onap host url
+ description: Host url
short_option: m
is_optional: false
- default_value: ${ONAP_HOST_URL}
+ default_value: ${OPEN_CLI_HOST_URL}
name: help
~~~~~~~~~~
type: string
- description: Onap command help message
+ description: Command help message
short_option: h
~~~~~~~~~~~~~
type: string
- description: Onap command service version
+ description: Command service version
short_option: v
default_value: false
*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
+of each commands. Please refer *service* section to find more details on login
and logout.
-For example, OCLIP platform provides a command called 'schema-validate' to
-validate schematics of template against the specification 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
-
-
-
results
-------
Every command produces the output and *results* section helps to define the
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.
+ 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.
+ useful while command does operations like listing of resource.
attributes
~~~~~~~~~~
* *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* : attribute 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
**scope: short**
+default_value
+^^^^^^^^^^^^^
+In some scenarios, author can set the default value to attribute which OCLIP assigns,
+when the value for that attribute is not available from back-end service in product.
+
+
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.
+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-amsterdam product,
+
+ service:
+ name: aai
+
+*CAUTION*: This entry is very signification to discover 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-amsterdam' having versions like v11.
+
+ service:
+ version: v11
+
+*CAUTION*: This entry is very signification to discover this service from the
+service catalog and version should be matching with the service version
+registered in the catalog.
+
+mode
+~~~~
+Some software 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-amsterdam' 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 authentication and authorization approach exist and
+for OCLIP provides support for following approaches. Based on the approach
+configured 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 authentication 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 authentication approach and given *host-username* and
+*host-password* values are used to find the hash and use it as Authentication
+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
+
+--------------------
request
~~~~~~~
*request* section captures all HTTP request information as:
q2: value2
+
+context
+^^^^^^^
+*context* entry allows to customize the HTTP request and response processing.
+
+Following are the supported customization parameters:
+
+*remove_empty_node* : By default, OCLIP does not remove the empty json entries
+ in request body. Otherwise set this entry to true as below.
+
+ request:
+
+ context:
+ remove_empty_node: true
+
success_codes
~~~~~~~~~~~~~
Every REST API has set of success codes and OCLIP will treat the HTTP request
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 response as reference 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. |
-+----------------+------------------------------------------------------------+
++------------------+------------------------------------------------------------+
+| Macro | Definitions |
++==================+============================================================+
+| ${param-name} | To retrieve the value from parameter named 'param-name' |
++------------------+------------------------------------------------------------+
+| $s{env:env-name} | To retrieve the value from environment variable 'env-name' |
++------------------+------------------------------------------------------------+
+| $s{uuid} | To set the value in uuid4 format |
++------------------+------------------------------------------------------------+
+| $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. |
++------------------+------------------------------------------------------------+
+
+samples
+-------
+
+OCLIP provides way to setup and verify the OCS yaml by using the open_cli_sample_version 1.0 specification,
+which provides options to capture the samples and expected out for the given moco environment.
Code Review / cli.git / blobdiff