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

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