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             key name;
 528             leaf name {
 529                 description "The name of the action instance";
 530                 type leafref {
 531                     path "/tenants/tenant/subject-feature-instances/action-instance/name";
 532                 }
 533                 mandatory true;
 534             }
 535             uses has-order;
 536         }
 537     }
 538
 539     grouping subject-feature-definition {
 540         description
 541             "Base type for subject feature definitions.";
 542
 543         leaf description {
 544             description "A user-readable description";
 545             type gbp-common:description;
 546         }
 547
 548         list parameter {
 549             description
 550                 "A parameter for the feature that can be
 551                  passed in.";
 552             key "name";
 553             leaf name {
 554                 description "A user-visible name for the parameter";
 555                 type gbp-common:parameter-name;
 556                 mandatory true;
 557             }
 558             leaf description {
 559                 description
 560                     "A user-visible description of the meaning of
 561                      the parameter.";
 562                 type gbp-common:description;
 563             }
 564             leaf type {
 565                 description "The type of the parameter";
 566                 default string;
 567                 type enumeration {
 568                     enum string {
 569                         description "A string-valued parameter";
 570                     }
 571                     enum int {
 572                         description "An integer-valued parameter";
 573                     }
 574                     enum range {
 575                         description "An integer-range parameter";
 576                     }
 577                 }
 578             }
 579             leaf is-required {
 580                 description "Specify whether the parameter is
 581                              required for correct operation.";
 582                 default optional;
 583                 type enumeration {
 584                     enum required {
 585                         description "The parameter is required";
 586                     }
 587                     enum optional {
 588                         description "The parameter is optional";
 589                     }
 590                 }
 591             }
 592         }
 593
 594         leaf fallback-behavior {
 595             description
 596                 "Set the behavior when the underlying infrastructure
 597                  is unable to support a particular feature.";
 598             type enumeration {
 599                 enum strict {
 600                     description
 601                         "A fatal exception MUST be raised which will
 602                          render the enclosing subject inactive.";
 603                 }
 604                 enum allow-fallback {
 605                     description
 606                         "The infrastructure MAY fall back to using
 607                          a parent definition of this feature, and
 608                          instread raise a nonfatal exception.";
 609                 }
 610             }
 611         }
 612     }
 613
 614     // ********************
 615     // Global Configuration
 616     // ********************
 617
 618     container subject-feature-definitions {
 619         description
 620             "Contains configuration for the set of actions and
 621              classifiers that can be defined for a subject.  This is
 622              be specific to the capabilities of the underlying
 623              infrastructure, so the policy model does not define the
 624              specific semantics.
 625
 626              The definitions here provide a generic parameterized base
 627              that can be extended by more specific definitions.
 628              Extensions must apply all the semantics from their parent
 629              object as well as any additional semantics.  If the
 630              underlying infrastructure is unable to support a
 631              particular feature, it MUST trigger an exception that
 632              will render the enclosing subject inactive until the
 633              exception is resolved.  If the fallback-behavior
 634              parameter is set to 'allow-fallback', the infrastructure
 635              MAY instead apply the parent subject feature and instead
 636              raise a nonfatal exception.";
 637
 638         config true;
 639
 640         list classifier-definition {
 641             description
 642                 "A classifier is used to match traffic traveling between
 643                  the endpoint groups that form the contract.
 644                  Classifier definitions can define parameters that
 645                  will need to be filled in when a particular rule
 646                  references it.";
 647
 648             key "id";
 649             uses subject-feature-definition;
 650
 651             leaf id {
 652                 description "A unique ID for the classifier definition";
 653                 type gbp-common:classifier-definition-id;
 654                 mandatory true;
 655             }
 656
 657             leaf name {
 658                 description
 659                     "A user-visible name for the classifier definition";
 660                 type gbp-common:classifier-name;
 661             }
 662
 663             leaf parent {
 664                 description
 665                     "Parent classifier definition from which we inherit";
 666                 type leafref {
 667                     path "/subject-feature-definitions/classifier-definition/id";
 668                 }
 669             }
 670         }
 671
 672         list action-definition {
 673             description
 674                 "A action to be applied to traffic across endpoint
 675                  groups.  Action definitions can define parameters
 676                  that will need to be filled in when a particular rule
 677                  references it.";
 678
 679             key "id";
 680             uses subject-feature-definition;
 681
 682             leaf id {
 683                 description "A unique ID for the action";
 684                 type gbp-common:action-definition-id;
 685                 mandatory true;
 686             }
 687
 688             leaf name {
 689                 description "A user-visible name for the action";
 690                 type gbp-common:action-name;
 691             }
 692
 693             leaf parent {
 694                 description
 695                     "Parent action definition from which we inherit";
 696                 type leafref {
 697                     path "/subject-feature-definitions/action-definition/id";
 698                 }
 699             }
 700         }
 701     }
 702
 703     // *******
 704     // Tenants
 705     // *******
 706
 707     container tenants {
 708         description "The list of all known tenants";
 709
 710         config true;
 711
 712         list tenant {
 713             description
 714                 "A tenant is a domain of administration which is
 715                  logically separate from other tenants.  Most policy
 716                  is defined in the context of a particular tenant";
 717
 718             key "id";
 719             leaf id {
 720                 description "A unique ID for the tenant";
 721                 mandatory true;
 722                 type gbp-common:tenant-id;
 723             }
 724             leaf name {
 725                 description "A user-visible name for the tenant";
 726                 type gbp-common:name;
 727             }
 728             leaf description {
 729                 description "A user-readable description for the tenant";
 730                 type gbp-common:description;
 731             }
 732
 733             // ***************
 734             // Network domains
 735             // ***************
 736
 737             list l3-context {
 738                 description
 739                     "A layer 3 context represents a namespace for layer 3
 740                      addresses.  It represents a domain inside which endpoints
 741                      can communicate with requiring any address translation.";
 742
 743                 key "id";
 744                 uses forwarding-context;
 745
 746                 leaf id {
 747                     description
 748                         "A unique ID for the layer 3 context";
 749                     type gbp-common:l3-context-id;
 750                 }
 751             }
 752
 753             list l2-bridge-domain {
 754                 description
 755                     "A layer 2 bridge domain represents a domain in which
 756                      layer 2 communication is possible when allowed by policy.";
 757                 key "id";
 758                 uses l2-context;
 759
 760                 leaf id {
 761                     description "A unique ID for the bridge domain";
 762                     type gbp-common:l2-bridge-domain-id;
 763                 }
 764
 765                 leaf parent {
 766                     description
 767                         "The layer 3 context that contains this bridge domain";
 768                     type leafref {
 769                         path "/tenants/tenant/l3-context/id";
 770                     }
 771                 }
 772             }
 773
 774             list l2-flood-domain {
 775                 description
 776                     "A layer 2 flood domain represents a domain in which
 777                      layer 2 broadcast and multicast is allowed.";
 778                 key "id";
 779                 uses l2-context;
 780
 781                 leaf id {
 782                     description "A unique ID for the flood domain";
 783                     type  gbp-common:l2-flood-domain-id;
 784                 }
 785
 786                 leaf parent {
 787                     description
 788                         "The bridge domain that contains this flood domain";
 789                     type leafref {
 790                         path "/tenants/tenant/l2-bridge-domain/id";
 791                     }
 792                 }
 793             }
 794
 795             list subnet {
 796                 description
 797                     "An IP subnet associated with a layer 2 or layer 3
 798                      context.";
 799                 key "id";
 800                 uses network-domain;
 801
 802                 leaf id {
 803                     description "A unique ID for the subnet";
 804                     type gbp-common:subnet-id;
 805                 }
 806
 807                 leaf parent {
 808                     description
 809                         "The forwarding context that contains this subnet";
 810                     type gbp-common:context-id;
 811                 }
 812
 813                 leaf ip-prefix {
 814                     description "The IP prefix that defines the subnet";
 815                     type inet:ip-prefix;
 816                 }
 817                 leaf virtual-router-ip {
 818                     description
 819                         "IP address to use for a virtual gateway router
 820                          for the subnet, if desired.";
 821                     type inet:ip-address;
 822                 }
 823             }
 824
 825             // ***************
 826             // Endpoint groups
 827             // ***************
 828
 829             list endpoint-group {
 830                 description
 831                     "Endpoint groups are sets of endpoints that share a
 832                      common set of policies.  Endpoint groups are
 833                      matched to contracts using selectors, contracts
 834                      determine which endpoints can communicate and in
 835                      what way.
 836
 837                      Endpoint groups have both requirements and
 838                      capabilities, which represent specific pieces of
 839                      functionality that are exposed at the boundary of
 840                      those groups.  Requirements represent some
 841                      specific functionality that is needed for the
 842                      endpoints in the endpoint group to function.
 843                      Correspondingly, capabilities are pieces of
 844                      functionality that the endpoints in the endpoint
 845                      group can provide to other endpoints.
 846
 847                      Contracts can be selected through either a named
 848                      selector, which matches specific contracts by
 849                      name, or by a target selector which will match
 850                      contracts by matching its list of qualities to
 851                      the list of qualities for a target on the
 852                      contract.  The contract selectors choose which
 853                      contracts are in scope.  Note that requirements
 854                      and capabilities are not used when choosing which
 855                      contracts are in scope; these are used to
 856                      determine how a contract will be interpreted.
 857
 858                      There are two broad category of selectors:
 859                      provider selectors and consumer selectors.  The
 860                      provider selectors allow selecting contracts that
 861                      allow the endpoint group to expose its
 862                      capabilities.  The consumer selectors allow
 863                      selecting contracts which allow the endpoint
 864                      group to meet its requirements.";
 865
 866                 key "id";
 867
 868                 leaf id {
 869                     mandatory true;
 870                     type gbp-common:endpoint-group-id;
 871                 }
 872
 873                 leaf name {
 874                     description
 875                         "A user-visible name for the endpoint group";
 876                     type gbp-common:name;
 877                 }
 878                 leaf description {
 879                     description
 880                         "A human-readable description for the endpoint
 881                          group.";
 882                     type gbp-common:description;
 883                 }
 884                 uses has-requirements;
 885                 uses has-capabilities;
 886
 887                 leaf intra-group-policy {
 888                     description
 889                         "Governs how traffic within the endpoint group
 890                          should be handled.";
 891                     default allow;
 892                     type enumeration {
 893                         enum allow {
 894                             description
 895                                 "Traffic between two endpoints in the group
 896                                  is always allowed";
 897                         }
 898                         enum require-contract {
 899                             description
 900                                 "Traffic between two endpoints in the group
 901                                  is allowed only when a contract exists to
 902                                  allow it explicitly";
 903                         }
 904                     }
 905                 }
 906
 907                 list consumer-named-selector {
 908                     description
 909                         "Consumer named selectors are named selectors
 910                          that select contracts to meet the
 911                          requirements of the endpoint group.
 912
 913                          The consumer named selector selects a
 914                          contract based on the name of the contract.
 915                          Once the contract is selected, the
 916                          requirements are used to select specific
 917                          subjects within that contract.";
 918
 919                     key "name";
 920                     uses named-selector;
 921                     uses consumer-selection-relator;
 922                 }
 923
 924                 list provider-named-selector {
 925                     description
 926                         "Provider named selectors are named selectors
 927                          that select contracts to provide capabilties
 928                          to other endpoint group.
 929
 930                          The provider named selector selects a
 931                          contract based on the name of the contract.
 932                          Once the contract is selected, the capabilies
 933                          are used to select specific subjects within
 934                          that contract.";
 935
 936                     key "name";
 937                     uses named-selector;
 938                     uses provider-selection-relator;
 939                 }
 940
 941                 list consumer-target-selector {
 942                     description
 943                         "Consumer target selectors are target selectors
 944                          that select contracts to meet the requirements
 945                          of the endpoint group.
 946
 947                          The consumer target selector selects a
 948                          contract using the quality matchers to match
 949                          against the qualities specified on the
 950                          contract targets.  Once the contract is
 951                          selected, the requirements are used to select
 952                          specific subjects within that contract.";
 953
 954                     key "name";
 955                     uses target-selector;
 956                     uses consumer-selection-relator;
 957                 }
 958
 959                 list provider-target-selector {
 960                     description
 961                         "Provider target selectors are target selectors
 962                          that select contracts to provide capabilties
 963                          to other endpoint group.
 964
 965                          The provider target selector selects a
 966                          contract using the quality matchers to match
 967                          against the qualities specified on the
 968                          contract targets.  Once the contract is
 969                          selected, the capabilities are used to select
 970                          specific subjects within that contract.";
 971
 972                     key "name";
 973                     uses target-selector;
 974                     uses provider-selection-relator;
 975                 }
 976
 977                 leaf network-domain {
 978                     description
 979                         "The network domain associated with this endpoint
 980                          group.  The network domain controls which endpoints
 981                          are addressible by the endpoints in the group.";
 982                     type gbp-common:network-domain-id;
 983                 }
 984
 985                 leaf parent {
 986                     description
 987                         "Parent endpoint group from which we inherit";
 988
 989                     type leafref {
 990                         path "/tenants/tenant/endpoint-group/id";
 991                     }
 992                 }
 993             }
 994
 995             // *************************
 996             // Subject feature instances
 997             // *************************
 998
 999             container subject-feature-instances {
1000                 description
1001                     "Contains instances of subject features.  Subject
1002                      feature instances reference a subject feature
1003                      definition but fill in the required parameters so
1004                      that they can be easily references elsewhere.";
1005
1006                 list classifier-instance {
1007                     description "XXX";
1008
1009                     key "name";
1010                     leaf name {
1011                         description "A name for the classifier instance";
1012                         type gbp-common:classifier-name;
1013                         mandatory true;
1014                     }
1015                     leaf classifier-definition-id {
1016                         type leafref {
1017                             path "/subject-feature-definitions/classifier-definition/id";
1018                         }
1019                     }
1020                     uses subject-feature-instance;
1021                 }
1022
1023                 list action-instance {
1024                     description "XXX";
1025
1026                     key "name";
1027                     leaf name {
1028                         description "A name for the action instance";
1029                         type gbp-common:action-name;
1030                         mandatory true;
1031                     }
1032                     leaf action-definition-id {
1033                         type leafref {
1034                             path "/subject-feature-definitions/action-definition/id";
1035                         }
1036                     }
1037                     uses subject-feature-instance;
1038                 }
1039             }
1040
1041             // *********
1042             // Contracts
1043             // *********
1044
1045             list contract {
1046                 description
1047                     "Contracts contain a set of subjects that describe
1048                      the communication allowed between endpoints in
1049                      endpoint groups.  Contracts are matched to endpoint
1050                      groups by selectors.";
1051
1052                 key "id";
1053                 leaf id {
1054                     description "A unique ID for the contract";
1055                     type gbp-common:contract-id;
1056                     mandatory true;
1057                 }
1058
1059                 leaf description {
1060                     description
1061                         "A human-readable description for the contract.";
1062                     type gbp-common:description;
1063                 }
1064
1065                 // *******
1066                 // Relator
1067                 // *******
1068
1069                 uses has-qualities;
1070
1071                 list target {
1072                     description
1073                         "Targets on a contract allow grouping sets of qualities
1074                          together, as well as providing a namespace for
1075                          the qualities that are matched.";
1076
1077                     key "name";
1078                     leaf name {
1079                         description
1080                             "The name for this target.  This can also be used
1081                              by quality matchers as a namespace for qualities.";
1082                         type gbp-common:target-name;
1083                         mandatory true;
1084                     }
1085
1086                     uses relator;
1087                     uses has-qualities;
1088                 }
1089
1090                 // ********************
1091                 // Clauses and subjects
1092                 // ********************
1093
1094                 list subject {
1095                     description
1096                         "Subjects define rules to allow traffic to flow
1097                          between endpoints in different endpoint
1098                          groups.  No communication is allowed unless a
1099                          subject allows that communication.
1100
1101                          After a contract has been selected, clauses
1102                          in that contract match against the
1103                          requirements, capabilities, and conditions
1104                          that apply to the endpoints or endpoint
1105                          groups that are participating in the
1106                          contract.  Clauses that match each point to a
1107                          subject which then becomes active.
1108
1109                          An active subject can then apply its rules to
1110                          the traffic between the endpoints.";
1111
1112                     key "name";
1113                     leaf name {
1114                         description "A name for the subject";
1115                         type gbp-common:subject-name;
1116                         mandatory true;
1117                     }
1118
1119                     list rule {
1120                         description
1121                             "A rule is applied to traffic between
1122                              endpoints in different endpoint groups.
1123                              Rules match against the traffic using
1124                              classifiers, and then apply actions to
1125                              the traffic for matching rules.
1126
1127                              Rules are applied in order according to
1128                              their order parameter.  Only the first
1129                              matching rule will apply.  When multiple
1130                              subjects are active, the order on each
1131                              subject will determine which subjects are
1132                              applied first, and all their rules will
1133                              take effect before the rules of any
1134                              subjects with a higher order value.  When
1135                              subjects have the same order value, then
1136                              they will apply in lexicographic order by
1137                              subject name.";
1138
1139                         key "name";
1140                         leaf name {
1141                             description "A name for the rule";
1142                             type gbp-common:rule-name;
1143                             mandatory true;
1144                         }
1145
1146                         uses has-classifier-refs;
1147                         uses has-action-refs;
1148                         uses has-order;
1149                     }
1150
1151                     uses has-order;
1152                 }
1153
1154                 list clause {
1155                     description
1156                         "Clauses are used to determine which subjects are
1157                          active once a contract is selected using the
1158                          contract selectors.
1159
1160                          Clauses are activated by matching against
1161                          requirements on the consumer endpoint group,
1162                          capabilities on the provider endpoint group, and
1163                          conditions on the individual endpoints in the
1164                          endpoint group.";
1165
1166                     key "name";
1167                     leaf name {
1168                         type gbp-common:clause-name;
1169                         mandatory true;
1170                     }
1171
1172                     // ********
1173                     // Matchers
1174                     // ********
1175
1176                     container consumer-matchers {
1177                         description
1178                             "Matchers that apply to the consumer endpoint
1179                              group.";
1180                         list requirement-matcher {
1181                             description
1182                                 "Match against requirements in the consumer
1183                                  endpoint group.";
1184
1185                             key "name";
1186                             leaf name {
1187                                 description
1188                                     "A name for the requirement matcher";
1189                                 type gbp-common:requirement-matcher-name;
1190                                 mandatory true;
1191                             }
1192
1193                             uses matcher;
1194                             list matcher-requirement {
1195                                 description
1196                                     "A matcher requirement is a
1197                                      requirement with a selector name
1198                                      field used in requirement
1199                                      matchers.  The name of the
1200                                      matcher requirement matches
1201                                      against requirements in endpoint
1202                                      groups.";
1203
1204                                 key name;
1205                                 uses requirement-base;
1206
1207                                 leaf selector-namespace {
1208                                     description
1209                                         "The name of the selector to
1210                                          match.  This allows us to
1211                                          specify that we want to match
1212                                          only requirements scoped to a
1213                                          particular selector name.
1214
1215                                          This parameter is optional;
1216                                          if not specified, use an
1217                                          inherited selector namespace
1218                                          if it exists, or match
1219                                          against any selector name.";
1220
1221                                     type gbp-common:selector-name;
1222                                 }
1223                             }
1224                         }
1225                         uses has-condition-matchers;
1226                     }
1227
1228                     container provider-matchers {
1229                         description
1230                             "Matchers that apply to the provider endpoint
1231                              group";
1232
1233                         list capability-matcher {
1234                             description
1235                                 "Match against capabilities in the provider
1236                                  endpoint group.";
1237
1238                             key "name";
1239                             leaf name {
1240                                 description
1241                                     "A name for the capability matcher";
1242                                 type gbp-common:capability-matcher-name;
1243                                 mandatory true;
1244                             }
1245
1246                             uses matcher;
1247
1248                             list matcher-capability {
1249                                 description
1250                                     "A matcher capability is a
1251                                      capability with a selector
1252                                      name field used in capability
1253                                      mat  chers.  The name of the
1254                                      matcher capability matches
1255                                      against capabilities in
1256                                      endpoint groups.";
1257
1258                                 key name;
1259                                 uses capability-base;
1260
1261                                 leaf selector-namespace {
1262                                     description
1263                                         "The name of the selector to
1264                                          match.  This allows us to
1265                                          specify that we want to match
1266                                          only capabilities scoped to a
1267                                          particular selector name.
1268
1269                                          This parameter is optional;
1270                                          if not specified, use an
1271                                          inherited selector namespace
1272                                          if it exists, or match
1273                                          against any selector name.";
1274
1275                                     type gbp-common:selector-name;
1276                                 }
1277                             }
1278                         }
1279                         uses has-condition-matchers;
1280                     }
1281
1282                     // ******************
1283                     // Subject References
1284                     // ******************
1285
1286                     leaf-list subject-refs {
1287                         description
1288                             "The subjects that will be activated if this
1289                              clause matches.";
1290
1291                         type leafref {
1292                             path "/tenants/tenant/contract/subject/name";
1293                         }
1294                     }
1295                 }
1296
1297                 // ***********
1298                 // Inheritance
1299                 // ***********
1300
1301                 leaf parent {
1302                     description "Parent contract from which we inherit";
1303
1304                     type leafref {
1305                         path "/tenants/tenant/contract/id";
1306                     }
1307                 }
1308             }
1309
1310             list contract-ref {
1311                 description
1312                     "Contract references allow forming contracts
1313                      between endpoint groups in different tenants.
1314                      Once the contract reference is created, it is
1315                      then possible to match against the contract using
1316                      selectors as though it were a local tenant.
1317
1318                      Endpoint groups in the local tenant can serve
1319                      only as consumers of the contract.  Once the
1320                      contract is matched, consumer matchers will apply
1321                      to requirements and conditions in the local
1322                      tenant, and provider matchers will apply against
1323                      capabilities and conditions in the referenced
1324                      tenant.";
1325
1326                 key contract-id;
1327
1328                 leaf tenant-id {
1329                     description
1330                         "The tenant ID of the tenant containing the
1331                          contract.";
1332                     type leafref {
1333                         path "/tenants/tenant/id";
1334                     }
1335                 }
1336                 leaf contract-id {
1337                     description "The contract ID of the contract.";
1338
1339                     type leafref {
1340                         path "/tenants/tenant/contract/id";
1341                     }
1342                 }
1343             }
1344         }
1345     }
1346 }