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 {
18 revision-date 2010-09-24;
22 "This module defines the group-based policy configuration
25 revision "2014-04-21" {
36 "Labels are used for matching contracts to endpoint groups
37 through selectors and targets, as well as determining how
38 those contracts will be applied. See more detailed
39 documentation for qualities, conditions, requirements,
43 description "A human-readable description for the label";
44 type gbp-common:description;
47 description "Specify how inheritance will work for this label";
53 "This label will be included normally in the
58 "This label will be excluded from the
59 matching. This allows removing labels that
60 would have otherwise been included because of
67 grouping quality-base {
68 description "Base type for qualities and matcher qualities.";
70 description "A user-visible name for the quality";
71 type gbp-common:quality-name;
77 grouping has-qualities {
78 description "An object with a list of qualities";
81 "A quality is a label which selects which selects the
82 contracts that are in scope. Another name for
83 'quality' could be 'attribute' or 'characteristic.'
84 Qualities can be scoped to either a specific contract
85 or to a target within that contract.
87 Contracts are matched to provider and consumer
88 endpoint groups based on the selectors in those
89 endpoint groups that match the quality.
91 Qualities for a contract are inherited from the
94 Qualities for a target with a given name are
95 inherited both from the enclosing parent contract and
96 from any targets with the same name within the
97 enclosing parent contract.";
104 grouping requirement-base {
105 description "Base type for requirements and matcher requirements.";
107 description "A user-visible name for the requirement";
108 type gbp-common:requirement-name;
114 grouping has-requirements {
117 "A requirement is a label that, along with capabilities,
118 selects how contracts are applied by selecting the
119 applicable subjects within that contract.
120 Requirements represent the fact that an endpoint
121 group requires that some specific functionality be
122 provided to it in order to function.
124 Requirements scoped to an endpoint group (as well as
125 any parent endpoint groups) are inherited by all of
126 that group's contract selectors. Contract selectors
127 also inherit requirements from any contract selectors
128 in the parent groups that have with matching names.
130 Note that requirements play no role in choosing which
131 contracts apply; they only affect how the contracts
132 that are chosen will be interpreted.";
135 uses requirement-base;
139 grouping capability-base {
140 description "Base type for capabilities and matcher capabilities.";
142 description "A user-visible name for the capability";
143 type gbp-common:capability-name;
149 grouping has-capabilities {
152 "A capability is a label that, along with requirements,
153 selects how contracts are applied by selecting the
154 applicable subjects within that contract.
155 Capabilities are specific pieces of functionality
156 that can be exposed to other endpoint groups that may
157 meet functional requirements of those endpoint
160 Capabilities scoped to an endpoint group (as well as
161 any parent endpoint groups) are inherited by all of
162 that group's contract selectors. Contract selectors
163 also inherit capabilities from any contract selectors
164 in the parent groups that have matching names.
166 Note that capabilities play no role in choosing which
167 contracts apply; they only affect how the contracts
168 that are chosen will be interpreted.";
171 uses capability-base;
175 grouping has-conditions {
178 "A condition is a state label for endpoints that can
179 change over time. As conditions change for certain
180 endpoints, this can affect which subjects are in
181 scope as determined by how the clauses in the
182 contract match against the requirements and
183 capabilities for the endpoint group, and the
184 conditions for the endpoints.";
188 description "A user-visible name for the condition";
189 type gbp-common:condition-name;
198 "A matcher allows matching against labels. This is used
199 to both to match contracts to endpoint groups by matching
200 on qualities, and then to match against subjects in the
201 contract by matching on requirements, capabilities, and
206 "Specify how many of the labels must match. If not
207 specified, defaults to 'all'.";
211 "All specified labels must match.";
215 "At least one of the specified labels must match.";
219 "None of the specified labels can match.";
225 grouping has-condition-matchers {
226 description "Objects with condition matchers";
227 list condition-matcher {
228 description "Match against conditions on endpoints.";
233 "A name for the condition matcher";
234 type gbp-common:condition-matcher-name;
243 grouping has-endpoint-identification-constraints {
244 container endpoint-identification-constraints {
246 "Identify endpoints via other attributes other than conditions.
247 These can be things such as ip-prefix, vlan, mpls label etc. These
248 things are intended to be explicity stated, and should not contain
249 references to other objects like endpointsIDs.";
250 container l3-endpoint-identification-constraints {
251 list prefix-constraint {
261 // ************************
262 // Network domains grouping
263 // ************************
265 grouping network-domain {
267 "A base type for network domains. Network domains
268 represent some logical grouping or namespace of
272 "A human-readable name for the network domain.";
273 type gbp-common:name;
277 "A human-readable description for the context.";
278 type gbp-common:description;
282 grouping forwarding-context {
283 description "A base type for forwarding contexts.";
287 grouping l2-context {
289 "A base type for layer 2 contexts. Layer 2 contexts
290 represent a namespace or logical grouping of layer 2
293 uses forwarding-context;
296 // ************************
297 // Endpoint group groupings
298 // ************************
302 "Relators allow contracts and endpoint groups to be related
303 to each other through a matching process. See target,
304 selection-relator, target-selector, and named-selector
305 for more information.";
308 grouping selection-relator {
310 "Selection relators allow endpoint groups to select
311 contracts based on their name or on their qualities.";
315 description "A name for the selector";
316 type gbp-common:selector-name;
321 grouping consumer-selection-relator {
323 "A selection relator for matching contracts to meet
324 endpoint group requirements. See consumer-named-selector
325 and consumer-target-selector for more details.";
326 uses selection-relator;
327 uses has-requirements;
330 grouping provider-selection-relator {
332 "A selection relator for matching contracts to meet
333 endpoint group requirements. See provider-named-selector
334 and provider-named-selector for more details.";
335 uses selection-relator;
336 uses has-capabilities;
339 grouping named-selector {
341 "A named selector selects a contract based on the name of
342 the contract. Once the contract is selected, the
343 requirements and capabilities are used to select specific
344 subjects within that contract. Named selectors are the
345 simplest way to select a contract. If you need a more
346 advanced selector, see the target selector.
348 There are two kinds of named selector: consumer named
349 selectors and provider named selectors. Consumer named
350 selectors select contracts to meet requirements for the
351 endpoint group, and provider named selectors select
352 contracts to provide capabilities for the endpoint group.";
355 description "Specific contracts to select.";
357 path "/tenants/tenant/contract/id";
362 grouping target-selector {
364 "Target selectors select contracts for the endpoint group.
365 First, the quality matchers are used to select the
366 contracts. Then, the requirements and capabilities are
367 used to select specific subjects within that contract.
368 Target selectors are an advanced method for selecting
369 contracts; for a simpler method, see the named selector.
371 There are two kinds of target selectors: consumer target
372 selectors and provider target selectors. Consumer target
373 selectors select contracts to meet requirements for the
374 endpoint group, and provider target selectors select
375 contracts to provide capabilities to other endpoint
378 list quality-matcher {
380 "A quality matcher is used in a target selector to
381 match against the qualities in a contract target.
382 You can specify a list of qualities to match against.
383 You can choose whether all qualities listed must
384 match or if a match can be made with any of the
389 description "A unique name for the quality matcher";
390 type gbp-common:quality-matcher-name;
396 list matcher-quality {
398 "A matcher quality is a quality with a target name
399 field used in quality matchers. The name of the
400 matcher quality matches against qualities in
406 leaf target-namespace {
408 "The name of the target to match. This allows
409 us to specify that we want to match only
410 qualities scoped to a particular target name.
412 This parameter is optional; if not specified,
413 use an inherited target name if it exists, or
414 match against any target name.";
416 type gbp-common:target-name;
422 // ******************
423 // Contract groupings
424 // ******************
426 grouping has-direction {
427 description "Object that have a directionality.";
429 default bidirectional;
433 "Applies to traffic into provider endpoint group";
437 "Applies to traffic out of provider endpoint group";
441 "Applies to traffic in both directions";
447 grouping subject-feature-instance {
449 "Specific instances of subject features with
450 parameters filled in.";
451 list parameter-value {
454 type gbp-common:parameter-name;
463 container range-value {
477 description "Objects containing an order parameter";
480 "Specify the ordering of an ordered list
488 grouping has-classifier-refs {
489 description "Objects containing lists of classifier references";
491 list classifier-ref {
494 "A reference to classifier instance that is used to match
495 traffic traveling between the endpoint groups that
499 description "A unique name for this classifier reference";
500 type gbp-common:classifier-name;
505 description "The name of the classifier instance";
507 path "/tenants/tenant/subject-feature-instances/classifier-instance/name";
512 leaf connection-tracking {
514 "Set up connection tracking for this classifier,
515 which allows the traffic in the reverse direction
516 as connections are established. This enables
517 rules that allow connections to be initiated only
518 from one side, but once initiated the two sides
519 can communicate for that connection.";
525 "Match only traffic matching the classifier
530 "Additionally match reverse traffic for
540 grouping has-action-refs {
541 description "Objects containing lists of action references";
545 "A reference to an action defined in the subject
546 feature instances for the tenant.";
550 description "The name of the action instance";
552 path "/tenants/tenant/subject-feature-instances/action-instance/name";
560 grouping subject-feature-definition {
562 "Base type for subject feature definitions.";
565 description "A user-readable description";
566 type gbp-common:description;
571 "A parameter for the feature that can be
575 description "A user-visible name for the parameter";
576 type gbp-common:parameter-name;
581 "A user-visible description of the meaning of
583 type gbp-common:description;
586 description "The type of the parameter";
590 description "A string-valued parameter";
593 description "An integer-valued parameter";
596 description "An integer-range parameter";
601 description "Specify whether the parameter is
602 required for correct operation.";
606 description "The parameter is required";
609 description "The parameter is optional";
615 leaf fallback-behavior {
617 "Set the behavior when the underlying infrastructure
618 is unable to support a particular feature.";
622 "A fatal exception MUST be raised which will
623 render the enclosing subject inactive.";
625 enum allow-fallback {
627 "The infrastructure MAY fall back to using
628 a parent definition of this feature, and
629 instread raise a nonfatal exception.";
635 // ********************
636 // Global Configuration
637 // ********************
639 container subject-feature-definitions {
641 "Contains configuration for the set of actions and
642 classifiers that can be defined for a subject. This is
643 be specific to the capabilities of the underlying
644 infrastructure, so the policy model does not define the
647 The definitions here provide a generic parameterized base
648 that can be extended by more specific definitions.
649 Extensions must apply all the semantics from their parent
650 object as well as any additional semantics. If the
651 underlying infrastructure is unable to support a
652 particular feature, it MUST trigger an exception that
653 will render the enclosing subject inactive until the
654 exception is resolved. If the fallback-behavior
655 parameter is set to 'allow-fallback', the infrastructure
656 MAY instead apply the parent subject feature and instead
657 raise a nonfatal exception.";
661 list classifier-definition {
663 "A classifier is used to match traffic traveling between
664 the endpoint groups that form the contract.
665 Classifier definitions can define parameters that
666 will need to be filled in when a particular rule
670 uses subject-feature-definition;
673 description "A unique ID for the classifier definition";
674 type gbp-common:classifier-definition-id;
680 "A user-visible name for the classifier definition";
681 type gbp-common:classifier-name;
686 "Parent classifier definition from which we inherit";
688 path "/subject-feature-definitions/classifier-definition/id";
693 list action-definition {
695 "A action to be applied to traffic across endpoint
696 groups. Action definitions can define parameters
697 that will need to be filled in when a particular rule
701 uses subject-feature-definition;
704 description "A unique ID for the action";
705 type gbp-common:action-definition-id;
710 description "A user-visible name for the action";
711 type gbp-common:action-name;
716 "Parent action definition from which we inherit";
718 path "/subject-feature-definitions/action-definition/id";
729 description "The list of all known tenants";
735 "A tenant is a domain of administration which is
736 logically separate from other tenants. Most policy
737 is defined in the context of a particular tenant";
741 description "A unique ID for the tenant";
743 type gbp-common:tenant-id;
746 description "A user-visible name for the tenant";
747 type gbp-common:name;
750 description "A user-readable description for the tenant";
751 type gbp-common:description;
760 "A layer 3 context represents a namespace for layer 3
761 addresses. It represents a domain inside which endpoints
762 can communicate with requiring any address translation.";
765 uses forwarding-context;
769 "A unique ID for the layer 3 context";
770 type gbp-common:l3-context-id;
774 list l2-bridge-domain {
776 "A layer 2 bridge domain represents a domain in which
777 layer 2 communication is possible when allowed by policy.";
782 description "A unique ID for the bridge domain";
783 type gbp-common:l2-bridge-domain-id;
788 "The layer 3 context that contains this bridge domain";
790 path "/tenants/tenant/l3-context/id";
795 list l2-flood-domain {
797 "A layer 2 flood domain represents a domain in which
798 layer 2 broadcast and multicast is allowed.";
803 description "A unique ID for the flood domain";
804 type gbp-common:l2-flood-domain-id;
809 "The bridge domain that contains this flood domain";
811 path "/tenants/tenant/l2-bridge-domain/id";
818 "An IP subnet associated with a layer 2 or layer 3
824 description "A unique ID for the subnet";
825 type gbp-common:subnet-id;
830 "The forwarding context that contains this subnet";
831 type gbp-common:context-id;
835 description "The IP prefix that defines the subnet";
838 leaf virtual-router-ip {
840 "IP address to use for a virtual gateway router
841 for the subnet, if desired.";
842 type inet:ip-address;
846 "External gateways for subnets we serve,
847 includes prefixes for static routing";
850 type inet:ip-address;
866 list endpoint-group {
868 "Endpoint groups are sets of endpoints that share a
869 common set of policies. Endpoint groups are
870 matched to contracts using selectors, contracts
871 determine which endpoints can communicate and in
874 Endpoint groups have both requirements and
875 capabilities, which represent specific pieces of
876 functionality that are exposed at the boundary of
877 those groups. Requirements represent some
878 specific functionality that is needed for the
879 endpoints in the endpoint group to function.
880 Correspondingly, capabilities are pieces of
881 functionality that the endpoints in the endpoint
882 group can provide to other endpoints.
884 Contracts can be selected through either a named
885 selector, which matches specific contracts by
886 name, or by a target selector which will match
887 contracts by matching its list of qualities to
888 the list of qualities for a target on the
889 contract. The contract selectors choose which
890 contracts are in scope. Note that requirements
891 and capabilities are not used when choosing which
892 contracts are in scope; these are used to
893 determine how a contract will be interpreted.
895 There are two broad category of selectors:
896 provider selectors and consumer selectors. The
897 provider selectors allow selecting contracts that
898 allow the endpoint group to expose its
899 capabilities. The consumer selectors allow
900 selecting contracts which allow the endpoint
901 group to meet its requirements.";
907 type gbp-common:endpoint-group-id;
912 "A user-visible name for the endpoint group";
913 type gbp-common:name;
917 "A human-readable description for the endpoint
919 type gbp-common:description;
921 uses has-requirements;
922 uses has-capabilities;
924 leaf intra-group-policy {
926 "Governs how traffic within the endpoint group
932 "Traffic between two endpoints in the group
935 enum require-contract {
937 "Traffic between two endpoints in the group
938 is allowed only when a contract exists to
939 allow it explicitly";
944 list consumer-named-selector {
946 "Consumer named selectors are named selectors
947 that select contracts to meet the
948 requirements of the endpoint group.
950 The consumer named selector selects a
951 contract based on the name of the contract.
952 Once the contract is selected, the
953 requirements are used to select specific
954 subjects within that contract.";
958 uses consumer-selection-relator;
961 list provider-named-selector {
963 "Provider named selectors are named selectors
964 that select contracts to provide capabilties
965 to other endpoint group.
967 The provider named selector selects a
968 contract based on the name of the contract.
969 Once the contract is selected, the capabilies
970 are used to select specific subjects within
975 uses provider-selection-relator;
978 list consumer-target-selector {
980 "Consumer target selectors are target selectors
981 that select contracts to meet the requirements
982 of the endpoint group.
984 The consumer target selector selects a
985 contract using the quality matchers to match
986 against the qualities specified on the
987 contract targets. Once the contract is
988 selected, the requirements are used to select
989 specific subjects within that contract.";
992 uses target-selector;
993 uses consumer-selection-relator;
996 list provider-target-selector {
998 "Provider target selectors are target selectors
999 that select contracts to provide capabilties
1000 to other endpoint group.
1002 The provider target selector selects a
1003 contract using the quality matchers to match
1004 against the qualities specified on the
1005 contract targets. Once the contract is
1006 selected, the capabilities are used to select
1007 specific subjects within that contract.";
1010 uses target-selector;
1011 uses provider-selection-relator;
1014 leaf network-domain {
1016 "The network domain associated with this endpoint
1017 group. The network domain controls which endpoints
1018 are addressible by the endpoints in the group.";
1019 type gbp-common:network-domain-id;
1024 "Parent endpoint group from which we inherit";
1027 path "/tenants/tenant/endpoint-group/id";
1032 list external-implicit-group {
1040 type gbp-common:endpoint-group-id;
1042 // Fields to be determined and completed before Code Freeze
1045 // *************************
1046 // Subject feature instances
1047 // *************************
1049 container subject-feature-instances {
1051 "Contains instances of subject features. Subject
1052 feature instances reference a subject feature
1053 definition but fill in the required parameters so
1054 that they can be easily references elsewhere.";
1056 list classifier-instance {
1061 description "A name for the classifier instance";
1062 type gbp-common:classifier-name;
1065 leaf classifier-definition-id {
1067 path "/subject-feature-definitions/classifier-definition/id";
1070 uses subject-feature-instance;
1073 list action-instance {
1078 description "A name for the action instance";
1079 type gbp-common:action-name;
1082 leaf action-definition-id {
1084 path "/subject-feature-definitions/action-definition/id";
1087 uses subject-feature-instance;
1097 "Contracts contain a set of subjects that describe
1098 the communication allowed between endpoints in
1099 endpoint groups. Contracts are matched to endpoint
1100 groups by selectors.";
1104 description "A unique ID for the contract";
1105 type gbp-common:contract-id;
1111 "A human-readable description for the contract.";
1112 type gbp-common:description;
1123 "Targets on a contract allow grouping sets of qualities
1124 together, as well as providing a namespace for
1125 the qualities that are matched.";
1130 "The name for this target. This can also be used
1131 by quality matchers as a namespace for qualities.";
1132 type gbp-common:target-name;
1140 // ********************
1141 // Clauses and subjects
1142 // ********************
1146 "Subjects define rules to allow traffic to flow
1147 between endpoints in different endpoint
1148 groups. No communication is allowed unless a
1149 subject allows that communication.
1151 After a contract has been selected, clauses
1152 in that contract match against the
1153 requirements, capabilities, and conditions
1154 that apply to the endpoints or endpoint
1155 groups that are participating in the
1156 contract. Clauses that match each point to a
1157 subject which then becomes active.
1159 An active subject can then apply its rules to
1160 the traffic between the endpoints.";
1164 description "A name for the subject";
1165 type gbp-common:subject-name;
1171 "A rule is applied to traffic between
1172 endpoints in different endpoint groups.
1173 Rules match against the traffic using
1174 classifiers, and then apply actions to
1175 the traffic for matching rules.
1177 Rules are applied in order according to
1178 their order parameter. Only the first
1179 matching rule will apply. When multiple
1180 subjects are active, the order on each
1181 subject will determine which subjects are
1182 applied first, and all their rules will
1183 take effect before the rules of any
1184 subjects with a higher order value. When
1185 subjects have the same order value, then
1186 they will apply in lexicographic order by
1191 description "A name for the rule";
1192 type gbp-common:rule-name;
1196 uses has-classifier-refs;
1197 uses has-action-refs;
1206 "Clauses are used to determine which subjects are
1207 active once a contract is selected using the
1210 Clauses are activated by matching against
1211 requirements on the consumer endpoint group,
1212 capabilities on the provider endpoint group, and
1213 conditions on the individual endpoints in the
1217 type gbp-common:clause-name;
1224 container consumer-matchers {
1226 "Matchers that apply to the consumer endpoint
1229 // GIC mutually OR'd within role
1230 choice group-identification-constraints {
1231 description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";
1233 case group-name-constraint-case {
1234 list group-name-constraint {
1235 key endpoint-group-name;
1236 leaf endpoint-group-name {
1237 type gbp-common:name;
1241 case group-requirement-constraint-case {
1242 list requirement-matcher {
1244 "Match against requirements in the consumer
1250 "A name for the requirement matcher";
1251 type gbp-common:requirement-matcher-name;
1256 list matcher-requirement {
1258 "A matcher requirement is a
1259 requirement with a selector name
1260 field used in requirement
1261 matchers. The name of the
1262 matcher requirement matches
1263 against requirements in endpoint
1267 uses requirement-base;
1269 leaf selector-namespace {
1271 "The name of the selector to
1272 match. This allows us to
1273 specify that we want to match
1274 only requirements scoped to a
1275 particular selector name.
1277 This parameter is optional;
1278 if not specified, use an
1279 inherited selector namespace
1280 if it exists, or match
1281 against any selector name.";
1283 type gbp-common:selector-name;
1289 case group-any-case {
1290 container group-any {
1293 "A presence container stating that, if this exists,
1294 the role matcher will match on any group.";
1295 presence "This matches any group";
1302 uses has-condition-matchers;
1304 uses has-endpoint-identification-constraints;
1307 container provider-matchers {
1309 "Matchers that apply to the provider endpoint
1312 // GIC mutually OR'd within role
1313 choice group-identification-constraints {
1314 description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";
1316 case group-name-constraint-case {
1317 list group-name-constraint {
1318 key endpoint-group-name;
1319 leaf endpoint-group-name {
1320 type gbp-common:name;
1324 case group-capability-constraint-case {
1325 list capability-matcher {
1327 "Match against capabilities in the provider
1333 "A name for the capability matcher";
1334 type gbp-common:capability-matcher-name;
1340 list matcher-capability {
1342 "A matcher capability is a
1343 capability with a selector
1344 name field used in capability
1345 mat chers. The name of the
1346 matcher capability matches
1347 against capabilities in
1351 uses capability-base;
1353 leaf selector-namespace {
1355 "The name of the selector to
1356 match. This allows us to
1357 specify that we want to match
1358 only capabilities scoped to a
1359 particular selector name.
1361 This parameter is optional;
1362 if not specified, use an
1363 inherited selector namespace
1364 if it exists, or match
1365 against any selector name.";
1367 type gbp-common:selector-name;
1372 case group-any-case {
1373 container group-any {
1379 uses has-condition-matchers;
1381 uses has-endpoint-identification-constraints;
1384 container any-matchers {
1386 "Matchers that apply to either provider endpoint group or consumer endpoint group.";
1387 // TODO fill this out, may need additional groupings so as to not confuse capability or requirement.
1390 // ******************
1391 // Subject References
1392 // ******************
1394 leaf-list subject-refs {
1396 "The subjects that will be activated if this
1400 path "/tenants/tenant/contract/subject/name";
1410 description "Parent contract from which we inherit";
1413 path "/tenants/tenant/contract/id";
1420 "Contract references allow forming contracts
1421 between endpoint groups in different tenants.
1422 Once the contract reference is created, it is
1423 then possible to match against the contract using
1424 selectors as though it were a local tenant.
1426 Endpoint groups in the local tenant can serve
1427 only as consumers of the contract. Once the
1428 contract is matched, consumer matchers will apply
1429 to requirements and conditions in the local
1430 tenant, and provider matchers will apply against
1431 capabilities and conditions in the referenced
1438 "The tenant ID of the tenant containing the
1441 path "/tenants/tenant/id";
1445 description "The contract ID of the contract.";
1448 path "/tenants/tenant/contract/id";