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