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

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