2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
12 namespace "urn:opendaylight:groupbasedpolicy:policy";
15 import gbp-common {prefix gbp-common;}
16 import ietf-inet-types {prefix inet;}
19 "This module defines the group-based policy configuration
22 revision "2014-04-21" {
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,
40 description "A human-readable description for the label";
41 type gbp-common:description;
44 description "Specify how inheritance will work for this label";
50 "This label will be included normally in the
55 "This label will be excluded from the
56 matching. This allows removing labels that
57 would have otherwise been included because of
64 grouping quality-base {
65 description "Base type for qualities and matcher qualities.";
67 description "A user-visible name for the quality";
68 type gbp-common:quality-name;
74 grouping has-qualities {
75 description "An object with a list of qualities";
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.
84 Contracts are matched to provider and consumer
85 endpoint groups based on the selectors in those
86 endpoint groups that match the quality.
88 Qualities for a contract are inherited from the
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.";
101 grouping requirement-base {
102 description "Base type for requirements and matcher requirements.";
104 description "A user-visible name for the requirement";
105 type gbp-common:requirement-name;
111 grouping has-requirements {
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.
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.
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.";
132 uses requirement-base;
136 grouping capability-base {
137 description "Base type for capabilities and matcher capabilities.";
139 description "A user-visible name for the capability";
140 type gbp-common:capability-name;
146 grouping has-capabilities {
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
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.
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.";
168 uses capability-base;
172 grouping has-conditions {
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.";
185 description "A user-visible name for the condition";
186 type gbp-common:condition-name;
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
203 "Specify how many of the labels must match. If not
204 specified, defaults to 'all'.";
208 "All specified labels must match.";
212 "At least one of the specified labels must match.";
216 "None of the specified labels can match.";
222 grouping has-condition-matchers {
223 description "Objects with condition matchers";
224 list condition-matcher {
225 description "Match against conditions on endpoints.";
230 "A name for the condition matcher";
231 type gbp-common:condition-matcher-name;
240 // ************************
241 // Network domains grouping
242 // ************************
244 grouping network-domain {
246 "A base type for network domains. Network domains
247 represent some logical grouping or namespace of
251 "A human-readable name for the network domain.";
252 type gbp-common:name;
256 "A human-readable description for the context.";
257 type gbp-common:description;
261 grouping forwarding-context {
262 description "A base type for forwarding contexts.";
266 grouping l2-context {
268 "A base type for layer 2 contexts. Layer 2 contexts
269 represent a namespace or logical grouping of layer 2
272 uses forwarding-context;
275 // ************************
276 // Endpoint group groupings
277 // ************************
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.";
287 grouping selection-relator {
289 "Selection relators allow endpoint groups to select
290 contracts based on their name or on their qualities.";
294 description "A name for the selector";
295 type gbp-common:selector-name;
300 grouping consumer-selection-relator {
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;
309 grouping provider-selection-relator {
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;
318 grouping named-selector {
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.
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.";
334 description "Specific contracts to select.";
336 path "/tenants/tenant/contract/id";
341 grouping target-selector {
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.
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
357 list quality-matcher {
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
368 description "A unique name for the quality matcher";
369 type gbp-common:quality-matcher-name;
375 list matcher-quality {
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
385 leaf target-namespace {
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.
391 This parameter is optional; if not specified,
392 use an inherited target name if it exists, or
393 match against any target name.";
395 type gbp-common:target-name;
401 // ******************
402 // Contract groupings
403 // ******************
405 grouping has-direction {
406 description "Object that have a directionality.";
408 default bidirectional;
412 "Applies to traffic into provider endpoint group";
416 "Applies to traffic out of provider endpoint group";
420 "Applies to traffic in both directions";
426 grouping subject-feature-instance {
428 "Specific instances of subject features with
429 parameters filled in.";
430 list parameter-value {
433 type gbp-common:parameter-name;
442 container range-value {
456 description "Objects containing an order parameter";
459 "Specify the ordering of an ordered list
467 grouping has-classifier-refs {
468 description "Objects containing lists of classifier references";
470 list classifier-ref {
473 "A reference to classifier instance that is used to match
474 traffic traveling between the endpoint groups that
478 description "A unique name for this classifier reference";
479 type gbp-common:classifier-name;
484 description "The name of the classifier instance";
486 path "/tenants/tenant/subject-feature-instances/classifier-instance/name";
491 leaf connection-tracking {
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.";
504 "Match only traffic matching the classifier
509 "Additionally match reverse traffic for
519 grouping has-action-refs {
520 description "Objects containing lists of action references";
524 "A reference to an action defined in the subject
525 feature instances for the tenant.";
528 description "The name of the action instance";
530 path "/tenants/tenant/subject-feature-instances/action-instance/name";
538 grouping subject-feature-definition {
540 "Base type for subject feature definitions.";
543 description "A user-readable description";
544 type gbp-common:description;
549 "A parameter for the feature that can be
553 description "A user-visible name for the parameter";
554 type gbp-common:parameter-name;
559 "A user-visible description of the meaning of
561 type gbp-common:description;
564 description "The type of the parameter";
568 description "A string-valued parameter";
571 description "An integer-valued parameter";
574 description "An integer-range parameter";
579 description "Specify whether the parameter is
580 required for correct operation.";
584 description "The parameter is required";
587 description "The parameter is optional";
593 leaf fallback-behavior {
595 "Set the behavior when the underlying infrastructure
596 is unable to support a particular feature.";
600 "A fatal exception MUST be raised which will
601 render the enclosing subject inactive.";
603 enum allow-fallback {
605 "The infrastructure MAY fall back to using
606 a parent definition of this feature, and
607 instread raise a nonfatal exception.";
613 // ********************
614 // Global Configuration
615 // ********************
617 container subject-feature-definitions {
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
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.";
639 list classifier-definition {
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
648 uses subject-feature-definition;
651 description "A unique ID for the classifier definition";
652 type gbp-common:classifier-definition-id;
658 "A user-visible name for the classifier definition";
659 type gbp-common:classifier-name;
664 "Parent classifier definition from which we inherit";
666 path "/subject-feature-definitions/classifier-definition/id";
671 list action-definition {
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
679 uses subject-feature-definition;
682 description "A unique ID for the action";
683 type gbp-common:action-definition-id;
688 description "A user-visible name for the action";
689 type gbp-common:action-name;
694 "Parent action definition from which we inherit";
696 path "/subject-feature-definitions/action-definition/id";
707 description "The list of all known tenants";
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";
719 description "A unique ID for the tenant";
721 type gbp-common:tenant-id;
724 description "A user-visible name for the tenant";
725 type gbp-common:name;
728 description "A user-readable description for the tenant";
729 type gbp-common: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.";
743 uses forwarding-context;
747 "A unique ID for the layer 3 context";
748 type gbp-common:l3-context-id;
752 list l2-bridge-domain {
754 "A layer 2 bridge domain represents a domain in which
755 layer 2 communication is possible when allowed by policy.";
760 description "A unique ID for the bridge domain";
761 type gbp-common:l2-bridge-domain-id;
766 "The layer 3 context that contains this bridge domain";
768 path "/tenants/tenant/l3-context/id";
773 list l2-flood-domain {
775 "A layer 2 flood domain represents a domain in which
776 layer 2 broadcast and multicast is allowed.";
781 description "A unique ID for the flood domain";
782 type gbp-common:l2-flood-domain-id;
787 "The bridge domain that contains this flood domain";
789 path "/tenants/tenant/l2-bridge-domain/id";
796 "An IP subnet associated with a layer 2 or layer 3
802 description "A unique ID for the subnet";
803 type gbp-common:subnet-id;
808 "The forwarding context that contains this subnet";
809 type gbp-common:context-id;
813 description "The IP prefix that defines the subnet";
816 leaf virtual-router-ip {
818 "IP address to use for a virtual gateway router
819 for the subnet, if desired.";
820 type inet:ip-address;
828 list endpoint-group {
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
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.
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.
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.";
869 type gbp-common:endpoint-group-id;
874 "A user-visible name for the endpoint group";
875 type gbp-common:name;
879 "A human-readable description for the endpoint
881 type gbp-common:description;
883 uses has-requirements;
884 uses has-capabilities;
886 leaf intra-group-policy {
888 "Governs how traffic within the endpoint group
894 "Traffic between two endpoints in the group
897 enum require-contract {
899 "Traffic between two endpoints in the group
900 is allowed only when a contract exists to
901 allow it explicitly";
906 list consumer-named-selector {
908 "Consumer named selectors are named selectors
909 that select contracts to meet the
910 requirements of the endpoint group.
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.";
920 uses consumer-selection-relator;
923 list provider-named-selector {
925 "Provider named selectors are named selectors
926 that select contracts to provide capabilties
927 to other endpoint group.
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
937 uses provider-selection-relator;
940 list consumer-target-selector {
942 "Consumer target selectors are target selectors
943 that select contracts to meet the requirements
944 of the endpoint group.
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.";
954 uses target-selector;
955 uses consumer-selection-relator;
958 list provider-target-selector {
960 "Provider target selectors are target selectors
961 that select contracts to provide capabilties
962 to other endpoint group.
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.";
972 uses target-selector;
973 uses provider-selection-relator;
976 leaf network-domain {
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;
986 "Parent endpoint group from which we inherit";
989 path "/tenants/tenant/endpoint-group/id";
994 // *************************
995 // Subject feature instances
996 // *************************
998 container subject-feature-instances {
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.";
1005 list classifier-instance {
1010 description "A name for the classifier instance";
1011 type gbp-common:classifier-name;
1014 leaf classifier-definition-id {
1016 path "/subject-feature-definitions/classifier-definition/id";
1019 uses subject-feature-instance;
1022 list action-instance {
1027 description "A name for the action instance";
1028 type gbp-common:action-name;
1031 leaf action-definition-id {
1033 path "/subject-feature-definitions/action-definition/id";
1036 uses subject-feature-instance;
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.";
1053 description "A unique ID for the contract";
1054 type gbp-common:contract-id;
1060 "A human-readable description for the contract.";
1061 type gbp-common: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.";
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;
1089 // ********************
1090 // Clauses and subjects
1091 // ********************
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.
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.
1108 An active subject can then apply its rules to
1109 the traffic between the endpoints.";
1113 description "A name for the subject";
1114 type gbp-common:subject-name;
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.
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
1140 description "A name for the rule";
1141 type gbp-common:rule-name;
1145 uses has-classifier-refs;
1146 uses has-action-refs;
1155 "Clauses are used to determine which subjects are
1156 active once a contract is selected using the
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
1167 type gbp-common:clause-name;
1175 container consumer-matchers {
1177 "Matchers that apply to the consumer endpoint
1179 list requirement-matcher {
1181 "Match against requirements in the consumer
1187 "A name for the requirement matcher";
1188 type gbp-common:requirement-matcher-name;
1193 list matcher-requirement {
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
1204 uses requirement-base;
1206 leaf selector-namespace {
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.
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.";
1220 type gbp-common:selector-name;
1224 uses has-condition-matchers;
1227 container provider-matchers {
1229 "Matchers that apply to the provider endpoint
1232 list capability-matcher {
1234 "Match against capabilities in the provider
1240 "A name for the capability matcher";
1241 type gbp-common:capability-matcher-name;
1247 list matcher-capability {
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
1258 uses capability-base;
1260 leaf selector-namespace {
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.
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.";
1274 type gbp-common:selector-name;
1278 uses has-condition-matchers;
1281 // ******************
1282 // Subject References
1283 // ******************
1285 leaf-list subject-refs {
1287 "The subjects that will be activated if this
1291 path "/tenants/tenant/contract/subject/name";
1301 description "Parent contract from which we inherit";
1304 path "/tenants/tenant/contract/id";
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.
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
1327 "The tenant ID of the tenant containing the
1330 path "/tenants/tenant/contract/id";
1334 description "The contract ID of the contract.";
1337 path "/tenants/tenant/contract/id";