groupbasedpolicy/src/main/yang/model/policy.yang

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8
   9 module policy {
  10     yang-version 1;
  11
  12     namespace "urn:opendaylight:groupbasedpolicy:policy";
  13     prefix "gbp-policy";
  14
  15     import gbp-common {prefix gbp-common;}
  16     import ietf-inet-types {prefix inet;}
  17
  18     description
  19         "This module defines the group-based policy configuration
  20          model.";
  21
  22     revision "2014-04-21" {
  23         description
  24             "Initial revision.";
  25     }
  26
  27     // ***************
  28     // Label groupings
  29     // ***************
  30
  31     grouping label {
  32         description
  33             "Labels are used for matching contracts to endpoint groups
  34              through selectors and targets, as well as determining how
  35              those contracts will be applied.  See more detailed
  36              documentation for qualities, conditions, requirements,
  37              and capabilities.";
  38
  39         leaf description {
  40             description "A human-readable description for the label";
  41             type gbp-common:description;
  42         }
  43         leaf inclusion-rule {
  44             description "Specify how inheritance will work for this label";
  45             default include;
  46
  47             type enumeration {
  48                 enum include {
  49                     description
  50                         "This label will be included normally in the
  51                          matching.";
  52                 }
  53                 enum exclude {
  54                     description
  55                         "This label will be excluded from the
  56                          matching.  This allows removing labels that
  57                          would have otherwise been included because of
  58                          inheritence rules.";
  59                 }
  60             }
  61         }
  62     }
  63
  64     grouping quality-base {
  65         description "Base type for qualities and matcher qualities.";
  66         leaf name {
  67             description "A user-visible name for the quality";
  68             type gbp-common:quality-name;
  69             mandatory true;
  70         }
  71         uses label;
  72     }
  73
  74     grouping has-qualities {
  75         description "An object with a list of qualities";
  76         list quality {
  77             description
  78                 "A quality is a label which selects which selects the
  79                  contracts that are in scope.  Another name for
  80                  'quality' could be 'attribute' or 'characteristic.'
  81                  Qualities can be scoped to either a specific contract
  82                  or to a target within that contract.
  83
  84                  Contracts are matched to provider and consumer
  85                  endpoint groups based on the selectors in those
  86                  endpoint groups that match the quality.
  87
  88                  Qualities for a contract are inherited from the
  89                  enclosing contract.
  90
  91                  Qualities for a target with a given name are
  92                  inherited both from the enclosing parent contract and
  93                  from any targets with the same name within the
  94                  enclosing parent contract.";
  95
  96             key name;
  97             uses quality-base;
  98         }
  99     }
 100
 101     grouping requirement-base {
 102         description "Base type for requirements and matcher requirements.";
 103         leaf name {
 104             description "A user-visible name for the requirement";
 105             type gbp-common:requirement-name;
 106             mandatory true;
 107         }
 108         uses label;
 109     }
 110
 111     grouping has-requirements {
 112         list requirement {
 113             description
 114                 "A requirement is a label that, along with capabilities,
 115                  selects how contracts are applied by selecting the
 116                  applicable subjects within that contract.
 117                  Requirements represent the fact that an endpoint
 118                  group requires that some specific functionality be
 119                  provided to it in order to function.
 120
 121                  Requirements scoped to an endpoint group (as well as
 122                  any parent endpoint groups) are inherited by all of
 123                  that group's contract selectors.  Contract selectors
 124                  also inherit requirements from any contract selectors
 125                  in the parent groups that have with matching names.
 126
 127                  Note that requirements play no role in choosing which
 128                  contracts apply; they only affect how the contracts
 129                  that are chosen will be interpreted.";
 130
 131             key name;
 132             uses requirement-base;
 133         }
 134     }
 135
 136     grouping capability-base {
 137         description "Base type for capabilities and matcher capabilities.";
 138         leaf name {
 139             description "A user-visible name for the capability";
 140             type gbp-common:capability-name;
 141             mandatory true;
 142         }
 143         uses label;
 144     }
 145
 146     grouping has-capabilities {
 147         list capability {
 148             description
 149                 "A capability is a label that, along with requirements,
 150                  selects how contracts are applied by selecting the
 151                  applicable subjects within that contract.
 152                  Capabilities are specific pieces of functionality
 153                  that can be exposed to other endpoint groups that may
 154                  meet functional requirements of those endpoint
 155                  groups.
 156
 157                  Capabilities scoped to an endpoint group (as well as
 158                  any parent endpoint groups) are inherited by all of
 159                  that group's contract selectors.  Contract selectors
 160                  also inherit capabilities from any contract selectors
 161                  in the parent groups that have matching names.
 162
 163                  Note that capabilities play no role in choosing which
 164                  contracts apply; they only affect how the contracts
 165                  that are chosen will be interpreted.";
 166
 167             key "name";
 168             uses capability-base;
 169         }
 170     }
 171
 172     grouping has-conditions {
 173         list condition {
 174             description
 175                 "A condition is a state label for endpoints that can
 176                  change over time.  As conditions change for certain
 177                  endpoints, this can affect which subjects are in
 178                  scope as determined by how the clauses in the
 179                  contract match against the requirements and
 180                  capabilities for the endpoint group, and the
 181                  conditions for the endpoints.";
 182
 183             key "name";
 184             leaf name {
 185                 description "A user-visible name for the condition";
 186                 type gbp-common:condition-name;
 187                 mandatory true;
 188             }
 189             uses label;
 190         }
 191     }
 192
 193     grouping matcher {
 194         description
 195             "A matcher allows matching against labels.  This is used
 196              to both to match contracts to endpoint groups by matching
 197              on qualities, and then to match against subjects in the
 198              contract by matching on requirements, capabilities, and
 199              conditions.";
 200
 201         leaf match-type {
 202             description
 203                 "Specify how many of the labels must match.  If not
 204                  specified, defaults to 'all'.";
 205             type enumeration {
 206                 enum all {
 207                     description
 208                         "All specified labels must match.";
 209                 }
 210                 enum any {
 211                     description
 212                         "At least one of the specified labels must match.";
 213                 }
 214                 enum none {
 215                     description
 216                         "None of the specified labels can match.";
 217                 }
 218             }
 219         }
 220     }
 221
 222     grouping has-condition-matchers {
 223         description "Objects with condition matchers";
 224         list condition-matcher {
 225             description "Match against conditions on endpoints.";
 226
 227             key "name";
 228             leaf name {
 229                 description
 230                     "A name for the condition matcher";
 231                 type gbp-common:condition-matcher-name;
 232                 mandatory true;
 233             }
 234
 235             uses matcher;
 236             uses has-conditions;
 237         }
 238     }
 239
 240     // ************************
 241     // Network domains grouping
 242     // ************************
 243
 244     grouping network-domain {
 245         description
 246             "A base type for network domains.  Network domains
 247              represent some logical grouping or namespace of
 248              network addresses.";
 249         leaf name {
 250             description
 251                 "A human-readable name for the network domain.";
 252             type gbp-common:name;
 253         }
 254         leaf description {
 255             description
 256                 "A human-readable description for the context.";
 257             type gbp-common:description;
 258         }
 259     }
 260
 261     grouping forwarding-context {
 262         description "A base type for forwarding contexts.";
 263         uses network-domain;
 264     }
 265
 266     grouping l2-context {
 267         description
 268             "A base type for layer 2 contexts.  Layer 2 contexts
 269              represent a namespace or logical grouping of layer 2
 270              addresses.";
 271
 272         uses forwarding-context;
 273     }
 274
 275     // ************************
 276     // Endpoint group groupings
 277     // ************************
 278
 279     grouping relator {
 280         description
 281             "Relators allow contracts and endpoint groups to be related
 282              to each other through a matching process.  See target,
 283              selection-relator, target-selector, and named-selector
 284              for more information.";
 285     }
 286
 287     grouping selection-relator {
 288         description
 289             "Selection relators allow endpoint groups to select
 290              contracts based on their name or on their qualities.";
 291         uses relator;
 292
 293         leaf name {
 294             description "A name for the selector";
 295             type gbp-common:selector-name;
 296             mandatory true;
 297         }
 298     }
 299
 300     grouping consumer-selection-relator {
 301         description
 302             "A selection relator for matching contracts to meet
 303              endpoint group requirements.  See consumer-named-selector
 304              and consumer-target-selector for more details.";
 305         uses selection-relator;
 306         uses has-requirements;
 307     }
 308
 309     grouping provider-selection-relator {
 310         description
 311             "A selection relator for matching contracts to meet
 312              endpoint group requirements.  See provider-named-selector
 313              and provider-named-selector for more details.";
 314         uses selection-relator;
 315         uses has-capabilities;
 316     }
 317
 318     grouping named-selector {
 319         description
 320             "A named selector selects a contract based on the name of
 321              the contract.  Once the contract is selected, the
 322              requirements and capabilities are used to select specific
 323              subjects within that contract.  Named selectors are the
 324              simplest way to select a contract.  If you need a more
 325              advanced selector, see the target selector.
 326
 327              There are two kinds of named selector: consumer named
 328              selectors and provider named selectors.  Consumer named
 329              selectors select contracts to meet requirements for the
 330              endpoint group, and provider named selectors select
 331              contracts to provide capabilities for the endpoint group.";
 332
 333         leaf-list contract {
 334             description "Specific contracts to select.";
 335             type leafref {
 336                 path "/tenants/tenant/contract/id";
 337             }
 338         }
 339     }
 340
 341     grouping target-selector {
 342         description
 343             "Target selectors select contracts for the endpoint group.
 344              First, the quality matchers are used to select the
 345              contracts.  Then, the requirements and capabilities are
 346              used to select specific subjects within that contract.
 347              Target selectors are an advanced method for selecting
 348              contracts; for a simpler method, see the named selector.
 349
 350              There are two kinds of target selectors: consumer target
 351              selectors and provider target selectors.  Consumer target
 352              selectors select contracts to meet requirements for the
 353              endpoint group, and provider target selectors select
 354              contracts to provide capabilities to other endpoint
 355              groups.";
 356
 357         list quality-matcher {
 358             description
 359                 "A quality matcher is used in a target selector to
 360                  match against the qualities in a contract target.
 361                  You can specify a list of qualities to match against.
 362                  You can choose whether all qualities listed must
 363                  match or if a match can be made with any of the
 364                  qualities.";
 365
 366             key "name";
 367             leaf name {
 368                 description "A unique name for the quality matcher";
 369                 type gbp-common:quality-matcher-name;
 370                 mandatory true;
 371             }
 372
 373             uses matcher;
 374
 375             list matcher-quality {
 376                 description
 377                     "A matcher quality is a quality with a target name
 378                      field used in quality matchers.  The name of the
 379                      matcher quality matches against qualities in
 380                      contract targets.";
 381
 382                 key name;
 383                 uses quality-base;
 384
 385                 leaf target-namespace {
 386                     description
 387                         "The name of the target to match.  This allows
 388                          us to specify that we want to match only
 389                          qualities scoped to a particular target name.
 390
 391                          This parameter is optional; if not specified,
 392                          use an inherited target name if it exists, or
 393                          match against any target name.";
 394
 395                     type gbp-common:target-name;
 396                 }
 397             }
 398         }
 399     }
 400
 401     // ******************
 402     // Contract groupings
 403     // ******************
 404
 405     grouping has-direction {
 406         description "Object that have a directionality.";
 407         leaf direction {
 408             default bidirectional;
 409             type enumeration {
 410                 enum in {
 411                     description
 412                         "Applies to traffic into provider endpoint group";
 413                 }
 414                 enum out {
 415                     description
 416                         "Applies to traffic out of provider endpoint group";
 417                 }
 418                 enum bidirectional {
 419                     description
 420                         "Applies to traffic in both directions";
 421                 }
 422             }
 423         }
 424     }
 425
 426     grouping subject-feature-instance {
 427         description
 428             "Specific instances of subject features with
 429              parameters filled in.";
 430         list parameter-value {
 431             key "name";
 432             leaf name {
 433                 type gbp-common:parameter-name;
 434                 mandatory true;
 435             }
 436             leaf string-value {
 437                 type string;
 438             }
 439             leaf int-value {
 440                 type int64;
 441             }
 442         }
 443     }
 444
 445     grouping has-order {
 446         description "Objects containing an order parameter";
 447         leaf order {
 448             description
 449                 "Specify the ordering of an ordered list
 450                  of elements.";
 451             type int32 {
 452                 range "0..max";
 453             }
 454         }
 455     }
 456
 457     grouping has-classifier-refs {
 458         description "Objects containing lists of classifier references";
 459
 460         list classifier-ref {
 461             key "name";
 462             description
 463                 "A reference to classifier instance that is used to match
 464                  traffic traveling between the endpoint groups that
 465                  form the contract.";
 466
 467             leaf name {
 468                 description "A unique name for this classifier reference";
 469                 type gbp-common:classifier-name;
 470                 mandatory true;
 471             }
 472
 473             leaf instance-name {
 474                 description "The name of the classifier instance";
 475                 type leafref {
 476                     path "/tenants/tenant/subject-feature-instances/classifier-instance/name";
 477                 }
 478                 mandatory true;
 479             }
 480
 481             leaf connection-tracking {
 482                 description
 483                     "Set up connection tracking for this classifier,
 484                      which allows the traffic in the reverse direction
 485                      as connections are established.  This enables
 486                      rules that allow connections to be initiated only
 487                      from one side, but once initiated the two sides
 488                      can communicate for that connection.";
 489
 490                 default normal;
 491                 type enumeration {
 492                     enum normal {
 493                         description
 494                             "Match only traffic matching the classifier
 495                              strictly";
 496                     }
 497                     enum reflexive {
 498                         description
 499                             "Additionally match reverse traffic for
 500                              connections";
 501                     }
 502                 }
 503             }
 504
 505             uses has-direction;
 506         }
 507     }
 508
 509     grouping has-action-refs {
 510         description "Objects containing lists of action references";
 511
 512         list action-ref {
 513             description
 514                 "A reference to an action defined in the subject
 515                  feature instances for the tenant.";
 516
 517             leaf name {
 518                 description "The name of the action instance";
 519                 type leafref {
 520                     path "/tenants/tenant/subject-feature-instances/action-instance/name";
 521                 }
 522                 mandatory true;
 523             }
 524             uses has-order;
 525         }
 526     }
 527
 528     grouping subject-feature-definition {
 529         description
 530             "Base type for subject feature definitions.";
 531
 532         leaf description {
 533             description "A user-readable description";
 534             type gbp-common:description;
 535         }
 536
 537         list parameter {
 538             description
 539                 "A parameter for the feature that can be
 540                  passed in.";
 541             key "name";
 542             leaf name {
 543                 description "A user-visible name for the parameter";
 544                 type gbp-common:parameter-name;
 545                 mandatory true;
 546             }
 547             leaf description {
 548                 description
 549                     "A user-visible description of the meaning of
 550                      the parameter.";
 551                 type gbp-common:description;
 552             }
 553             leaf type {
 554                 description "The type of the parameter";
 555                 default string;
 556                 type enumeration {
 557                     enum string {
 558                         description "A string-valued parameter";
 559                     }
 560                     enum int {
 561                         description "An integer-valued parameter";
 562                     }
 563                 }
 564             }
 565             leaf is-required {
 566                 description "Specify whether the parameter is
 567                              required for correct operation.";
 568                 default optional;
 569                 type enumeration {
 570                     enum required {
 571                         description "The parameter is required";
 572                     }
 573                     enum optional {
 574                         description "The parameter is optional";
 575                     }
 576                 }
 577             }
 578         }
 579
 580         leaf fallback-behavior {
 581             description
 582                 "Set the behavior when the underlying infrastructure
 583                  is unable to support a particular feature.";
 584             type enumeration {
 585                 enum strict {
 586                     description
 587                         "A fatal exception MUST be raised which will
 588                          render the enclosing subject inactive.";
 589                 }
 590                 enum allow-fallback {
 591                     description
 592                         "The infrastructure MAY fall back to using
 593                          a parent definition of this feature, and
 594                          instread raise a nonfatal exception.";
 595                 }
 596             }
 597         }
 598     }
 599
 600     // ********************
 601     // Global Configuration
 602     // ********************
 603
 604     container subject-feature-definitions {
 605         description
 606             "Contains configuration for the set of actions and
 607              classifiers that can be defined for a subject.  This is
 608              be specific to the capabilities of the underlying
 609              infrastructure, so the policy model does not define the
 610              specific semantics.
 611
 612              The definitions here provide a generic parameterized base
 613              that can be extended by more specific definitions.
 614              Extensions must apply all the semantics from their parent
 615              object as well as any additional semantics.  If the
 616              underlying infrastructure is unable to support a
 617              particular feature, it MUST trigger an exception that
 618              will render the enclosing subject inactive until the
 619              exception is resolved.  If the fallback-behavior
 620              parameter is set to 'allow-fallback', the infrastructure
 621              MAY instead apply the parent subject feature and instead
 622              raise a nonfatal exception.";
 623
 624         config false;
 625
 626         list classifier-definition {
 627             description
 628                 "A classifier is used to match traffic traveling between
 629                  the endpoint groups that form the contract.
 630                  Classifier definitions can define parameters that
 631                  will need to be filled in when a particular rule
 632                  references it.";
 633
 634             key "id";
 635             uses subject-feature-definition;
 636
 637             leaf id {
 638                 description "A unique ID for the classifier definition";
 639                 type gbp-common:classifier-definition-id;
 640                 mandatory true;
 641             }
 642
 643             leaf name {
 644                 description
 645                     "A user-visible name for the classifier definition";
 646                 type gbp-common:classifier-name;
 647             }
 648
 649             leaf parent {
 650                 description
 651                     "Parent classifier definition from which we inherit";
 652                 type leafref {
 653                     path "/subject-feature-definitions/classifier-definition/id";
 654                 }
 655             }
 656         }
 657
 658         list action-definition {
 659             description
 660                 "A action to be applied to traffic across endpoint
 661                  groups.  Action definitions can define parameters
 662                  that will need to be filled in when a particular rule
 663                  references it.";
 664
 665             key "id";
 666             uses subject-feature-definition;
 667
 668             leaf id {
 669                 description "A unique ID for the action";
 670                 type gbp-common:action-definition-id;
 671                 mandatory true;
 672             }
 673
 674             leaf name {
 675                 description "A user-visible name for the action";
 676                 type gbp-common:action-name;
 677             }
 678
 679             leaf parent {
 680                 description
 681                     "Parent action definition from which we inherit";
 682                 type leafref {
 683                     path "/subject-feature-definitions/action-definition/id";
 684                 }
 685             }
 686         }
 687     }
 688
 689     // *******
 690     // Tenants
 691     // *******
 692
 693     container tenants {
 694         description "The list of all known tenants";
 695
 696         config true;
 697
 698         list tenant {
 699             description
 700                 "A tenant is a domain of administration which is
 701                  logically separate from other tenants.  Most policy
 702                  is defined in the context of a particular tenant";
 703
 704             key "id";
 705             leaf id {
 706                 description "A unique ID for the tenant";
 707                 mandatory true;
 708                 type gbp-common:tenant-id;
 709             }
 710             leaf name {
 711                 description "A user-visible name for the tenant";
 712                 type gbp-common:name;
 713             }
 714             leaf description {
 715                 description "A user-readable description for the tenant";
 716                 type gbp-common:description;
 717             }
 718
 719             // ***************
 720             // Network domains
 721             // ***************
 722
 723             list l3-context {
 724                 description
 725                     "A layer 3 context represents a namespace for layer 3
 726                      addresses.  It represents a domain inside which endpoints
 727                      can communicate with requiring any address translation.";
 728
 729                 key "id";
 730                 uses forwarding-context;
 731
 732                 leaf id {
 733                     description
 734                         "A unique ID for the layer 3 context";
 735                     type gbp-common:l3-context-id;
 736                 }
 737             }
 738
 739             list l2-bridge-domain {
 740                 description
 741                     "A layer 2 bridge domain represents a domain in which
 742                      layer 2 communication is possible when allowed by policy.";
 743                 key "id";
 744                 uses l2-context;
 745
 746                 leaf id {
 747                     description "A unique ID for the bridge domain";
 748                     type gbp-common:l2-bridge-domain-id;
 749                 }
 750
 751                 leaf parent {
 752                     description
 753                         "The layer 3 context that contains this bridge domain";
 754                     type leafref {
 755                         path "/tenants/tenant/l3-context/id";
 756                     }
 757                 }
 758             }
 759
 760             list l2-flood-domain {
 761                 description
 762                     "A layer 2 flood domain represents a domain in which
 763                      layer 2 broadcast and multicast is allowed.";
 764                 key "id";
 765                 uses l2-context;
 766
 767                 leaf id {
 768                     description "A unique ID for the flood domain";
 769                     type  gbp-common:l2-flood-domain-id;
 770                 }
 771
 772                 leaf parent {
 773                     description
 774                         "The bridge domain that contains this flood domain";
 775                     type leafref {
 776                         path "/tenants/tenant/l2-bridge-domain/id";
 777                     }
 778                 }
 779             }
 780
 781             list subnet {
 782                 description
 783                     "An IP subnet associated with a layer 2 or layer 3
 784                      context.";
 785                 key "id";
 786                 uses network-domain;
 787
 788                 leaf id {
 789                     description "A unique ID for the subnet";
 790                     type gbp-common:subnet-id;
 791                 }
 792
 793                 leaf parent {
 794                     description
 795                         "The forwarding context that contains this subnet";
 796                     type gbp-common:context-id;
 797                 }
 798
 799                 leaf ip-prefix {
 800                     description "The IP prefix that defines the subnet";
 801                     type inet:ip-prefix;
 802                 }
 803                 leaf virtual-router-ip {
 804                     description
 805                         "IP address to use for a virtual gateway router
 806                          for the subnet, if desired.";
 807                     type inet:ip-address;
 808                 }
 809             }
 810
 811             // ***************
 812             // Endpoint groups
 813             // ***************
 814
 815             list endpoint-group {
 816                 description
 817                     "Endpoint groups are sets of endpoints that share a
 818                      common set of policies.  Endpoint groups are
 819                      matched to contracts using selectors, contracts
 820                      determine which endpoints can communicate and in
 821                      what way.
 822
 823                      Endpoint groups have both requirements and
 824                      capabilities, which represent specific pieces of
 825                      functionality that are exposed at the boundary of
 826                      those groups.  Requirements represent some
 827                      specific functionality that is needed for the
 828                      endpoints in the endpoint group to function.
 829                      Correspondingly, capabilities are pieces of
 830                      functionality that the endpoints in the endpoint
 831                      group can provide to other endpoints.
 832
 833                      Contracts can be selected through either a named
 834                      selector, which matches specific contracts by
 835                      name, or by a target selector which will match
 836                      contracts by matching its list of qualities to
 837                      the list of qualities for a target on the
 838                      contract.  The contract selectors choose which
 839                      contracts are in scope.  Note that requirements
 840                      and capabilities are not used when choosing which
 841                      contracts are in scope; these are used to
 842                      determine how a contract will be interpreted.
 843
 844                      There are two broad category of selectors:
 845                      provider selectors and consumer selectors.  The
 846                      provider selectors allow selecting contracts that
 847                      allow the endpoint group to expose its
 848                      capabilities.  The consumer selectors allow
 849                      selecting contracts which allow the endpoint
 850                      group to meet its requirements.";
 851
 852                 key "id";
 853
 854                 leaf id {
 855                     mandatory true;
 856                     type gbp-common:endpoint-group-id;
 857                 }
 858
 859                 leaf name {
 860                     description
 861                         "A user-visible name for the endpoint group";
 862                     type gbp-common:name;
 863                 }
 864                 leaf description {
 865                     description
 866                         "A human-readable description for the endpoint
 867                          group.";
 868                     type gbp-common:description;
 869                 }
 870                 uses has-requirements;
 871                 uses has-capabilities;
 872
 873                 leaf intra-group-policy {
 874                     description
 875                         "Governs how traffic within the endpoint group
 876                          should be handled.";
 877                     default allow;
 878                     type enumeration {
 879                         enum allow {
 880                             description
 881                                 "Traffic between two endpoints in the group
 882                                  is always allowed";
 883                         }
 884                         enum require-contract {
 885                             description
 886                                 "Traffic between two endpoints in the group
 887                                  is allowed only when a contract exists to
 888                                  allow it explicitly";
 889                         }
 890                     }
 891                 }
 892
 893                 list consumer-named-selector {
 894                     description
 895                         "Consumer named selectors are named selectors
 896                          that select contracts to meet the
 897                          requirements of the endpoint group.
 898
 899                          The consumer named selector selects a
 900                          contract based on the name of the contract.
 901                          Once the contract is selected, the
 902                          requirements are used to select specific
 903                          subjects within that contract.";
 904
 905                     key "name";
 906                     uses named-selector;
 907                     uses consumer-selection-relator;
 908                 }
 909
 910                 list provider-named-selector {
 911                     description
 912                         "Provider named selectors are named selectors
 913                          that select contracts to provide capabilties
 914                          to other endpoint group.
 915
 916                          The provider named selector selects a
 917                          contract based on the name of the contract.
 918                          Once the contract is selected, the capabilies
 919                          are used to select specific subjects within
 920                          that contract.";
 921
 922                     key "name";
 923                     uses named-selector;
 924                     uses provider-selection-relator;
 925                 }
 926
 927                 list consumer-target-selector {
 928                     description
 929                         "Consumer target selectors are target selectors
 930                          that select contracts to meet the requirements
 931                          of the endpoint group.
 932
 933                          The consumer target selector selects a
 934                          contract using the quality matchers to match
 935                          against the qualities specified on the
 936                          contract targets.  Once the contract is
 937                          selected, the requirements are used to select
 938                          specific subjects within that contract.";
 939
 940                     key "name";
 941                     uses target-selector;
 942                     uses consumer-selection-relator;
 943                 }
 944
 945                 list provider-target-selector {
 946                     description
 947                         "Provider target selectors are target selectors
 948                          that select contracts to provide capabilties
 949                          to other endpoint group.
 950
 951                          The provider target selector selects a
 952                          contract using the quality matchers to match
 953                          against the qualities specified on the
 954                          contract targets.  Once the contract is
 955                          selected, the capabilities are used to select
 956                          specific subjects within that contract.";
 957
 958                     key "name";
 959                     uses target-selector;
 960                     uses provider-selection-relator;
 961                 }
 962
 963                 leaf network-domain {
 964                     description
 965                         "The network domain associated with this endpoint
 966                          group.  The network domain controls which endpoints
 967                          are addressible by the endpoints in the group.";
 968                     type gbp-common:network-domain-id;
 969                 }
 970
 971                 leaf parent {
 972                     description
 973                         "Parent endpoint group from which we inherit";
 974
 975                     type leafref {
 976                         path "/tenants/tenant/endpoint-group/id";
 977                     }
 978                 }
 979             }
 980
 981             // *************************
 982             // Subject feature instances
 983             // *************************
 984
 985             container subject-feature-instances {
 986                 description
 987                     "Contains instances of subject features.  Subject
 988                      feature instances reference a subject feature
 989                      definition but fill in the required parameters so
 990                      that they can be easily references elsewhere.";
 991
 992                 list classifier-instance {
 993                     description "XXX";
 994
 995                     key "name";
 996                     leaf name {
 997                         description "A name for the classifier instance";
 998                         type gbp-common:classifier-name;
 999                         mandatory true;
1000                     }
1001                     leaf classifier-definition-id {
1002                         type leafref {
1003                             path "/subject-feature-definitions/classifier-definition/id";
1004                         }
1005                     }
1006                     uses subject-feature-instance;
1007                 }
1008
1009                 list action-instance {
1010                     description "XXX";
1011
1012                     key "name";
1013                     leaf name {
1014                         description "A name for the action instance";
1015                         type gbp-common:action-name;
1016                         mandatory true;
1017                     }
1018                     leaf action-definition-id {
1019                         type leafref {
1020                             path "/subject-feature-definitions/action-definition/id";
1021                         }
1022                     }
1023                     uses subject-feature-instance;
1024                 }
1025             }
1026
1027             // *********
1028             // Contracts
1029             // *********
1030
1031             list contract {
1032                 description
1033                     "Contracts contain a set of subjects that describe
1034                      the communication allowed between endpoints in
1035                      endpoint groups.  Contracts are matched to endpoint
1036                      groups by selectors.";
1037
1038                 key "id";
1039                 leaf id {
1040                     description "A unique ID for the contract";
1041                     type gbp-common:contract-id;
1042                     mandatory true;
1043                 }
1044
1045                 leaf description {
1046                     description
1047                         "A human-readable description for the contract.";
1048                     type gbp-common:description;
1049                 }
1050
1051                 // *******
1052                 // Relator
1053                 // *******
1054
1055                 uses has-qualities;
1056
1057                 list target {
1058                     description
1059                         "Targets on a contract allow grouping sets of qualities
1060                          together, as well as providing a namespace for
1061                          the qualities that are matched.";
1062
1063                     key "name";
1064                     leaf name {
1065                         description
1066                             "The name for this target.  This can also be used
1067                              by quality matchers as a namespace for qualities.";
1068                         type gbp-common:target-name;
1069                         mandatory true;
1070                     }
1071
1072                     uses relator;
1073                     uses has-qualities;
1074                 }
1075
1076                 // ********************
1077                 // Clauses and subjects
1078                 // ********************
1079
1080                 list subject {
1081                     description
1082                         "Subjects define rules to allow traffic to flow
1083                          between endpoints in different endpoint
1084                          groups.  No communication is allowed unless a
1085                          subject allows that communication.
1086
1087                          After a contract has been selected, clauses
1088                          in that contract match against the
1089                          requirements, capabilities, and conditions
1090                          that apply to the endpoints or endpoint
1091                          groups that are participating in the
1092                          contract.  Clauses that match each point to a
1093                          subject which then becomes active.
1094
1095                          An active subject can then apply its rules to
1096                          the traffic between the endpoints.";
1097
1098                     key "name";
1099                     leaf name {
1100                         description "A name for the subject";
1101                         type gbp-common:subject-name;
1102                         mandatory true;
1103                     }
1104
1105                     list rule {
1106                         description
1107                             "A rule is applied to traffic between
1108                              endpoints in different endpoint groups.
1109                              Rules match against the traffic using
1110                              classifiers, and then apply actions to
1111                              the traffic for matching rules.
1112
1113                              Rules are applied in order according to
1114                              their order parameter.  Only the first
1115                              matching rule will apply.  When multiple
1116                              subjects are active, the order on each
1117                              subject will determine which subjects are
1118                              applied first, and all their rules will
1119                              take effect before the rules of any
1120                              subjects with a higher order value.  When
1121                              subjects have the same order value, then
1122                              they will apply in lexicographic order by
1123                              subject name.";
1124
1125                         key "name";
1126                         leaf name {
1127                             description "A name for the rule";
1128                             type gbp-common:rule-name;
1129                             mandatory true;
1130                         }
1131
1132                         uses has-classifier-refs;
1133                         uses has-action-refs;
1134                         uses has-order;
1135                     }
1136
1137                     uses has-order;
1138                 }
1139
1140                 list clause {
1141                     description
1142                         "Clauses are used to determine which subjects are
1143                          active once a contract is selected using the
1144                          contract selectors.
1145
1146                          Clauses are activated by matching against
1147                          requirements on the consumer endpoint group,
1148                          capabilities on the provider endpoint group, and
1149                          conditions on the individual endpoints in the
1150                          endpoint group.";
1151
1152                     key "name";
1153                     leaf name {
1154                         type gbp-common:clause-name;
1155                         mandatory true;
1156                     }
1157
1158                     // ********
1159                     // Matchers
1160                     // ********
1161
1162                     container consumer-matchers {
1163                         description
1164                             "Matchers that apply to the consumer endpoint
1165                              group.";
1166                         list requirement-matcher {
1167                             description
1168                                 "Match against requirements in the consumer
1169                                  endpoint group.";
1170
1171                             key "name";
1172                             leaf name {
1173                                 description
1174                                     "A name for the requirement matcher";
1175                                 type gbp-common:requirement-matcher-name;
1176                                 mandatory true;
1177                             }
1178
1179                             uses matcher;
1180                             list matcher-requirement {
1181                                 description
1182                                     "A matcher requirement is a
1183                                      requirement with a selector name
1184                                      field used in requirement
1185                                      matchers.  The name of the
1186                                      matcher requirement matches
1187                                      against requirements in endpoint
1188                                      groups.";
1189
1190                                 key name;
1191                                 uses requirement-base;
1192
1193                                 leaf selector-namespace {
1194                                     description
1195                                         "The name of the selector to
1196                                          match.  This allows us to
1197                                          specify that we want to match
1198                                          only requirements scoped to a
1199                                          particular selector name.
1200
1201                                          This parameter is optional;
1202                                          if not specified, use an
1203                                          inherited selector namespace
1204                                          if it exists, or match
1205                                          against any selector name.";
1206
1207                                     type gbp-common:selector-name;
1208                                 }
1209                             }
1210                         }
1211                         uses has-condition-matchers;
1212                     }
1213
1214                     container provider-matchers {
1215                         description
1216                             "Matchers that apply to the provider endpoint
1217                              group";
1218
1219                         list capability-matcher {
1220                             description
1221                                 "Match against capabilities in the provider
1222                                  endpoint group.";
1223
1224                             key "name";
1225                             leaf name {
1226                                 description
1227                                     "A name for the capability matcher";
1228                                 type gbp-common:capability-matcher-name;
1229                                 mandatory true;
1230                             }
1231
1232                             uses matcher;
1233
1234                             list matcher-capability {
1235                                 description
1236                                     "A matcher capability is a
1237                                      capability with a selector
1238                                      name field used in capability
1239                                      mat  chers.  The name of the
1240                                      matcher capability matches
1241                                      against capabilities in
1242                                      endpoint groups.";
1243
1244                                 key name;
1245                                 uses capability-base;
1246
1247                                 leaf selector-namespace {
1248                                     description
1249                                         "The name of the selector to
1250                                          match.  This allows us to
1251                                          specify that we want to match
1252                                          only capabilities scoped to a
1253                                          particular selector name.
1254
1255                                          This parameter is optional;
1256                                          if not specified, use an
1257                                          inherited selector namespace
1258                                          if it exists, or match
1259                                          against any selector name.";
1260
1261                                     type gbp-common:selector-name;
1262                                 }
1263                             }
1264                         }
1265                         uses has-condition-matchers;
1266                     }
1267
1268                     // ******************
1269                     // Subject References
1270                     // ******************
1271
1272                     leaf-list subject-refs {
1273                         description
1274                             "The subjects that will be activated if this
1275                              clause matches.";
1276
1277                         type leafref {
1278                             path "/tenants/tenant/contract/subject/name";
1279                         }
1280                     }
1281                 }
1282
1283                 // ***********
1284                 // Inheritance
1285                 // ***********
1286
1287                 leaf parent {
1288                     description "Parent contract from which we inherit";
1289
1290                     type leafref {
1291                         path "/tenants/tenant/contract/id";
1292                     }
1293                 }
1294             }
1295
1296             list contract-ref {
1297                 description
1298                     "Contract references allow forming contracts
1299                      between endpoint groups in different tenants.
1300                      Once the contract reference is created, it is
1301                      then possible to match against the contract using
1302                      selectors as though it were a local tenant.
1303
1304                      Endpoint groups in the local tenant can serve
1305                      only as consumers of the contract.  Once the
1306                      contract is matched, consumer matchers will apply
1307                      to requirements and conditions in the local
1308                      tenant, and provider matchers will apply against
1309                      capabilities and conditions in the referenced
1310                      tenant.";
1311
1312                 leaf tenant-id {
1313                     description
1314                         "The tenant ID of the tenant containing the
1315                          contract.";
1316                     type leafref {
1317                         path "/tenants/tenant/contract/id";
1318                     }
1319                 }
1320                 leaf contract-id {
1321                     description "The contract ID of the contract.";
1322
1323                     type leafref {
1324                         path "/tenants/tenant/contract/id";
1325                     }
1326                 }
1327             }
1328         }
1329     }
1330 }