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

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