appc-provider/appc-provider-model/src/main/yang/appc-provider.yang

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  * APPC
   4  * ================================================================================
   5  * Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.
   6  * Copyright (C) 2017 Amdocs
   7  * ================================================================================
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  * ============LICENSE_END=========================================================
  20  * ECOMP is a trademark and service mark of AT&T Intellectual Property.
  21  */
  22
  23 /*
  24  * Yang model for the Application Controller (APP-C) component of ECOMP
  25  *
  26  * This model is used to define the data and services of the Application Controller
  27  * component of ECOMP.  The APP-C controller initiates the processing of directed
  28  * graphs, which define the actual process implementations used.  The name of the
  29  * directed graph is set by properties and cannot be changed dynamically.
  30  *
  31  * The services exposed by this provider are:
  32  *
  33  * restart-vnf:
  34  *    Used to request a restart of a virtual network function (a VM).
  35  *
  36  * rebuild-vnf:
  37  *    Used to request a rebuild of a virtual network function (a VM).
  38  *
  39  */
  40
  41 module appc-provider {
  42
  43     yang-version 1;
  44     namespace "org:openecomp:appc";
  45     prefix appc-provider;
  46     organization "Copyright 2017 AT&T Intellectual Property.";
  47
  48     description
  49       "Defines the services and request/response requirements for the ECOMP APP-C component.";
  50
  51     /*
  52      * Note, the revision changes the package name of the generated java code.  Do not
  53      * change the revision unless you also update all references to the bindings.
  54      */
  55     revision "2016-01-04" {
  56       description
  57         "APP-C interface version 1.0.48";
  58     }
  59
  60     /**********************************************************************************
  61      * Data type definitions
  62      *
  63      * The following data type definitions are used to define common data structures,
  64      * define constraints, or to impart special meanings to data objects related to the
  65      * APP-C controller functions.
  66      **********************************************************************************/
  67
  68     /*
  69      * Define a common definition of a UUID
  70      */
  71     typedef UUID {
  72         type string {
  73             length "1..255";
  74         }
  75         description "Universally Unique ID";
  76     }
  77
  78     /*
  79      * Define the name of the provider region/LCP to connect to
  80      */
  81     typedef LCP {
  82         type string {
  83             length "1..255";
  84         }
  85         description "The local control plane name (OpenStack region name) of the provider";
  86     }
  87
  88     /*
  89      * Define a common definition of a time stamp (expressed as a formatted string) as follows
  90      *
  91      * yyyy-MM-dd HH:mm:ss.SSSSSSSS
  92      *
  93      * yyyy ...... exactly 4 digit year, e.g., 2015
  94      * MM ........ 1 or 2 digit month of year, e.g., 7
  95      * dd ........ 1 or 2 digit day of month, e.g., 29
  96      * HH ........ 1 or 2 digit hour of day (24-hour clock) in UTC, e.g., 17
  97      * mm ........ 1 or 2 digit minute of the hour, e.g. 31
  98      * ss ........ 1 or 2 digit seconds of the minute, e.g., 28
  99      * SSSSSS .... 1-6 digit microseconds
 100      */
 101     typedef TIMESTAMP {
 102         type string {
 103             length "16..28";
 104             pattern "[0-9]{4}-[0-9]{1,2}-[0-9]{1,2} [0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2}.[0-9]{1,6}";
 105         }
 106     }
 107
 108     typedef ZULU {
 109         type string {
 110             length "16..28";
 111             pattern "[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}T[0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2}.[0-9]{1,6}Z";
 112         }
 113     }
 114
 115     typedef payload {
 116            type string ;
 117            description "The payload can be any valid JSON string value. Json escape characters need to be added when required to include an inner json within the payload to make it a valid json string value";
 118     }
 119
 120     typedef action {
 121          type enumeration {
 122              enum "Restart";
 123              enum "Rebuild";
 124              enum "Migrate";
 125              enum "Evacuate";
 126              enum "Snapshot";
 127              enum "ModifyConfig";
 128          }
 129          description "The action to be taken by APP-C, e.g. Test, Start, Terminate";
 130     }
 131
 132     /**********************************************************************************
 133      * All requests will include this standard header
 134      *
 135      * The standard request header is used to define a correlation identification for
 136      * the request that is returned on all responses.  This correlation identifier
 137      * (called the service-request-id) is meaningful to the caller and is included on
 138      * all responses from the services.
 139      **********************************************************************************/
 140     grouping common-request-header {
 141         description "A common header for all requests";
 142         container common-request-header {
 143             leaf service-request-id {
 144                 description "An identifier meaningful to the caller to correlate all responses";
 145                 type string;
 146                 mandatory true;
 147             }
 148
 149             leaf time-to-live {
 150                 description "The alloted time to perform the operation, in seconds.  If the
 151                     operation cannot be completed in this amount of time, the operation is
 152                     aborted.  If set to zero, no timeout exists and the operation will continue
 153                     until it completes or fails.  If omitted, the default value of 0 is used.";
 154                 type uint32 {
 155                     range "0..86400";
 156                 }
 157                 mandatory false;
 158             }
 159         }
 160     }
 161
 162     /**********************************************************************************
 163      * Basic manipulation of a VNF (or VM) will typically include querying the current
 164      * state, restarting, rebuilding, stopping, starting, etc.  In all of these basic
 165      * "state"-type operations, the services require the identification of the VNF to
 166      * be operated on, and the region or LCP that contains that resource.  This
 167      * information is used across all of these services, so it has been defined as a
 168      * common structure here and is referenced in the appropriate RPC definitions.
 169      **********************************************************************************/
 170     grouping vnf-resource {
 171         description "The data that uniquely identifies a virtual network function (or vm)";
 172         container vnf-resource {
 173             leaf vm-id {
 174                 description "The UUID of the resource.  For backwards compatibility, this can be
 175                     the self-link URL of the VM.";
 176                 type UUID;
 177                 mandatory true;
 178             }
 179             leaf identity-url {
 180                 description "The identity url used to access the resource";
 181                 type UUID;
 182                 mandatory false;
 183             }
 184             leaf tenant-id {
 185                 description "The id of the provider tenant that owns the resource";
 186                 type string;
 187                 mandatory false;
 188             }
 189         }
 190     }
 191
 192     /**********************************************************************************
 193      * All responses will include this standard header
 194      *
 195      * The standard response header includes the time of completion as well as a
 196      * success|failure indication
 197      **********************************************************************************/
 198     grouping common-response-header {
 199         description "A common header for all responses defining success or failure
 200             and the time stamp when completed";
 201         container common-response-header {
 202             leaf service-request-id {
 203                 description "An identifier meaningful to the caller to correlate all responses";
 204                 type string;
 205             }
 206             leaf success {
 207                 description "True indicates the request was successful";
 208                 type boolean;
 209             }
 210             leaf reason {
 211                 description "If success=false, the failure reason.  Otherwise, undefined.";
 212                 type string;
 213             }
 214             leaf completed {
 215                 description "The formatted time stamp when the operation was completed.";
 216                 type TIMESTAMP;
 217             }
 218             leaf duration {
 219                 description "The amount of time used (in seconds) to process the request";
 220                 type uint32;
 221             }
 222         }
 223     }
 224
 225
 226        /**********************************************************************************
 227          * All requests/response will include this standard header
 228          *
 229          * The standard common header is used to define a correlation identification for
 230          * the request that is returned on all responses.
 231          **********************************************************************************/
 232         grouping common-header {
 233             description "A common header for all APP-C requests";
 234             container common-header {
 235                 description "A common header for all APP-C requests";
 236                 leaf timestamp {
 237                     description "timestamp is in ISO 8601 timestamp format ZULU offset";
 238                     type ZULU;
 239                     mandatory true;
 240                 }
 241
 242                 leaf api-ver {
 243                     description "api-ver is the API version identifier. A given release of APPC should support all previous versions of APPC API (correlate with general requirements)";
 244                     type string;
 245                     mandatory true;
 246                 }
 247
 248                 leaf originator-id {
 249                     description "originator-id an identifier of the calling system which can be used addressing purposes, i.e. returning asynchronous response to the proper destination over DMaaP (especially in case of multiple consumers of APP-C APIs)";
 250                     type string;
 251                     mandatory true;
 252                 }
 253
 254                 leaf request-id {
 255                     description "UUID for the request ID. An OSS/BSS identifier for the request that caused the current action. Multiple API calls may be made with the same request-id \vThe request-id shall be recorded throughout the operations on a single request";
 256                     type string;
 257                     mandatory true;
 258                 }
 259
 260                 leaf sub-request-id {
 261                     description "Uniquely identifies a specific LCM action. It is persistent over the life-cycle of a single request";
 262                     type string;
 263                     mandatory false;
 264                 }
 265
 266
 267                 /**********************************************************************************
 268                  * Flags are generic flags that apply to any and all commands, all are optional
 269                  *  force = TRUE/FALSE - Execute command even if target is in unstable (i.e. locked, transiting, etc) state. Specific behaviour of forced commands varies, but implies cancellation of previous command and an override by the new command. The FALSE value is used by default.
 270                  *  ttl = <0....N> - The timeout value for command execution, expressed in seconds
 271                  *  mode = EXCLUSIVE/NORMAL - defines execution mode as follows:
 272                  *        - EXCLUSIVE ? on encountering an exclusive command, the APP-C will:
 273                  *          * Cease accepting additional command requests
 274                  *          * Complete execution of outstanding commands
 275                  *          * Execute the exclusive command to completion
 276                  *          * Optionally report the result of the command
 277                  *          * Optionally resume command acceptance and processing
 278                  *        - NORMAL - Obverse of EXCLUSIVE, the default one.
 279                  **********************************************************************************/
 280                 container flags {
 281                     description "Flags are generic flags that apply to any and all commands, all are optional";
 282                     leaf mode {
 283                         type enumeration {
 284                                          enum "EXCLUSIVE";
 285                                          enum "NORMAL";
 286                                      }
 287                         description "EXCLUSIVE (accept no queued requests on this VNF while processing) or NORMAL (queue other requests until complete)";
 288                         mandatory false;
 289                     }
 290                     leaf force {
 291                         type enumeration {
 292                                     enum "TRUE";
 293                                     enum "FALSE";
 294                                }
 295                         description "TRUE/FALSE - Execute action even if target is in unstable (i.e. locked, transiting, etc.) state";
 296                         mandatory false;
 297                     }
 298                     leaf ttl {
 299                         description "<0....N> -Â The timeout value (expressed in seconds) for action execution, between action being received by APPC and action initiation";
 300                         type uint16;
 301                         mandatory false;
 302                     }
 303                 }
 304             }
 305         }
 306
 307         grouping config-payload {
 308             description "Payload for modify config on traffic generator";
 309             container config-payload {
 310                 description "Payload for modify config on traffic generator";
 311                 leaf config-url {
 312                     description "this is the restconf interface for  vTrafficGenerator";
 313                     type string;
 314                     mandatory true;
 315                 }
 316
 317                 leaf config-json {
 318                     description "this is the configuration data";
 319                     type string;
 320                     mandatory true;
 321                 }
 322             }
 323         }
 324
 325
 326      grouping action-identifiers {
 327             description "A block containing the action arguments. These are used to specify the object upon which APP-C LCM command is to operate";
 328             container action-identifiers {
 329                 description "A block containing the action arguments. These are used to specify the object upon which APP-C LCM command is to operate";
 330                 leaf service-instance-id {
 331                     description "identifies a specific service the command refers to. When multiple APP-C instances are used and applied to a subset of services, this will become significant . The field is mandatory when the vnf-id is empty";
 332                     type string;
 333                     mandatory false;
 334                 }
 335                 leaf vnf-id {
 336                     description "identifies the VNF to which this action is to be applied(vnf-id uniquely identifies the service-instance referred to).  Note that some actions  are applied to multiple VNFs in the same service. When this is the case, vnf-id may be left out, but service-instance-id must appear. The field is mandatory when service-instance-id is empty";
 337                     type string;
 338                     mandatory false;
 339                 }
 340                 leaf vnfc-name {
 341                     description "identifies the VNFC to which this action is to be applied. Some actions apply only to a component within a VNF (e.g. RESTART is sometimes applied to on VM only).  In such a case, the name of the VNFC is used to search for the component within the VNF";
 342                     type string;
 343                     mandatory false;
 344                 }
 345                 leaf vserver-id {
 346                     description "identifies a specific VM within the given service/vnf to which this action is to be applied";
 347                     type string;
 348                     mandatory false;
 349                 }
 350             }
 351         }
 352
 353      grouping status {
 354             description "The specific response codes are to be aligned with ASDC reference doc (main table removed to avoid duplication and digression from main table). See ASDC and ECOMP Distribution Consumer Interface Agreement";
 355             container status {
 356                 description "The specific response codes are to be aligned with ASDC reference doc (main table removed to avoid duplication and digression from main table). See ASDC and ECOMP Distribution Consumer Interface Agreement";
 357                 leaf code {
 358                     description "Response code";
 359                     type uint16;
 360                     mandatory true;
 361                 }
 362                 leaf message {
 363                     description "Response message";
 364                     type string;
 365                     mandatory true;
 366                 }
 367             }
 368       }
 369
 370
 371       /**********************************************************************************
 372      * NEW API ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 373      * All requests will include this standard header
 374      *
 375      * The standard request header is used to define a correlation identification for
 376      * the request that is returned on all responses.  This correlation identifier
 377      * (called the service-request-id) is meaningful to the caller and is included on
 378      * all responses from the services.
 379      **********************************************************************************/
 380     grouping RequestHeader {
 381         container RequestHeader {
 382             description "A common header for all APP-C requests";
 383             leaf TimeStamp {
 384                 description "TimeStamp is in ISO 8601 timestamp format ZULU offset";
 385                 type TIMESTAMP;
 386                 mandatory true;
 387             }
 388
 389             leaf APIver {
 390                 description "APIver is the API version identifier. A given release of APPC should support all previous versions of APPC API (correlate with general requirements)";
 391                 type string;
 392                 mandatory true;
 393             }
 394
 395             leaf OriginatorID {
 396                 description "OriginatorID an identifier of the calling system which can be used addressing purposes, i.e. returning asynchronous response to the proper destination over DMaaP (especially in case of multiple consumers of APP-C APIs)";
 397                 type string;
 398                 mandatory true;
 399             }
 400
 401             leaf TransactionID {
 402                 description "Identifiers that may be generated when multiple responses or handling passes are needed for a given request, allowing the request itself to be tracked";
 403                 type string;
 404                 mandatory true;
 405             }
 406
 407             leaf-list RequestTrack {
 408                 description "Identifiers that may be generated when multiple responses or handling passes are needed for a given request, allowing the request itself to be tracked";
 409                 type string;
 410             }
 411
 412             /**********************************************************************************
 413              * Flags are generic flags that apply to any and all commands, all are optional
 414              *  FORCE = TRUE/FALSE - Execute command even if target is in unstable (i.e. locked, transiting, etc) state. Specific behaviour of forced commands varies, but implies cancellation of previous command and an override by the new command. The FALSE value is used by default.
 415              *  TTL = <0....N> - The timeout value for command execution, expressed in seconds
 416              *  MODE = EXCLUSIVE/NORMAL - defines execution mode as follows:
 417              *        - EXCLUSIVE � on encountering an exclusive command, the APP-C will:
 418              *          * Cease accepting additional command requests
 419
 420              * Complete execution of outstanding commands
 421              *          * Execute the exclusive command to completion
 422              *          * Optionally report the result of the command
 423              *          * Optionally resume command acceptance and processing
 424              *        - NORMAL - Obverse of EXCLUSIVE, the default one.
 425              **********************************************************************************/
 426             container Flags {
 427                 description "Flags are generic flags that apply to any and all commands, all are optional";
 428                 leaf FORCE {
 429                     description "TRUE/FALSE - Execute action even if target is in unstable (i.e. locked, transiting, etc) state.";
 430                     type string;
 431                     mandatory false;
 432                 }
 433                 leaf TTL {
 434                     description "<0....N> - The timeout value for action execution, expressed in seconds";
 435                     type string;
 436                     mandatory false;
 437                 }
 438                 leaf MODE {
 439                     description "EXCLUSIVE/NORMAL - defines execution mode";
 440                     type string;
 441                     mandatory false;
 442                 }
 443             }
 444         }
 445     }
 446
 447     grouping RequestParameters {
 448         description "The request contains the entry of command-specific and is opaque to the APP-C handler";
 449         leaf Action {
 450             description "The actual action to be taken";
 451             type string;
 452             mandatory true;
 453         }
 454         leaf TargetID {
 455             description "The specific VF a component of which is to be affected";
 456             type string;
 457             mandatory true;
 458         }
 459         leaf ObjectID {
 460             description "The specific VFC within a VF to be affected";
 461             type string;
 462             mandatory true;
 463         }
 464         leaf Payload {
 465             description "An action-specific value opaque to the APPC handler.
 466                          The value can be any valid JSON type (primitive, object, collection of those two).
 467                          APPC will pass the value as raw JSON string to the executing LCM action.";
 468             type string;
 469             mandatory true;
 470         }
 471     }
 472
 473     grouping ResponseHeader {
 474         description "The response to an APP-C command or control is, likewise, encoded in a JSON object. ";
 475         container ResponseHeader {
 476             description "The response to an APP-C command or control is, likewise, encoded in a JSON object. ";
 477             leaf TimeStamp {
 478                 description "TimeStamp is in ISO 8601 timestamp format ZULU offset";
 479                 type TIMESTAMP;
 480                 mandatory true;
 481             }
 482
 483             leaf APIver {
 484                 description "APIver is the API version identifier. A given release of APPC should support all previous versions of APPC API (correlate with general requirements)";
 485                 type string;
 486                 mandatory true;
 487             }
 488
 489             leaf ResponseID {
 490                 description "ResponseID an identifier of the calling system which can be used addressing purposes, i.e. returning asynchronous response to the proper destination over DMaaP (especially in case of multiple consumers of APP-C APIs)";
 491                 type string;
 492                 mandatory true;
 493             }
 494
 495             leaf-list SubResponseID {
 496                 description "Identifiers that may be generated when multiple responses or handling passes are needed for a given request, allowing the request itself to be tracked";
 497                 type string;
 498             }
 499         }
 500     }
 501
 502     grouping ResponseAttributes {
 503         description "The response contains the status of executed functionality";
 504         container Status {
 505             description "The specific response codes are to be aligned with ASDC reference doc (main table removed to avoid duplication and digression from main table). See ASDC and ECOMP Distribution Consumer Interface Agreement";
 506             leaf Code {
 507                 description "Response code value";
 508                 type uint32;
 509                 mandatory true;
 510             }
 511             leaf Value {
 512                 description "Response code description";
 513                 type string;
 514                 mandatory true;
 515             }
 516         }
 517         leaf Payload {
 518             description "Payload - the entry is command-specific and is opaque to the APP-C handler.
 519                          The value can be any valid JSON type (primitive, object, collection of those two).
 520                          APP-C will pass the value as raw JSON string to appropriate addressee";
 521             type string;
 522             mandatory false;
 523         }
 524     }
 525
 526
 527
 528
 529     /**********************************************************************************
 530      * Define the restart service
 531      **********************************************************************************/
 532     rpc restart {
 533         description "An operation to restart a virtual network function (or VM)";
 534         input {
 535             uses common-request-header;
 536             uses vnf-resource;
 537         }
 538         output {
 539             uses common-response-header;
 540             leaf vm-id {
 541                 description "The UUID of the VM that was restarted";
 542                 type UUID;
 543             }
 544         }
 545     }
 546
 547     /**********************************************************************************
 548      * Define the rebuild service
 549      **********************************************************************************/
 550     rpc rebuild {
 551         description "An operation to rebuild a virtual network function (or VM)";
 552         input {
 553             uses common-request-header;
 554             uses vnf-resource;
 555         }
 556         output {
 557             uses common-response-header;
 558             leaf new-vm-id {
 559                 description "The UUID of the VM after rebuild.  If the UUID was changed,
 560                     this contains the new UUID.  If it was not changed, this contains
 561                     the original UUID";
 562                 type UUID;
 563             }
 564             leaf original-vm-id {
 565                 description "The UUID of the VM before rebuild (i.e., the original UUID)";
 566                 type UUID;
 567             }
 568         }
 569     }
 570
 571     /**********************************************************************************
 572      * Define the migrate service
 573      **********************************************************************************/
 574     rpc migrate {
 575         description "An operation to migrate a virtual network function (or VM)";
 576         input {
 577             uses common-request-header;
 578             uses vnf-resource;
 579         }
 580         output {
 581             uses common-response-header;
 582             leaf vm-id {
 583                 description "The UUID of the VM that was migrated.";
 584                 type UUID;
 585             }
 586         }
 587     }
 588
 589      /**********************************************************************************
 590      * Define the evacuate service
 591      **********************************************************************************/
 592     rpc evacuate {
 593         description "An operation to evacuate a virtual network function (or VM)";
 594         input {
 595             uses common-request-header;
 596             uses vnf-resource;
 597         }
 598         output {
 599             uses common-response-header;
 600             leaf vm-id {
 601                 description "The UUID of the VM that was evacuated";
 602                 type UUID;
 603             }
 604         }
 605     }
 606
 607
 608          /**********************************************************************************
 609      * Define the snapshot service
 610      **********************************************************************************/
 611     rpc snapshot {
 612         description "An operation to create a snapshot of a virtual network function (or VM)";
 613         input {
 614             uses common-request-header;
 615             uses vnf-resource;
 616         }
 617         output {
 618             uses common-response-header;
 619             leaf vm-id {
 620                 description "The UUID of the VM that was snapshot";
 621                 type UUID;
 622             }
 623         }
 624     }
 625
 626         rpc ModifyConfig {
 627         description "An operation to modify-config the configurations of a virtual network function (or VM)";
 628         input {
 629             uses common-request-header;
 630             uses config-payload;
 631             leaf action {
 632                        type action;
 633                        mandatory true;
 634             }
 635         }
 636         output {
 637             uses common-response-header;
 638         }
 639     }
 640
 641         rpc vmstatuscheck {
 642             description "An operation to check status of a VM";
 643             input {
 644                 uses common-request-header;
 645                 uses vnf-resource;
 646             }
 647             output {
 648                 uses common-response-header;
 649                 leaf stat-msg {
 650                     description "The status of the VM requested";
 651                     type string;
 652                 }
 653             }
 654         }
 655
 656 }