docs/open_cli_schema_version_1_0.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 Huawei Technologies Co., Ltd.
   4
   5 .. _open_cli_schema_version_1_0:
   6
   7 Open Command Line Interface (CLI) Schema Version (OCS) 1.0
   8 ==========================================================
   9
  10 Open CLI Platform (OCLIP) provides model based framework to implement
  11 Linux Commands for any given software products, by using YAML template
  12 based on the schematics defined in this document. In version 1.0,
  13 following aspects of commands are modeled as YAML schematics:
  14
  15 * Software product/service information
  16
  17 * Command line arguments
  18
  19 * Command outputs
  20
  21 * Command execution details like HTTP, SNMP (profiles)
  22
  23 * Command usage and samples
  24
  25 open_cli_schema_version
  26 -----------------------
  27 OCLIP considers any YAML file with first line having the following entry
  28 as OCS template.
  29
  30     open_cli_schema_version: 1.0
  31
  32 Here, 1.0 version is first version of this schema. In future, this version
  33 number will get incremented based on addition of new schematics or update of
  34 existing schematics.
  35
  36 name
  37 ----
  38 *name* entry allows to set the command name and it is recommended to use the
  39 following format:
  40
  41     <entity>-<action>
  42
  43     entity - Resource or a feature, for which command is provided
  44
  45     action - Functionality performed on the entity
  46
  47     For example, to implement a command to *start* a given *service*.
  48     set the name as:
  49
  50     **name** : **service-start**
  51
  52 *CAUTION*: name should not have any space character in it.
  53
  54 description
  55 -----------
  56 *description* entry allows to write detailed usage of the command. It could be
  57 a line or a paragraph as given example here.
  58
  59 **a line**
  60
  61     description: Start the given service
  62
  63 **a paragraph**
  64
  65     description: |
  66         Start the given service. To see the available services in the system
  67         use the command *service-list*
  68
  69 info
  70 -------
  71 product
  72 ~~~~~~~~
  73 *product* entry allows to tag the command template with the software product
  74 name and version, for which command is implemented and is recommended to use
  75 the following format:
  76
  77     <product>-<version>
  78
  79     product - Short name of the product
  80
  81     action - Version of the product
  82
  83     For example, to implement a command for Open Network Automation Platform
  84     (onap) version amsterdam, set the version as:
  85
  86     **product** : **onap-amsterdam**
  87
  88 *CAUTION*: product should not have any space character in it.
  89
  90
  91 parameters
  92 ---------
  93 Every command has set of arguments to provide the input values and *parameters*
  94 section allows to add the required arguments details such as name, description,
  95 etc as list of entries.
  96
  97 name
  98 ~~~~
  99 *name* entry uniquely identifies the given argument. It can be of any
 100 alpha-numerical characters and dash(-). For example to provide the http port of
 101 an service, the parameter could be:
 102
 103     parameters:
 104       \- **name: service-port**
 105
 106 description
 107 ~~~~~~~~~~~
 108 *description* entry allows to provide the details of the parameter. Its
 109 supported in similar approach with command *description* defined in above
 110 section. For example service-port could be described as:
 111
 112     parameters:
 113       \- name: service-port
 114
 115       **description: Service HTTP port.**
 116
 117 is_optional
 118 ~~~~~~~~~~~
 119 *is_optional* entry allows to set the parameter is mandatory or not. By default,
 120 this entry is false. For example service-port could be made as as optional:
 121
 122     parameters:
 123       \- name: service-port
 124
 125       description: Service HTTP port.
 126
 127       **is_optional: true**
 128
 129 is_secured
 130 ~~~~~~~~~~~
 131 *is_secured* entry allows to set the parameter is secured or not. By default,
 132 this entry is false. This is very useful for password kind of parameters.
 133
 134 For example service-port could be made as in-secured:
 135
 136     parameters:
 137       \- name: service-port
 138
 139       description: Service HTTP port.
 140
 141       is_optional: true
 142
 143       **is_secured: false**
 144
 145 default_value
 146 ~~~~~~~~~~~~~
 147 *default_value* entry helps to provide the default value for the given parameter
 148 when that parameter is not provided during command execution.
 149
 150 Based on the *type* of parameter, default values are assigned as:
 151
 152 +---------------+------------------------------------------------------------+
 153 |       Type    |              Default value                                 |
 154 +===============+============================================================+
 155 | bool          | false                                                      |
 156 +---------------+------------------------------------------------------------+
 157 | uuid          | Auto-generated uuid-4 string                               |
 158 +---------------+------------------------------------------------------------+
 159 | string        | Blank. Also it can be set default values from the system   |
 160 |               | environment variable by mentioning it in the form of :     |
 161 |               |                                                            |
 162 |               | parameters:                                                |
 163 |               |     - default_value: ${ENV-VARIABLE-NAME}                  |
 164 +---------------+------------------------------------------------------------+
 165
 166 For example to provide the http port of an service, the parameter could be:
 167
 168     parameters:
 169       \- name: service-port
 170
 171       description: Service HTTP port.
 172
 173       is_optional: true
 174
 175       is_secured: false
 176
 177       **default_value: 8080**
 178
 179
 180 type
 181 ~~~~
 182 *type* entry allows to set the type of parameter such as boolean, integer, etc.
 183 For example to provide the http port of an service, the parameter type could be:
 184
 185     parameters:
 186       \- name: service-port
 187
 188       description: Service HTTP port.
 189
 190       is_optional: true
 191
 192       is_secured: false
 193
 194       default_value: 8080
 195
 196       **type: long**
 197
 198 Platform supports following types of parameter:
 199
 200 string
 201 ^^^^^^
 202 Any parameter value having a work or a line, string type is appropriate one. By
 203 default it is set to blank.
 204
 205 digit
 206 ^^^^^^
 207 Any parameter value having digit such as integers or floating values. For this
 208 type of parameter, platform does not set any default value. so while writing
 209 the parameter schematics, author should set the *default_value* if needed.
 210
 211 json
 212 ^^^^
 213 To set the value of parameter as JSON. Platform allows to input the JSON values
 214 either as direct one line string for simple json or complete file path for
 215 providing the complex json value. While user execute the command, based on the
 216 value of the JSON parameter, it could given as string or file path.
 217
 218 File path could start in the form of file://, http://, ftp://.
 219
 220 text
 221 ^^^^
 222 To set the value of parameter as text. Platform allows to input the text values
 223 either as direct one line string for simple text or complete file path for
 224 providing the complex text value. While user execute the command, based on the
 225 value of the text parameter, it could given as string or file path.
 226
 227 File path could start in the form of file://, http://, ftp://.
 228
 229 yaml
 230 ^^^^
 231 To set the value of parameter as yaml content. Platform allows to input the
 232 yaml values as complete file path. While user execute the command, YAML file
 233 needs to be created and provided that file's complete path as input value.
 234
 235 File path could start in the form of file://, http://, ftp://.
 236
 237 bool
 238 ^^^^
 239 This type allows to set the parameter value to either true or false. By
 240 default, its value is false, So, when user wants to input the boolean parameter
 241 its sufficient to mention the parameter option with out mentioning 'true'.
 242 For example, assume that command named 'login' defines the boolean input
 243 parameter 'is_secure_connection' to set the service connection is secured or
 244 not. For this command, while user input the value for parameter
 245 'is_secure_connection', it is sufficient to mention the parameter without
 246 passing value. Both of the following command will have same effect:
 247
 248     login --is_secure_connection
 249
 250     login --is_secure_connection true
 251
 252 uuid
 253 ^^^^
 254 *uuid* type allows to make the parameter value as UUID. By default platform auto
 255 generates uuid-4 formated string.
 256
 257 url
 258 ^^^
 259 *url* type allows to make the parameter value of URL/URI. Platform does not
 260 provide any default value for this type. so Author should provide the
 261 *default_value*, if needed during the template is created.
 262
 263 binary
 264 ^^^^^^
 265 *binary* type is very useful to pass the parameter as binary file and user
 266 should pass the complete path of the file.
 267
 268 array
 269 ^^^^^^
 270 To provide the same parameter multiple times array type helps. For example, when
 271 the command 'rm' is used, multiple file paths could be provided to remove all of
 272 them. In this kind of scenarios, array type supports and each parameter type
 273 is *string*
 274
 275 map
 276 ^^^^
 277 This is similar to *array* type and only differs the way the values are passed.
 278 In this type, values should be in the form of
 279 '<parameter-name>=<parameter-value>'
 280
 281
 282 Optional and Positional parameters
 283 ----------------------------------
 284 The input arguments for a given command usually provided with prefixing options
 285 names or directly giving the value. Earlier case is called optional arguments
 286 and later is called as positional arguments. OCLIP platform supports both the
 287 type.
 288
 289 For optional arguments, two type of options are supported:
 290
 291 *short option*: option name is usually single character and when user input
 292 the corresponding parameter, who will prefix with single dash(-).
 293
 294 *long option*: option name is usually more than one characters and when user
 295 input the corresponding parameter, who will prefix with double dash(-).
 296
 297 For example, the service port could be defined as :
 298
 299     parameters:
 300       \ - name: service-port
 301
 302       description: Service HTTP port.
 303
 304       is_optional: true
 305
 306       is_secured: false
 307
 308       default_value: 8080
 309
 310       type: long
 311
 312       **short_option: p**
 313
 314       **long_option:  service-port**
 315
 316 When user inputs the service port, it could either of following formats
 317
 318     --service-port 8080
 319
 320     -p 8080
 321
 322 For postional arguments, author should not define both *short_option* and
 323 *long_option* and when OCLIP process this template, it will consider as
 324 positional arguments. There could be more than one positional arguments could
 325 be defined for a command, and OCLIP treats the sequence of the positional
 326 parameters defined under *parameters* section is consider as it's position. For
 327 example, consider the below example:
 328
 329     parameters:
 330         \- name: param1
 331
 332         short_option: p1
 333
 334         long_option: param1
 335
 336         \- name: param2
 337
 338         \- name: param3
 339
 340         short_option: p3
 341
 342         long_option: param3
 343
 344         \- name: param4
 345
 346         \- name: param5
 347
 348         short_option: p5
 349
 350         long_option: param5
 351
 352 In this case, param2 and param4 are positional arguments as they are defined
 353 with out short and long options. so position of param2 is 1, for param4, it's 2.
 354 When user inputs the value as :
 355
 356     --param1 v1 -p3 v3 v2 -p5 v5 v4
 357
 358 OCLIP platform identifies the positions in sequence. so for param2, value v2
 359 will be assigned and for param4, value v4 will be assigned.
 360
 361 *NOTE*: User should only concern on the sequence of positional arguments while
 362 giving the values and no need to worry about the position at which value should
 363 be provided. so all of below sequence will yield the same result.
 364
 365     --param1 v1 -p3 v3 **v2** -p5 v5 **v4**
 366
 367     **v2** --param1 v1 **v4** -p5 v5 -p3 v3
 368
 369     --param1 v1 -p3 -p5 v5 v3 **v2** **v4**
 370
 371 default_parameters
 372 ------------------
 373 OCLIP platform provides following default parameters for every command and
 374 author is allowed to customize the inclusion or exclusion of these input
 375 parameters for a given command.
 376
 377 name: host-username
 378 ~~~~~~~~~~~~~~~~~~~
 379
 380     type: string
 381
 382     description: Host user name
 383
 384     short_option: u
 385
 386     long_option: host-username
 387
 388     default_value: ${OPEN_CLI_HOST_USERNAME}
 389
 390     is_optional: false
 391
 392 name: host-password
 393 ~~~~~~~~~~~~~~~~~~~
 394
 395     type: string
 396
 397     description: Host user password
 398
 399     short_option: p
 400
 401     long_option: host-password
 402
 403     default_value: ${OPEN_CLI_HOST_PASSWORD}
 404
 405     is_secured: true
 406
 407     is_optional: false
 408
 409 name: host-url
 410 ~~~~~~~~~~~~~~
 411     type: url
 412
 413     description: Host url
 414
 415     short_option: m
 416
 417     long_option: host-url
 418
 419     is_optional: false
 420
 421     default_value: ${OPEN_CLI_HOST_URL}
 422
 423 name: help
 424 ~~~~~~~~~~
 425     type: string
 426
 427     description: Command help message
 428
 429     short_option: h
 430
 431     long_option: help
 432
 433     default_value: false
 434
 435 name: version
 436 ~~~~~~~~~~~~~
 437     type: string
 438
 439     description: Command service version
 440
 441     short_option: v
 442
 443     long_option: version
 444
 445     default_value: false
 446
 447 name: debug
 448 ~~~~~~~~~~~
 449     type: bool
 450
 451     description: Enable debug output
 452
 453     short_option: d
 454
 455     long_option: debug
 456
 457     default_value: false
 458
 459 name: format
 460 ~~~~~~~~~~~~
 461     type: string
 462
 463     description: Output formats, supported formats such as table, csv, json,
 464     yaml
 465
 466     short_option: f
 467
 468     long_option: format
 469
 470     default_value: table
 471
 472 name: long
 473 ~~~~~~~~~~~
 474     type: bool
 475
 476     description: whether to print all attributes or only short attributes
 477
 478     short_option: s
 479
 480     long_option: long
 481
 482     default_value: false
 483
 484 name: no-title
 485 ~~~~~~~~~~~~~~
 486     type: bool
 487
 488     description: whether to print title or not
 489
 490     short_option: t
 491
 492     long_option: no-title
 493
 494     default_value: true
 495
 496 name: no-auth
 497 ~~~~~~~~~~~~~
 498     type: bool
 499
 500     description: whether to authenticate user or not
 501
 502     short_option: a
 503
 504     long_option: no-auth
 505
 506     default_value: false
 507
 508 *NOTE*: no-auth parameter is very helpful to by-pass the login and logout phase
 509 of each commands. Please refer *service* section to find more details on login
 510 and logout.
 511
 512 results
 513 -------
 514 Every command produces the output and *results* section helps to define the
 515 details of command outputs such as list of output attributes, the direction in
 516 which, result could be printed. More details are as follows.
 517
 518 direction
 519 ~~~~~~~~~
 520 *direction* entity allows to configure the direction in which the results to be
 521 printed. It can be:
 522
 523 * *portrait* : To print the results in two columns. First column is the name of
 524   the attribute and second column is the value of the attribute. It's more useful
 525   while command does operations like creation of resource, viewing of resources.
 526
 527 * *landscape* : To print the results row vise in landscape mode. It's more
 528   useful while command does operations like listing of resource.
 529
 530 attributes
 531 ~~~~~~~~~~
 532 name
 533 ^^^^
 534 *name* entry uniquely identifies the given attribute. It can be of any
 535 alpha-numerical characters and dash(-). For example to print the status of an
 536 service, the attribute could be:
 537
 538     attributes:
 539       \- **name: service-status**
 540
 541 description
 542 ^^^^^^^^^^^
 543 *description* entry allows to provide the details of the attribute. It's
 544 supported in similar approach with command *description* defined in above
 545 section. For example service-status could be described as:
 546
 547     attributes:
 548       \- name: service-status
 549
 550         **description: Service current status.**
 551
 552 type
 553 ^^^^
 554 *type* entry allows to set the type of attribute such as string, digit, etc.
 555 Similar to the parameter's type. currently it supports only string type.
 556
 557 For example, service-status could be:
 558
 559  attributes:
 560
 561  \- name: service-status
 562
 563  description: Service current status.
 564
 565  **type: string**
 566
 567 scope
 568 ^^^^^
 569 When a given command produces many results, most of the time no need to print
 570 all the attributes. SO OCLIP platform provides this *scope* entry to configure
 571 the attribute is printed by default or user should request to print it. So
 572 there are two scopes:
 573
 574 * *short* : attribute configured with this option will always printed by default
 575
 576 * *long* : attribute configured with this option will get printed only when
 577   user inputs the default parameter *long*, defined in *default_parameters*
 578   section. So to print all attributes of a command, user will input parameter:
 579
 580     --long
 581
 582 A sample attribute for service-status could be:
 583
 584   attributes:
 585       \- name: service-status
 586
 587       description: Service current status.
 588
 589       type: string
 590
 591       **scope: short**
 592
 593 default_value
 594 ^^^^^^^^^^^^^
 595 In some scenarios, author can set the default value to attribute which OCLIP assigns,
 596 when the value for that attribute is not available from back-end service in product.
 597
 598
 599 http
 600 ----
 601 OCLIP is enhanced to support REST API based products and *http* section is
 602 provided to capture all required details for performing http operation for the
 603 given command.
 604
 605 service
 606 -------
 607 Whether its information technology(IT) domain or communication technology(CT)
 608 domain, every software product is made of one or more service components. For
 609 example, onap has different components like aai, msb, etc and these components
 610 provides different kind of resources/features and functionalities.
 611
 612 *service* entry allows to mention the details of the given software product's
 613 service. This is an section and is having entries defined in below sections.
 614
 615 name
 616 ~~~~
 617 *name* entry allows to configure the service name. For example, to configure
 618 service component 'aai' in onap-amsterdam product,
 619
 620     service:
 621         name: aai
 622
 623 *CAUTION*: This entry is very signification to discover this service from the
 624 service catalog and name should be matching with the service name registered
 625 in the catalog.
 626
 627 version
 628 ~~~~~~~
 629 *version* entry allows to mention the particular version of service for which
 630 command is implemented. For example, the service 'aai' in the product
 631 'onap-amsterdam' having versions like v11.
 632
 633     service:
 634         version: v11
 635
 636 *CAUTION*: This entry is very signification to discover this service from the
 637 service catalog and version should be matching with the service version
 638 registered in the catalog.
 639
 640 mode
 641 ~~~~
 642 Some software product provides catalog service , where all service of that
 643 product could be discovered. While other product does not. OCLIP provides
 644 support for both kind of these products to implement commands and *mode*
 645 entry allows to configure this mode of operation.
 646
 647 CLIP supports in two different mode.
 648
 649 In *catalog* mode, OCLIP will discover the service details based on given
 650 *name* and *version* from the configured *host-url* parameter. For example,
 651 the product 'onap-amsterdam' provides the service 'msb' as the catalog service where
 652 all other services will get registered. so OCLIP can discover the given
 653 service such as 'aai' from the catalog service 'msb'. In this mode, *host-url*
 654 will be configured with the *msb* service url. In this case:
 655
 656     service:
 657         mode: catalog
 658
 659 *NOTE*: To see the details of *host-url*, refer the section default_parameters
 660
 661 In *direct* mode, OCLIP will not perform the discovery operation and consider
 662 the given *host-url* as the direct service url. In this case:
 663
 664     service:
 665         mode: direct
 666
 667 *NOTE*: To see the details of *host-url*, refer the section default_parameters
 668
 669 --------------------
 670
 671 auth
 672 ~~~~
 673 There are different kind of authentication and authorization approach exist and
 674 for OCLIP provides support for following approaches. Based on the approach
 675 configured in the template, OCLIP will login before executing the command and
 676 logout afterwards.
 677
 678 none
 679 ^^^^^
 680 In this approach, no login and logout will be performed. This is useful during
 681 the development cycle, as well as some services are available in public
 682 without authentication of user. In this approach, OCLIP ignores the given
 683 *host-username* and *host-password*. So the none auth is defined by:
 684
 685     service:
 686         auth: none
 687
 688 *NOTE*: To see the details of *host-username* and *host-password*, refer the
 689 section default_parameters
 690
 691
 692 basic
 693 ^^^^^
 694 This is HTTP basic authentication approach and given *host-username* and
 695 *host-password* values are used to find the hash and use it as Authentication
 696 value. So the none auth is defined by:
 697
 698     service:
 699         auth: basic
 700
 701 *NOTE*: To see the details of *host-username* and *host-password*, refer the
 702 section default_parameters
 703
 704 --------------------
 705 request
 706 ~~~~~~~
 707 *request* section captures all HTTP request information as:
 708
 709 uri
 710 ^^^
 711 *uri* entry allows to mention the REST API URI. Based on the *service mode*,
 712 this entry will vary. * when the mode is 'direct', it should be configured with
 713 out *host-url* portion in it. For example, if the REST API is
 714 '<host-url>/v1/service1/resource1, in which
 715
 716 * /v1/service1 - base path
 717 * /resource1 - service resource path.
 718
 719 then this entry will be:
 720
 721     request:
 722         uri: /v1/service1/resource1
 723
 724 when the mode is 'catalog', OCLIP will discover the  base path from the
 725 'catalog' service, so this entry need to be configured only with resource path
 726 as:
 727
 728     request:
 729         uri: /resource1
 730
 731 method
 732 ^^^^^^
 733 *method* entry allows to configure the HTTP methods GET, PUT, POST, DELETE,
 734 etc. For example, to get the resource1:
 735
 736     request:
 737         uri: /resource1
 738
 739         method: GET
 740
 741 body
 742 ^^^^
 743 *body* entry allows to mention the request body in json format, by default.
 744 And OCLIP adds 'application/json' header in the HTTP request. Otherwise, body
 745 could have complete path to binary file, in case request body is binary and
 746 *multipart_entity_name* should be configured with entity name provided by REST
 747 API.
 748
 749 headers
 750 ^^^^^^^
 751 *headers* entry allows to add REST API specific headers. By default OCLIP adds
 752 'application/json' as content-type and accept, also it will adds authentication
 753 headers such as 'Authentication' in case *auth* is of type 'basic'.
 754
 755 For example, to add the sample header :
 756
 757     request:
 758         uri: /resource1
 759
 760         method: GET
 761
 762         headers:
 763             header1: value1
 764
 765             header2: value2
 766
 767 queries
 768 ^^^^^^^
 769 *queries* entry allows to add REST API specific queries. For example, to add
 770 the sample queries :
 771
 772     request:
 773         uri: /resource1
 774
 775         method: GET
 776
 777         queries:
 778             q1: value1
 779
 780             q2: value2
 781
 782
 783 context
 784 ^^^^^^^
 785 *context* entry allows to customize the HTTP request and response processing.
 786
 787 Following are the supported customization parameters:
 788
 789 *remove_empty_node* : By default, OCLIP does not remove the empty json entries
 790   in request body. Otherwise set this entry to true as below.
 791
 792     request:
 793
 794         context:
 795             remove_empty_node: true
 796
 797 success_codes
 798 ~~~~~~~~~~~~~
 799 Every REST API has set of success codes and OCLIP will treat the HTTP request
 800 made based on the value configured in these http sections, only if
 801 *success_codes* contains the HTTP response status code.
 802
 803 result_map
 804 ~~~~~~~~~~
 805 This section allows to configure the require 'jpath' expression to retrieve the
 806 values from the HTTP response body.
 807
 808 *NOTE*: Currently only http response body is supported only with json type.
 809
 810 For example, if a http response '{"service_status": "green"} then to retrieve
 811 the service status and assign to result *attribute* service_status as :
 812
 813     result_map:
 814         service_status: $b{$.service_status}
 815
 816 Here, $b is detailed in section 'macros' of this document. and
 817 '$.service_status' is jpath expression.
 818
 819 macros
 820 -------
 821 OCLIP platform provides various marcos to fill *http* entries with the value
 822 of *parameters*, *headers* , etc Every macro is in the form of <macro name>
 823 followed by {<macro details>}Followings are the supported macros:
 824
 825 +------------------+------------------------------------------------------------+
 826 |       Macro      |               Definitions                                  |
 827 +==================+============================================================+
 828 | ${param-name}    | To retrieve the value from parameter named 'param-name'    |
 829 +------------------+------------------------------------------------------------+
 830 | $s{env:env-name} | To retrieve the value from environment variable 'env-name' |
 831 +------------------+------------------------------------------------------------+
 832 | $s{uuid}         | To set the value in uuid4 format                           |
 833 +------------------+------------------------------------------------------------+
 834 | $h{header-name}  | To retrieve the value from header named 'header-name'      |
 835 +------------------+------------------------------------------------------------+
 836 | $q{query-name}   | To retrieve the value from query named 'query-name'        |
 837 +------------------+------------------------------------------------------------+
 838 | $b{jpath}        | To retrieve the value from response body using the 'jpath' |
 839 |                  | expression.                                                |
 840 +------------------+------------------------------------------------------------+
 841
 842 samples
 843 -------
 844
 845 OCLIP provides way to setup and verify the OCS yaml by using the open_cli_sample_version 1.0 specification,
 846 which provides options to capture the samples and expected out for the given moco environment.