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             leaf parent {
 685                 description
 686                     "Parent classifier definition from which we inherit";
 687                 type leafref {
 688                     path "/subject-feature-definitions/classifier-definition/id";
 689                 }
 690             }
 691         }
 692
 693         list action-definition {
 694             description
 695                 "A action to be applied to traffic across endpoint
 696                  groups.  Action definitions can define parameters
 697                  that will need to be filled in when a particular rule
 698                  references it.";
 699
 700             key "id";
 701             uses subject-feature-definition;
 702
 703             leaf id {
 704                 description "A unique ID for the action";
 705                 type gbp-common:action-definition-id;
 706                 mandatory true;
 707             }
 708
 709             leaf name {
 710                 description "A user-visible name for the action";
 711                 type gbp-common:action-name;
 712             }
 713
 714             leaf parent {
 715                 description
 716                     "Parent action definition from which we inherit";
 717                 type leafref {
 718                     path "/subject-feature-definitions/action-definition/id";
 719                 }
 720             }
 721         }
 722     }
 723
 724     // *******
 725     // Tenants
 726     // *******
 727
 728     container tenants {
 729         description "The list of all known tenants";
 730
 731         config true;
 732
 733         list tenant {
 734             description
 735                 "A tenant is a domain of administration which is
 736                  logically separate from other tenants.  Most policy
 737                  is defined in the context of a particular tenant";
 738
 739             key "id";
 740             leaf id {
 741                 description "A unique ID for the tenant";
 742                 mandatory true;
 743                 type gbp-common:tenant-id;
 744             }
 745             leaf name {
 746                 description "A user-visible name for the tenant";
 747                 type gbp-common:name;
 748             }
 749             leaf description {
 750                 description "A user-readable description for the tenant";
 751                 type gbp-common:description;
 752             }
 753
 754             // ***************
 755             // Network domains
 756             // ***************
 757
 758             list l3-context {
 759                 description
 760                     "A layer 3 context represents a namespace for layer 3
 761                      addresses.  It represents a domain inside which endpoints
 762                      can communicate with requiring any address translation.";
 763
 764                 key "id";
 765                 uses forwarding-context;
 766
 767                 leaf id {
 768                     description
 769                         "A unique ID for the layer 3 context";
 770                     type gbp-common:l3-context-id;
 771                 }
 772             }
 773
 774             list l2-bridge-domain {
 775                 description
 776                     "A layer 2 bridge domain represents a domain in which
 777                      layer 2 communication is possible when allowed by policy.";
 778                 key "id";
 779                 uses l2-context;
 780
 781                 leaf id {
 782                     description "A unique ID for the bridge domain";
 783                     type gbp-common:l2-bridge-domain-id;
 784                 }
 785
 786                 leaf parent {
 787                     description
 788                         "The layer 3 context that contains this bridge domain";
 789                     type leafref {
 790                         path "/tenants/tenant/l3-context/id";
 791                     }
 792                 }
 793             }
 794
 795             list l2-flood-domain {
 796                 description
 797                     "A layer 2 flood domain represents a domain in which
 798                      layer 2 broadcast and multicast is allowed.";
 799                 key "id";
 800                 uses l2-context;
 801
 802                 leaf id {
 803                     description "A unique ID for the flood domain";
 804                     type  gbp-common:l2-flood-domain-id;
 805                 }
 806
 807                 leaf parent {
 808                     description
 809                         "The bridge domain that contains this flood domain";
 810                     type leafref {
 811                         path "/tenants/tenant/l2-bridge-domain/id";
 812                     }
 813                 }
 814             }
 815
 816             list subnet {
 817                 description
 818                     "An IP subnet associated with a layer 2 or layer 3
 819                      context.";
 820                 key "id";
 821                 uses network-domain;
 822
 823                 leaf id {
 824                     description "A unique ID for the subnet";
 825                     type gbp-common:subnet-id;
 826                 }
 827
 828                 leaf parent {
 829                     description
 830                         "The forwarding context that contains this subnet";
 831                     type gbp-common:context-id;
 832                 }
 833
 834                 leaf ip-prefix {
 835                     description "The IP prefix that defines the subnet";
 836                     type inet:ip-prefix;
 837                 }
 838                 leaf virtual-router-ip {
 839                     description
 840                         "IP address to use for a virtual gateway router
 841                          for the subnet, if desired.";
 842                     type inet:ip-address;
 843                 }
 844                 list gateways {
 845                     description
 846                         "External gateways for subnets we serve,
 847                         includes prefixes for static routing";
 848                     key "gateway";
 849                     leaf gateway {
 850                         type inet:ip-address;
 851                     }
 852                     list prefixes {
 853                         key "prefix";
 854                         leaf prefix {
 855                             type inet:ip-prefix;
 856                         }
 857                     }
 858
 859                 }
 860             }
 861
 862             // ***************
 863             // Endpoint groups
 864             // ***************
 865
 866             list endpoint-group {
 867                 description
 868                     "Endpoint groups are sets of endpoints that share a
 869                      common set of policies.  Endpoint groups are
 870                      matched to contracts using selectors, contracts
 871                      determine which endpoints can communicate and in
 872                      what way.
 873
 874                      Endpoint groups have both requirements and
 875                      capabilities, which represent specific pieces of
 876                      functionality that are exposed at the boundary of
 877                      those groups.  Requirements represent some
 878                      specific functionality that is needed for the
 879                      endpoints in the endpoint group to function.
 880                      Correspondingly, capabilities are pieces of
 881                      functionality that the endpoints in the endpoint
 882                      group can provide to other endpoints.
 883
 884                      Contracts can be selected through either a named
 885                      selector, which matches specific contracts by
 886                      name, or by a target selector which will match
 887                      contracts by matching its list of qualities to
 888                      the list of qualities for a target on the
 889                      contract.  The contract selectors choose which
 890                      contracts are in scope.  Note that requirements
 891                      and capabilities are not used when choosing which
 892                      contracts are in scope; these are used to
 893                      determine how a contract will be interpreted.
 894
 895                      There are two broad category of selectors:
 896                      provider selectors and consumer selectors.  The
 897                      provider selectors allow selecting contracts that
 898                      allow the endpoint group to expose its
 899                      capabilities.  The consumer selectors allow
 900                      selecting contracts which allow the endpoint
 901                      group to meet its requirements.";
 902
 903                 key "id";
 904
 905                 leaf id {
 906                     mandatory true;
 907                     type gbp-common:endpoint-group-id;
 908                 }
 909
 910                 leaf name {
 911                     description
 912                         "A user-visible name for the endpoint group";
 913                     type gbp-common:name;
 914                 }
 915                 leaf description {
 916                     description
 917                         "A human-readable description for the endpoint
 918                          group.";
 919                     type gbp-common:description;
 920                 }
 921                 uses has-requirements;
 922                 uses has-capabilities;
 923
 924                 leaf intra-group-policy {
 925                     description
 926                         "Governs how traffic within the endpoint group
 927                          should be handled.";
 928                     default allow;
 929                     type enumeration {
 930                         enum allow {
 931                             description
 932                                 "Traffic between two endpoints in the group
 933                                  is always allowed";
 934                         }
 935                         enum require-contract {
 936                             description
 937                                 "Traffic between two endpoints in the group
 938                                  is allowed only when a contract exists to
 939                                  allow it explicitly";
 940                         }
 941                     }
 942                 }
 943
 944                 list consumer-named-selector {
 945                     description
 946                         "Consumer named selectors are named selectors
 947                          that select contracts to meet the
 948                          requirements of the endpoint group.
 949
 950                          The consumer named selector selects a
 951                          contract based on the name of the contract.
 952                          Once the contract is selected, the
 953                          requirements are used to select specific
 954                          subjects within that contract.";
 955
 956                     key "name";
 957                     uses named-selector;
 958                     uses consumer-selection-relator;
 959                 }
 960
 961                 list provider-named-selector {
 962                     description
 963                         "Provider named selectors are named selectors
 964                          that select contracts to provide capabilties
 965                          to other endpoint group.
 966
 967                          The provider named selector selects a
 968                          contract based on the name of the contract.
 969                          Once the contract is selected, the capabilies
 970                          are used to select specific subjects within
 971                          that contract.";
 972
 973                     key "name";
 974                     uses named-selector;
 975                     uses provider-selection-relator;
 976                 }
 977
 978                 list consumer-target-selector {
 979                     description
 980                         "Consumer target selectors are target selectors
 981                          that select contracts to meet the requirements
 982                          of the endpoint group.
 983
 984                          The consumer target selector selects a
 985                          contract using the quality matchers to match
 986                          against the qualities specified on the
 987                          contract targets.  Once the contract is
 988                          selected, the requirements are used to select
 989                          specific subjects within that contract.";
 990
 991                     key "name";
 992                     uses target-selector;
 993                     uses consumer-selection-relator;
 994                 }
 995
 996                 list provider-target-selector {
 997                     description
 998                         "Provider target selectors are target selectors
 999                          that select contracts to provide capabilties
1000                          to other endpoint group.
1001
1002                          The provider target selector selects a
1003                          contract using the quality matchers to match
1004                          against the qualities specified on the
1005                          contract targets.  Once the contract is
1006                          selected, the capabilities are used to select
1007                          specific subjects within that contract.";
1008
1009                     key "name";
1010                     uses target-selector;
1011                     uses provider-selection-relator;
1012                 }
1013
1014                 leaf network-domain {
1015                     description
1016                         "The network domain associated with this endpoint
1017                          group.  The network domain controls which endpoints
1018                          are addressible by the endpoints in the group.";
1019                     type gbp-common:network-domain-id;
1020                 }
1021
1022                 leaf parent {
1023                     description
1024                         "Parent endpoint group from which we inherit";
1025
1026                     type leafref {
1027                         path "/tenants/tenant/endpoint-group/id";
1028                     }
1029                 }
1030             }
1031
1032             list external-implicit-group {
1033                 description
1034                     ".";
1035
1036                 key "id";
1037
1038                 leaf id {
1039                     mandatory true;
1040                     type gbp-common:endpoint-group-id;
1041                 }
1042                 // Fields to be determined and completed before Code Freeze
1043
1044             }
1045             // *************************
1046             // Subject feature instances
1047             // *************************
1048
1049             container subject-feature-instances {
1050                 description
1051                     "Contains instances of subject features.  Subject
1052                      feature instances reference a subject feature
1053                      definition but fill in the required parameters so
1054                      that they can be easily references elsewhere.";
1055
1056                 list classifier-instance {
1057                     description "XXX";
1058
1059                     key "name";
1060                     leaf name {
1061                         description "A name for the classifier instance";
1062                         type gbp-common:classifier-name;
1063                         mandatory true;
1064                     }
1065                     leaf classifier-definition-id {
1066                         type leafref {
1067                             path "/subject-feature-definitions/classifier-definition/id";
1068                         }
1069                     }
1070                     uses subject-feature-instance;
1071                 }
1072
1073                 list action-instance {
1074                     description "XXX";
1075
1076                     key "name";
1077                     leaf name {
1078                         description "A name for the action instance";
1079                         type gbp-common:action-name;
1080                         mandatory true;
1081                     }
1082                     leaf action-definition-id {
1083                         type leafref {
1084                             path "/subject-feature-definitions/action-definition/id";
1085                         }
1086                     }
1087                     uses subject-feature-instance;
1088                 }
1089             }
1090
1091             // *********
1092             // Contracts
1093             // *********
1094
1095             list contract {
1096                 description
1097                     "Contracts contain a set of subjects that describe
1098                      the communication allowed between endpoints in
1099                      endpoint groups.  Contracts are matched to endpoint
1100                      groups by selectors.";
1101
1102                 key "id";
1103                 leaf id {
1104                     description "A unique ID for the contract";
1105                     type gbp-common:contract-id;
1106                     mandatory true;
1107                 }
1108
1109                 leaf description {
1110                     description
1111                         "A human-readable description for the contract.";
1112                     type gbp-common:description;
1113                 }
1114
1115                 // *******
1116                 // Relator
1117                 // *******
1118
1119                 uses has-qualities;
1120
1121                 list target {
1122                     description
1123                         "Targets on a contract allow grouping sets of qualities
1124                          together, as well as providing a namespace for
1125                          the qualities that are matched.";
1126
1127                     key "name";
1128                     leaf name {
1129                         description
1130                             "The name for this target.  This can also be used
1131                              by quality matchers as a namespace for qualities.";
1132                         type gbp-common:target-name;
1133                         mandatory true;
1134                     }
1135
1136                     uses relator;
1137                     uses has-qualities;
1138                 }
1139
1140                 // ********************
1141                 // Clauses and subjects
1142                 // ********************
1143
1144                 list subject {
1145                     description
1146                         "Subjects define rules to allow traffic to flow
1147                          between endpoints in different endpoint
1148                          groups.  No communication is allowed unless a
1149                          subject allows that communication.
1150
1151                          After a contract has been selected, clauses
1152                          in that contract match against the
1153                          requirements, capabilities, and conditions
1154                          that apply to the endpoints or endpoint
1155                          groups that are participating in the
1156                          contract.  Clauses that match each point to a
1157                          subject which then becomes active.
1158
1159                          An active subject can then apply its rules to
1160                          the traffic between the endpoints.";
1161
1162                     key "name";
1163                     leaf name {
1164                         description "A name for the subject";
1165                         type gbp-common:subject-name;
1166                         mandatory true;
1167                     }
1168
1169                     list rule {
1170                         description
1171                             "A rule is applied to traffic between
1172                              endpoints in different endpoint groups.
1173                              Rules match against the traffic using
1174                              classifiers, and then apply actions to
1175                              the traffic for matching rules.
1176
1177                              Rules are applied in order according to
1178                              their order parameter.  Only the first
1179                              matching rule will apply.  When multiple
1180                              subjects are active, the order on each
1181                              subject will determine which subjects are
1182                              applied first, and all their rules will
1183                              take effect before the rules of any
1184                              subjects with a higher order value.  When
1185                              subjects have the same order value, then
1186                              they will apply in lexicographic order by
1187                              subject name.";
1188
1189                         key "name";
1190                         leaf name {
1191                             description "A name for the rule";
1192                             type gbp-common:rule-name;
1193                             mandatory true;
1194                         }
1195
1196                         uses has-classifier-refs;
1197                         uses has-action-refs;
1198                         uses has-order;
1199                     }
1200
1201                     uses has-order;
1202                 }
1203
1204                 list clause {
1205                     description
1206                         "Clauses are used to determine which subjects are
1207                          active once a contract is selected using the
1208                          contract selectors.
1209
1210                          Clauses are activated by matching against
1211                          requirements on the consumer endpoint group,
1212                          capabilities on the provider endpoint group, and
1213                          conditions on the individual endpoints in the
1214                          endpoint group.";
1215                     key "name";
1216                     leaf name {
1217                         type gbp-common:clause-name;
1218                         mandatory true;
1219                     }
1220                     // ********
1221                     // Matchers
1222                     // ********
1223
1224                     container consumer-matchers {
1225                         description
1226                             "Matchers that apply to the consumer endpoint
1227                              group.";
1228
1229                         // GIC mutually OR'd within role
1230                         choice group-identification-constraints {
1231                             description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";
1232
1233                             case group-name-constraint-case {
1234                                 list group-name-constraint {
1235                                     key endpoint-group-name;
1236                                     leaf endpoint-group-name {
1237                                         type gbp-common:name;
1238                                     }
1239                                 }
1240                             }
1241                             case group-requirement-constraint-case {
1242                                 list requirement-matcher {
1243                                     description
1244                                         "Match against requirements in the consumer
1245                                          endpoint group.";
1246
1247                                     key "name";
1248                                     leaf name {
1249                                         description
1250                                             "A name for the requirement matcher";
1251                                         type gbp-common:requirement-matcher-name;
1252                                         mandatory true;
1253                                     }
1254
1255                                     uses matcher;
1256                                     list matcher-requirement {
1257                                         description
1258                                             "A matcher requirement is a
1259                                              requirement with a selector name
1260                                              field used in requirement
1261                                              matchers.  The name of the
1262                                              matcher requirement matches
1263                                              against requirements in endpoint
1264                                              groups.";
1265
1266                                         key name;
1267                                         uses requirement-base;
1268
1269                                         leaf selector-namespace {
1270                                             description
1271                                                 "The name of the selector to
1272                                                  match.  This allows us to
1273                                                  specify that we want to match
1274                                                  only requirements scoped to a
1275                                                  particular selector name.
1276
1277                                                  This parameter is optional;
1278                                                  if not specified, use an
1279                                                  inherited selector namespace
1280                                                  if it exists, or match
1281                                                  against any selector name.";
1282
1283                                             type gbp-common:selector-name;
1284                                         }
1285                                     }
1286                                 }
1287                             }
1288
1289                             case group-any-case {
1290                                 container group-any {
1291
1292                                     description
1293                                         "A presence container stating that, if this exists,
1294                                         the role matcher will match on any group.";
1295                                     presence "This matches any group";
1296                                 }
1297                             }
1298                         }
1299
1300
1301
1302                         uses has-condition-matchers;
1303
1304                         uses has-endpoint-identification-constraints;
1305                     }
1306
1307                     container provider-matchers {
1308                         description
1309                             "Matchers that apply to the provider endpoint
1310                              group";
1311
1312                         // GIC mutually OR'd within role
1313                         choice group-identification-constraints {
1314                             description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";
1315
1316                             case group-name-constraint-case {
1317                                 list group-name-constraint {
1318                                     key endpoint-group-name;
1319                                     leaf endpoint-group-name {
1320                                         type gbp-common:name;
1321                                     }
1322                                 }
1323                             }
1324                             case group-capability-constraint-case {
1325                                 list capability-matcher {
1326                                     description
1327                                         "Match against capabilities in the provider
1328                                          endpoint group.";
1329
1330                                     key "name";
1331                                     leaf name {
1332                                         description
1333                                             "A name for the capability matcher";
1334                                         type gbp-common:capability-matcher-name;
1335                                         mandatory true;
1336                                     }
1337
1338                                     uses matcher;
1339
1340                                     list matcher-capability {
1341                                         description
1342                                             "A matcher capability is a
1343                                              capability with a selector
1344                                              name field used in capability
1345                                              mat  chers.  The name of the
1346                                              matcher capability matches
1347                                              against capabilities in
1348                                              endpoint groups.";
1349
1350                                         key name;
1351                                         uses capability-base;
1352
1353                                         leaf selector-namespace {
1354                                             description
1355                                                 "The name of the selector to
1356                                                  match.  This allows us to
1357                                                  specify that we want to match
1358                                                  only capabilities scoped to a
1359                                                  particular selector name.
1360
1361                                                  This parameter is optional;
1362                                                  if not specified, use an
1363                                                  inherited selector namespace
1364                                                  if it exists, or match
1365                                                  against any selector name.";
1366
1367                                             type gbp-common:selector-name;
1368                                         }
1369                                     }
1370                                 }
1371                             }
1372                             case group-any-case {
1373                                 container group-any {
1374                                     presence "any";
1375                                 }
1376                             }
1377                         }
1378
1379                         uses has-condition-matchers;
1380
1381                         uses has-endpoint-identification-constraints;
1382                     }
1383
1384                     container any-matchers {
1385                         description
1386                             "Matchers that apply to either provider endpoint group or consumer endpoint group.";
1387                         // TODO fill this out, may need additional groupings so as to not confuse capability or requirement.
1388                    }
1389
1390                     // ******************
1391                     // Subject References
1392                     // ******************
1393
1394                     leaf-list subject-refs {
1395                         description
1396                             "The subjects that will be activated if this
1397                              clause matches.";
1398
1399                         type leafref {
1400                             path "/tenants/tenant/contract/subject/name";
1401                         }
1402                     }
1403                 }
1404
1405                 // ***********
1406                 // Inheritance
1407                 // ***********
1408
1409                 leaf parent {
1410                     description "Parent contract from which we inherit";
1411
1412                     type leafref {
1413                         path "/tenants/tenant/contract/id";
1414                     }
1415                 }
1416             }
1417
1418             list contract-ref {
1419                 description
1420                     "Contract references allow forming contracts
1421                      between endpoint groups in different tenants.
1422                      Once the contract reference is created, it is
1423                      then possible to match against the contract using
1424                      selectors as though it were a local tenant.
1425
1426                      Endpoint groups in the local tenant can serve
1427                      only as consumers of the contract.  Once the
1428                      contract is matched, consumer matchers will apply
1429                      to requirements and conditions in the local
1430                      tenant, and provider matchers will apply against
1431                      capabilities and conditions in the referenced
1432                      tenant.";
1433
1434                 key contract-id;
1435
1436                 leaf tenant-id {
1437                     description
1438                         "The tenant ID of the tenant containing the
1439                          contract.";
1440                     type leafref {
1441                         path "/tenants/tenant/id";
1442                     }
1443                 }
1444                 leaf contract-id {
1445                     description "The contract ID of the contract.";
1446
1447                     type leafref {
1448                         path "/tenants/tenant/contract/id";
1449                     }
1450                 }
1451             }
1452         }
1453     }
1454 }