1 Group Based Policy User Guide
2 =============================
7 OpenDaylight Group Based Policy allows users to express network
8 configuration in a declarative versus imperative way.
10 This is often described as asking for **"what you want"**, rather than
13 In order to achieve this Group Based Policy (herein referred to as
14 **GBP**) is an implementation of an **Intent System**.
18 - is a process around an intent driven data model
20 - contains no domain specifics
22 - is capable of addressing multiple semantic definitions of intent
24 To this end, **GBP** Policy views an **Intent System** visually as:
26 .. figure:: ./images/groupbasedpolicy/IntentSystemPolicySurfaces.png
27 :alt: Intent System Process and Policy Surfaces
29 Intent System Process and Policy Surfaces
31 - **expressed intent** is the entry point into the system.
33 - **operational constraints** provide policy for the usage of the
34 system which modulates how the system is consumed. For instance *"All
35 Financial applications must use a specific encryption standard"*.
37 - **capabilities and state** are provided by *renderers*. *Renderers*
38 dynamically provide their capabilities to the core model, allowing
39 the core model to remain non-domain specific.
41 - **governance** provides feedback on the delivery of the *expressed
42 intent*. i.e. *"Did we do what you asked us?"*
44 In summary **GBP is about the Automation of Intent**.
46 By thinking of **Intent Systems** in this way, it enables:
48 - **automation of intent**
50 By focusing on **Model. Process. Automation**, a consistent policy
51 resolution process enables for mapping between the **expressed
52 intent** and renderers responsible for providing the capabilities of
53 implementing that intent.
55 - recursive/intent level-independent behaviour.
57 Where *one person’s concrete is another’s abstract*, intent can be
58 fulfilled through a hierarchical implementation of non-domain
59 specific policy resolution. Domain specifics are provided by the
60 *renderers*, and exposed via the API, at each policy resolution
61 instance. For example:
63 - To DNS: The name "www.foo.com" is *abstract*, and it’s IPv4
64 address 10.0.0.10 is *concrete*,
66 - To an IP stack: 10.0.0.10 is *abstract* and the MAC
67 08:05:04:03:02:01 is *concrete*,
69 - To an Ethernet switch: The MAC 08:05:04:03:02:01 is *abstract*,
70 the resolution to a port in it’s CAM table is *concrete*,
72 - To an optical network: The port maybe *abstract*, yet the optical
73 wavelength is *concrete*.
77 *This is a very domain specific analogy, tied to something most
78 readers will understand. It in no way implies the **GBP** should be
79 implemented in an OSI type fashion. The premise is that by
80 implementing a full **Intent System**, the user is freed from a lot
81 of the constraints of how the expressed intent is realised.*
83 It is important to show the overall philosophy of **GBP** as it sets the
86 In the Beryllium release of OpenDaylight, **GBP** focused on **expressed
87 intent**, **refactoring of how renderers consume and publish Subject
88 Feature Definitions for multi-renderer support**.
90 GBP Base Architecture and Value Proposition
91 -------------------------------------------
96 In order to explain the fundamental value proposition of **GBP**, an
97 illustrated example is given. In order to do that some terminology must
100 The Access Model is the core of the **GBP** Intent System policy
103 .. figure:: ./images/groupbasedpolicy/GBPTerminology1.png
104 :alt: GBP Access Model Terminology - Endpoints, EndpointGroups,
107 GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
109 .. figure:: ./images/groupbasedpolicy/GBPTerminology2.png
110 :alt: GBP Access Model Terminology - Subject, Classifier, Action
112 GBP Access Model Terminology - Subject, Classifier, Action
114 .. figure:: ./images/groupbasedpolicy/GBPTerminology3.png
115 :alt: GBP Forwarding Model Terminology - L3 Context, L2 Bridge
116 Context, L2 Flood Context/Domain, Subnet
118 GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2
119 Flood Context/Domain, Subnet
123 Define concrete uniquely identifiable entities. In Beryllium,
124 examples could be a Docker container, or a Neutron port
128 EndpointGroups are sets of endpoints that share a common set of
129 policies. EndpointGroups can participate in contracts that determine
130 the kinds of communication that are allowed. EndpointGroups *consume*
131 and *provide* contracts. They also expose both *requirements and
132 capabilities*, which are labels that help to determine how contracts
133 will be applied. An EndpointGroup can specify a parent EndpointGroup
134 from which it inherits.
138 Contracts determine which endpoints can communicate and in what way.
139 Contracts between pairs of EndpointGroups are selected by the
140 contract selectors defined by the EndpointGroup. Contracts expose
141 qualities, which are labels that can help EndpointGroups to select
142 contracts. Once the contract is selected, contracts have clauses that
143 can match against requirements and capabilities exposed by
144 EndpointGroups, as well as any conditions that may be set on
145 endpoints, in order to activate subjects that can allow specific
146 kinds of communication. A contract is allowed to specify a parent
147 contract from which it inherits.
151 Subjects describe some aspect of how two endpoints are allowed to
152 communicate. Subjects define an ordered list of rules that will match
153 against the traffic and perform any necessary actions on that
154 traffic. No communication is allowed unless a subject allows that
159 Clauses are defined as part of a contract. Clauses determine how a
160 contract should be applied to particular endpoints and
161 EndpointGroups. Clauses can match against requirements and
162 capabilities exposed by EndpointGroups, as well as any conditions
163 that may be set on endpoints. Matching clauses define some set of
164 subjects which can be applied to the communication between the pairs
167 Architecture and Value Proposition
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170 **GBP** offers an intent based interface, accessed via the `UX <#UX>`__,
171 via the `REST API <#REST>`__ or directly from a domain-specific-language
172 such as `Neutron <#Neutron>`__ through a mapping interface.
174 There are two models in **GBP**:
176 - the access (or core) model
178 - the forwarding model
180 .. figure:: ./images/groupbasedpolicy/GBP_AccessModel_simple.png
181 :alt: GBP Access (or Core) Model
183 GBP Access (or Core) Model
185 The *classifier* and *action* portions of the model can be thought of as
186 hooks, with their definition provided by each *renderer* about its
187 domain specific capabilities. In **GBP** Beryllium, there is one
188 renderer, the *`OpenFlow Overlay renderer (OfOverlay). <#OfOverlay>`__*
190 These hooks are filled with *definitions* of the types of *features* the
191 renderer can provide the *subject*, and are called
192 **subject-feature-definitions**.
194 This means an *expressed intent* can be fulfilled by, and across,
195 multiple renderers simultaneously, without any specific provisioning
196 from the consumer of **GBP**.
198 Since **GBP** is implemented in OpenDaylight, which is an SDN
199 controller, it also must address networking. This is done via the
200 *forwarding model*, which is domain specific to networking, but could be
201 applied to many different *types* of networking.
203 .. figure:: ./images/groupbasedpolicy/GBP_ForwardingModel_simple.png
204 :alt: GBP Forwarding Model
208 Each endpoint is provisioned with a *network-containment*. This can be
213 - normal IP stack behaviour, where ARP is performed in subnet, and
214 for out of subnet, traffic is sent to default gateway.
216 - a subnet can be a child of any of the below forwarding model
217 contexts, but typically would be a child of a flood-domain
221 - allows flooding behaviour.
223 - is a n:1 child of a bridge-domain
225 - can have multiple children
229 - is a layer2 namespace
231 - is the realm where traffic can be sent at layer 2
233 - is a n:1 child of a L3 context
235 - can have multiple children
239 - is a layer3 namespace
241 - is the realm where traffic is passed at layer 3
243 - is a n:1 child of a tenant
245 - can have multiple children
247 A simple example of how the access and forwarding models work is as
250 .. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Contract.png
251 :alt: GBP Endpoints, EndpointGroups and Contracts
253 GBP Endpoints, EndpointGroups and Contracts
255 In this example, the **EPG:webservers** is *providing* the *web* and
256 *ssh* contracts. The **EPG:client** is consuming those contracts.
257 **EPG:client** is providing the *any* contract, which is consumed by
260 The *direction* keyword is always from the perspective of the *provider*
261 of the contract. In this case contract *web*, being *provided* by
262 **EPG:webservers**, with the classifier to match TCP destination port
265 - packets with a TCP destination port of 80
267 - sent to (*in*) endpoints in the **EPG:webservers**
271 .. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png
272 :alt: GBP Endpoints and the Forwarding Model
274 GBP Endpoints and the Forwarding Model
276 When the forwarding model is considered in the figure above, it can be
277 seen that even though all endpoints are communicating using a common set
278 of contracts, their forwarding is *contained* by the forwarding model
279 contexts or namespaces. In the example shown, the endpoints associated
280 with a *network-containment* that has an ultimate parent of
281 *L3Context:Sales* can only communicate with other endpoints within this
282 L3Context. In this way L3VPN services can be implemented without any
283 impact to the **Intent** of the contract.
285 High-level implementation Architecture
286 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
288 The overall architecture, including *`Neutron <#Neutron>`__* domain
289 specific mapping, and the `OpenFlow Overlay renderer <#OfOverlay>`__
292 .. figure:: ./images/groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png
293 :alt: GBP High Level Beryllium Architecture
295 GBP High Level Beryllium Architecture
297 The major benefit of this architecture is that the mapping of the
298 domain-specific-language is completely separate and independent of the
299 underlying renderer implementation.
301 For instance, using the `Neutron Mapper <#Neutron>`__, which maps the
302 Neutron API to the **GBP** core model, any contract automatically
303 generated from this mapping can be augmented via the `UX <#UX>`__ to use
304 `Service Function Chaining <#SFC>`__, a capability not currently
305 available in OpenStack Neutron.
307 When another renderer is added, for instance, NetConf, the same policy
308 can now be leveraged across NetConf devices simultaneously:
310 .. figure:: ./images/groupbasedpolicy/GBP_High-levelExtraRenderer.png
311 :alt: GBP High Level Beryllium Architecture - adding a renderer
313 GBP High Level Beryllium Architecture - adding a renderer
315 As other domain-specific mappings occur, they too can leverage the same
316 renderers, as the renderers only need to implement the **GBP** access
317 and forwarding models, and the domain-specific mapping need only manage
318 mapping to the access and forwarding models. For instance:
320 .. figure:: ./images/groupbasedpolicy/High-levelBerylliumArchitectureEvolution2.png
321 :alt: GBP High Level Beryllium Architecture - adding a renderer
323 GBP High Level Beryllium Architecture - adding a renderer
325 In summary, the **GBP** architecture:
327 - separates concerns: the Expressed Intent is kept completely separated
328 from the underlying renderers.
330 - is cohesive: each part does it’s part and it’s part only
332 - is scalable: code can be optimised around model
333 mapping/implementation, and functionality re-used
341 The first step in policy resolution is to select the contracts that are
344 EndpointGroups participate in contracts either as a *provider* or as a
345 *consumer* of a contract. Each EndpointGroup can participate in many
346 contracts at the same time, but for each contract it can be in only one
347 role at a time. In addition, there are two ways for an EndpointGroup to
348 select a contract: either with either a:
352 Named selectors simply select a specific contract by its contract ID.
356 Target selectors allow for additional flexibility by matching against
357 *qualities* of the contract’s *target.*
359 Thus, there are a total of 4 kinds of contract selector:
361 - provider named selector
363 Select a contract by contract ID, and participate as a provider.
365 - provider target selector
367 Match against a contract’s target with a quality matcher, and
368 participate as a provider.
370 - consumer named selector
372 Select a contract by contract ID, and participate as a consumer.
374 - consumer target selector
376 Match against a contract’s target with a quality matcher, and
377 participate as a consumer.
379 To determine which contracts are in scope, contracts are found where
380 either the source EndpointGroup selects a contract as either a provider
381 or consumer, while the destination EndpointGroup matches against the
382 same contract in the corresponding role. So if endpoint *x* in
383 EndpointGroup *X* is communicating with endpoint *y* in EndpointGroup
384 *Y*, a contract *C* is in scope if either *X* selects *C* as a provider
385 and *Y* selects *C* as a consumer, or vice versa.
387 The details of how quality matchers work are described further in
388 `Matchers <#Matchers>`__. Quality matchers provide a flexible mechanism
389 for contract selection based on labels.
391 The end result of the contract selection phase can be thought of as a
392 set of tuples representing selected contract scopes. The fields of the
397 - The provider EndpointGroup ID
399 - The name of the selector in the provider EndpointGroup that was used
400 to select the contract, called the *matching provider selector.*
402 - The consumer EndpointGroup ID
404 - The name of the selector in the consumer EndpointGroup that was used
405 to select the contract, called the *matching consumer selector.*
407 The result is then stored in the datastore under **Resolved Policy**.
412 The second phase in policy resolution is to determine which subjects are
413 in scope. The subjects define what kinds of communication are allowed
414 between endpoints in the EndpointGroups. For each of the selected
415 contract scopes from the contract selection phase, the subject selection
416 procedure is applied.
418 Labels called, capabilities, requirements and conditions are matched
419 against to bring a Subject *into scope*. EndpointGroups have
420 capabilities and requirements, while endpoints have conditions.
422 Requirements and Capabilities
423 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
425 When acting as a *provider*, EndpointGroups expose *capabilities,* which
426 are labels representing specific pieces of functionality that can be
427 exposed to other EndpointGroups that may meet functional requirements of
428 those EndpointGroups.
430 When acting as a *consumer*, EndpointGroups expose *requirements*, which
431 are labels that represent that the EndpointGroup requires some specific
432 piece of functionality.
434 As an example, we might create a capability called "user-database" which
435 indicates that an EndpointGroup contains endpoints that implement a
438 We might create a requirement also called "user-database" to indicate an
439 EndpointGroup contains endpoints that will need to communicate with the
440 endpoints that expose this service.
442 Note that in this example the requirement and capability have the same
443 name, but the user need not follow this convention.
445 The matching provider selector (that was used by the provider
446 EndpointGroup to select the contract) is examined to determine the
447 capabilities exposed by the provider EndpointGroup for this contract
450 The provider selector will have a list of capabilities either directly
451 included in the provider selector or inherited from a parent selector or
452 parent EndpointGroup. (See `Inheritance <#Inheritance>`__).
454 Similarly, the matching consumer selector will expose a set of
460 Endpoints can have *conditions*, which are labels representing some
461 relevant piece of operational state related to the endpoint.
463 An example of a condition might be "malware-detected," or
464 "authentication-succeeded." Conditions are used to affect how that
465 particular endpoint can communicate.
467 To continue with our example, the "malware-detected" condition might
468 cause an endpoint’s connectivity to be cut off, while
469 "authentication-succeeded" might open up communication with services
470 that require an endpoint to be first authenticated and then forward its
471 authentication credentials.
476 Clauses perform the actual selection of subjects. A clause has lists of
477 matchers in two categories. In order for a clause to become active, all
478 lists of matchers must match. A matching clause will select all the
479 subjects referenced by the clause. Note that an empty list of matchers
482 The first category is the consumer matchers, which match against the
483 consumer EndpointGroup and endpoints. The consumer matchers are:
485 - Group Idenfication Constraint: Requirement matchers
487 Matches against requirements in the matching consumer selector.
489 - Group Identification Constraint: GroupName
491 Matches against the group name
493 - Consumer condition matchers
495 Matches against conditions on endpoints in the consumer EndpointGroup
497 - Consumer Endpoint Identification Constraint
499 Label based criteria for matching against endpoints. In Beryllium
500 this can be used to label endpoints based on IpPrefix.
502 The second category is the provider matchers, which match against the
503 provider EndpointGroup and endpoints. The provider matchers are:
505 - Group Idenfication Constraint: Capability matchers
507 Matches against capabilities in the matching provider selector.
509 - Group Identification Constraint: GroupName
511 Matches against the group name
513 - Consumer condition matchers
515 Matches against conditions on endpoints in the provider EndpointGroup
517 - Consumer Endpoint Identification Constraint
519 Label based criteria for matching against endpoints. In Beryllium
520 this can be used to label endpoints based on IpPrefix.
522 Clauses have a list of subjects that apply when all the matchers in the
523 clause match. The output of the subject selection phase logically is a
524 set of subjects that are in scope for any particular pair of endpoints.
529 Now subjects have been selected that apply to the traffic between a
530 particular set of endpoints, policy can be applied to allow endpoints to
531 communicate. The applicable subjects from the previous step will each
532 contain a set of rules.
534 Rules consist of a set of *classifiers* and a set of *actions*.
535 Classifiers match against traffic between two endpoints. An example of a
536 classifier would be something that matches against all TCP traffic on
537 port 80, or one that matches against HTTP traffic containing a
538 particular cookie. Actions are specific actions that need to be taken on
539 the traffic before it reaches its destination. Actions could include
540 tagging or encapsulating the traffic in some way, redirecting the
541 traffic, or applying a `service function chain <#SFC>`__.
543 Rules, subjects, and actions have an *order* parameter, where a lower
544 order value means that a particular item will be applied first. All
545 rules from a particular subject will be applied before the rules of any
546 other subject, and all actions from a particular rule will be applied
547 before the actions from another rule. If more than item has the same
548 order parameter, ties are broken with a lexicographic ordering of their
549 names, with earlier names having logically lower order.
554 Matchers specify a set of labels (which include requirements,
555 capabilities, conditions, and qualities) to match against. There are
556 several kinds of matchers that operate similarly:
560 used in target selectors during the contract selection phase. Quality
561 matchers provide a more advanced and flexible way to select contracts
562 compared to a named selector.
564 - Requirement and capability matchers
566 used in clauses during the subject selection phase to match against
567 requirements and capabilities on EndpointGroups
571 used in clauses during the subject selection phase to match against
572 conditions on endpoints
574 A matcher is, at its heart, fairly simple. It will contain a list of
575 label names, along with a *match type*. The match type can be either:
579 which means the matcher matches when all of its labels match
583 which means the matcher matches when any of its labels match,
587 which means the matcher matches when none of its labels match.
589 Note a *match all* matcher can be made by matching against an empty set
590 of labels with a match type of "all."
592 Additionally each label to match can optionally include a relevant name
593 field. For quality matchers, this is a target name. For capability and
594 requirement matchers, this is a selector name. If the name field is
595 specified, then the matcher will only match against targets or selectors
596 with that name, rather than any targets or selectors.
601 Some objects in the system include references to parents, from which
602 they will inherit definitions. The graph of parent references must be
603 loop free. When resolving names, the resolution system must detect loops
604 and raise an exception. Objects that are part of these loops may be
605 considered as though they are not defined at all. Generally, inheritance
606 works by simply importing the objects in the parent into the child
607 object. When there are objects with the same name in the child object,
608 then the child object will override the parent object according to rules
609 which are specific to the type of object. We’ll next explore the
610 detailed rules for inheritance for each type of object
614 EndpointGroups will inherit all their selectors from their parent
615 EndpointGroups. Selectors with the same names as selectors in the parent
616 EndpointGroups will inherit their behavior as defined below.
620 Selectors include provider named selectors, provider target selectors,
621 consumer named selectors, and consumer target selectors. Selectors
622 cannot themselves have parent selectors, but when selectors have the
623 same name as a selector of the same type in the parent EndpointGroup,
624 then they will inherit from and override the behavior of the selector in
625 the parent EndpointGroup.
629 Named selectors will add to the set of contract IDs that are selected by
630 the parent named selector.
634 A target selector in the child EndpointGroup with the same name as a
635 target selector in the parent EndpointGroup will inherit quality
636 matchers from the parent. If a quality matcher in the child has the same
637 name as a quality matcher in the parent, then it will inherit as
638 described below under Matchers.
642 Contracts will inherit all their targets, clauses and subjects from
643 their parent contracts. When any of these objects have the same name as
644 in the parent contract, then the behavior will be as defined below.
648 Targets cannot themselves have a parent target, but it may inherit from
649 targets with the same name as the target in a parent contract. Qualities
650 in the target will be inherited from the parent. If a quality with the
651 same name is defined in the child, then this does not have any semantic
652 effect except if the quality has its inclusion-rule parameter set to
653 "exclude." In this case, then the label should be ignored for the
654 purpose of matching against this target.
658 Subjects cannot themselves have a parent subject, but it may inherit
659 from a subject with the same name as the subject in a parent contract.
660 The order parameter in the child subject, if present, will override the
661 order parameter in the parent subject. The rules in the parent subject
662 will be added to the rules in the child subject. However, the rules will
663 not override rules of the same name. Instead, all rules in the parent
664 subject will be considered to run with a higher order than all rules in
665 the child; that is all rules in the child will run before any rules in
666 the parent. This has the effect of overriding any rules in the parent
667 without the potentially-problematic semantics of merging the ordering.
671 Clauses cannot themselves have a parent clause, but it may inherit from
672 a clause with the same name as the clause in a parent contract. The list
673 of subject references in the parent clause will be added to the list of
674 subject references in the child clause. This is just a union operation.
675 A subject reference that refers to a subject name in the parent contract
676 might have that name overridden in the child contract. Each of the
677 matchers in the clause are also inherited by the child clause. Matchers
678 in the child of the same name and type as a matcher from the parent will
679 inherit from and override the parent matcher. See below under Matchers
680 for more information.
684 Matchers include quality matchers, condition matchers, requirement
685 matchers, and capability matchers. Matchers cannot themselves have
686 parent matchers, but when there is a matcher of the same name and type
687 in the parent object, then the matcher in the child object will inherit
688 and override the behavior of the matcher in the parent object. The match
689 type, if specified in the child, overrides the value specified in the
690 parent. Labels are also inherited from the parent object. If there is a
691 label with the same name in the child object, this does not have any
692 semantic effect except if the label has its inclusion-rule parameter set
693 to "exclude." In this case, then the label should be ignored for the
694 purpose of matching. Otherwise, the label with the same name will
695 completely override the label from the parent.
697 Using the GBP UX interface
698 --------------------------
703 These following components make up this application and are described in
704 more detail in following sections:
710 - Policy Expression view
714 The **GBP** UX is access via:
718 http://<odl controller>:8181/index.html
723 Basic view contains 5 navigation buttons which switch user to the
724 desired section of application:
726 - Governance – switch to the Governance view (middle of graphic has the
729 - Renderer configuration – switch to the Policy expression view with
730 Renderers section expanded
732 - Policy expression – switch to the Policy expression view with Policy
735 - Operational constraints – placeholder for development in next release
737 .. figure:: ./images/groupbasedpolicy/ui-1-basicview.png
745 Governance view consists from three columns.
747 .. figure:: ./images/groupbasedpolicy/ui-2-governanceview.png
748 :alt: Governance view
752 **Governance view – Basic view – Left column**
754 In the left column is Health section with Exception and Conflict buttons
755 with no functionality yet. This is a placeholder for development in
758 **Governance view – Basic view – Middle column**
760 In the top half of this section is select box with list of tenants for
761 select. Once the tenant is selected, all sub sections in application
762 operate and display data with actual selected tenant.
764 Below the select box are buttons which display Expressed or Delivered
765 policy of Governance section. In the bottom half of this section is
766 select box with list of renderers for select. There is currently only
767 `OfOverlay <#OfOverlay>`__ renderer available.
769 Below the select box is Renderer configuration button, which switch the
770 app into the Policy expression view with Renderers section expanded for
771 performing CRUD operations. Renderer state button display Renderer state
774 **Governance view – Basic view – Right column**
776 In the bottom part of the right section of Governance view is Home
777 button which switch the app to the Basic view.
779 In the top part is situated navigation menu with four main sections.
781 Policy expression button expand/collapse sub menu with three main parts
782 of Policy expression. By clicking on sub menu buttons, user will be
783 switched into the Policy expressions view with appropriate section
784 expanded for performing CRUD operations.
786 Renderer configuration button switches user into the Policy expressions
789 Governance button expand/collapse sub menu with four main parts of
790 Governance section. Sub menu buttons of Governance section display
791 appropriate section of Governance view.
793 Operational constraints have no functionality yet, and is a placeholder
794 for development in further releases.
796 Below the menu is place for view info section which displays info about
797 actual selected element from the topology (explained below).
799 **Governance view – Expressed policy**
801 In this view are displayed contracts with their consumed and provided
802 EndpointGroups of actual selected tenant, which can be changed in select
803 box in the upper left corner.
805 By single-clicking on any contract or EPG, the data of actual selected
806 element will be shown in the right column below the menu. A Manage
807 button launches a display wizard window for managing configuration of
808 items such as `Service Function Chaining <#SFC>`__.
810 .. figure:: ./images/groupbasedpolicy/ui-3-governanceview-expressed.png
811 :alt: Expressed policy
815 **Governance view – Delivered policy** In this view are displayed
816 subjects with their consumed and provided EndpointGroups of actual
817 selected tenant, which can be changed in select box in the upper left
820 By single-clicking on any subject or EPG, the data of actual selected
821 element will be shown in the right column below the menu.
823 By double-click on subject the subject detail view will be displayed
824 with subject’s rules of actual selected subject, which can be changed in
825 select box in the upper left corner.
827 By single-clicking on rule or subject, the data of actual selected
828 element will be shown in the right column below the menu.
830 By double-clicking on EPG in Delivered policy view, the EPG detail view
831 will be displayed with EPG’s endpoints of actual selected EPG, which can
832 be changed in select box in the upper left corner.
834 By single-clicking on EPG or endpoint the data of actual selected
835 element will be shown in the right column below the menu.
837 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-0.png
838 :alt: Delivered policy
842 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-1-subject.png
847 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-2-epg.png
852 **Governance view – Renderer state**
854 In this part are displayed Subject feature definition data with two main
855 parts: Action definition and Classifier definition.
857 By clicking on the down/right arrow in the circle is possible to
858 expand/hide data of appropriate container or list. Next to the list node
859 are displayed names of list’s elements where one is always selected and
860 element’s data are shown (blue line under the name).
862 By clicking on names of children nodes is possible to select desired
863 node and node’s data will be displayed.
865 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-renderer.png
870 Policy expression view
871 ~~~~~~~~~~~~~~~~~~~~~~
873 In the left part of this view is placed topology of actual selected
874 elements with the buttons for switching between types of topology at the
877 Right column of this view contains four parts. At the top of this column
878 are displayed breadcrumbs with actual position in the application.
880 Below the breadcrumbs is select box with list of tenants for select. In
881 the middle part is situated navigation menu, which allows switch to the
882 desired section for performing CRUD operations.
884 At the bottom is quick navigation menu with Access Model Wizard button
885 which display Wizard view, Home button which switch application to the
886 Basic view and occasionally Back button, which switch application to the
889 **Policy expression - Navigation menu**
891 To open Policy expression, select Policy expression from the GBP Home
894 In the top of navigation box you can select the tenant from the tenants
895 list to activate features addicted to selected tenant.
897 In the right menu, by default, the Policy menu section is expanded.
898 Subitems of this section are modules for CRUD (creating, reading,
899 updating and deleting) of tenants, EndpointGroups, contracts, L2/L3
902 - Section Renderers contains CRUD forms for Classifiers and Actions.
904 - Section Endpoints contains CRUD forms for Endpoint and L3 prefix
907 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-1.png
908 :alt: Navigation menu
912 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-2.png
913 :alt: CRUD operations
917 **Policy expression - Types of topology**
919 There are three different types of topology:
921 - Configured topology - EndpointGroups and contracts between them from
924 - Operational topology - displays same information but is based on
927 - L2/L3 - displays relationships between L3Contexts, L2 Bridge domains,
928 L2 Flood domains and Subnets.
930 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-3.png
935 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-4.png
936 :alt: Config Topology
940 **Policy expression - CRUD operations**
942 In this part are described basic flows for viewing, adding, editing and
943 deleting system elements like tenants, EndpointGroups etc.
948 To edit tenant objects click the Tenants button in the right menu. You
949 can see the CRUD form containing tenants list and control buttons.
951 To add new tenant, click the Add button This will display the form for
952 adding a new tenant. After filling tenant attributes Name and
953 Description click Save button. Saving of any object can be performed
954 only if all the object attributes are filled correctly. If some
955 attribute doesn’t have correct value, exclamation mark with mouse-over
956 tooltip will be displayed next to the label for the attribute. After
957 saving of tenant the form will be closed and the tenants list will be
958 set to default value.
960 To view an existing tenant, select the tenant from the select box
961 Tenants list. The view form is read-only and can be closed by clicking
962 cross mark in the top right of the form.
964 To edit selected tenant, click the Edit button, which will display the
965 edit form for selected tenant. After editing the Name and Description of
966 selected tenant click the Save button to save selected tenant. After
967 saving of tenant the edit form will be closed and the tenants list will
968 be set to default value.
970 To delete tenant select the tenant from the Tenants list and click
973 To return to the Policy expression click Back button on the bottom of
978 For managing EndpointGroups (EPG) the tenant from the top Tenants list
981 To add new EPG click Add button and after filling required attributes
982 click Save button. After adding the EPG you can edit it and assign
983 Consumer named selector or Provider named selector to it.
985 To edit EPG click the Edit button after selecting the EPG from Group
988 To add new Consumer named selector (CNS) click the Add button next to
989 the Consumer named selectors list. While CNS editing you can set one or
990 more contracts for current CNS pressing the Plus button and selecting
991 the contract from the Contracts list. To remove the contract, click on
992 the cross mark next to the contract. Added CNS can be viewed, edited or
993 deleted by selecting from the Consumer named selectors list and clicking
994 the Edit and Delete buttons like with the EPG or tenants.
996 To add new Provider named selector (PNS) click the Add button next to
997 the Provider named selectors list. While PNS editing you can set one or
998 more contracts for current PNS pressing the Plus button and selecting
999 the contract from the Contracts list. To remove the contract, click on
1000 the cross mark next to the contract. Added PNS can be viewed, edited or
1001 deleted by selecting from the Provider named selectors list and clicking
1002 the Edit and Delete buttons like with the EPG or tenants.
1004 To delete EPG, CNS or PNS select it in selectbox and click the Delete
1005 button next to the selectbox.
1009 For managing contracts the tenant from the top Tenants list must be
1012 To add new Contract click Add button and after filling required fields
1015 After adding the Contract user can edit it by selecting in the Contracts
1016 list and clicking Edit button.
1018 To add new Clause click Add button next to the Clause list while editing
1019 the contract. While editing the Clause after selecting clause from the
1020 Clause list user can assign clause subjects by clicking the Plus button
1021 next to the Clause subjects label. Adding and editing action must be
1022 submitted by pressing Save button. To manage Subjects you can use CRUD
1023 form like with the Clause list.
1027 For managing L2/L3 the tenant from the top Tenants list must be
1030 To add L3 Context click the Add button next to the L3 Context list
1031 ,which will display the form for adding a new L3 Context. After filling
1032 L3 Context attributes click Save button. After saving of L3 Context,
1033 form will be closed and the L3 Context list will be set to default
1036 To view an existing L3 Context, select the L3 Context from the select
1037 box L3 Context list. The view form is read-only and can be closed by
1038 clicking cross mark in the top right of the form.
1040 If user wants to edit selected L3 Context, click the Edit button, which
1041 will display the edit form for selected L3 Context. After editing click
1042 the Save button to save selected L3 Context. After saving of L3 Context,
1043 the edit form will be closed and the L3 Context list will be set to
1046 To delete L3 Context, select it from the L3 Context list and click
1049 To add L2 Bridge Domain, click the Add button next to the L2 Bridge
1050 Domain list. This will display the form for adding a new L2 Bridge
1051 Domain. After filling L2 Bridge Domain attributes click Save button.
1052 After saving of L2 Bridge Domain, form will be closed and the L2 Bridge
1053 Domain list will be set to default value.
1055 To view an existing L2 Bridge Domain, select the L2 Bridge Domain from
1056 the select box L2 Bridge Domain list. The view form is read-only and can
1057 be closed by clicking cross mark in the top right of the form.
1059 If user wants to edit selected L2 Bridge Domain, click the Edit button,
1060 which will display the edit form for selected L2 Bridge Domain. After
1061 editing click the Save button to save selected L2 Bridge Domain. After
1062 saving of L2 Bridge Domain the edit form will be closed and the L2
1063 Bridge Domain list will be set to default value.
1065 To delete L2 Bridge Domain select it from the L2 Bridge Domain list and
1066 click Delete button.
1068 To add L3 Flood Domain, click the Add button next to the L3 Flood Domain
1069 list. This will display the form for adding a new L3 Flood Domain. After
1070 filling L3 Flood Domain attributes click Save button. After saving of L3
1071 Flood Domain, form will be closed and the L3 Flood Domain list will be
1072 set to default value.
1074 To view an existing L3 Flood Domain, select the L3 Flood Domain from the
1075 select box L3 Flood Domain list. The view form is read-only and can be
1076 closed by clicking cross mark in the top right of the form.
1078 If user wants to edit selected L3 Flood Domain, click the Edit button,
1079 which will display the edit form for selected L3 Flood Domain. After
1080 editing click the Save button to save selected L3 Flood Domain. After
1081 saving of L3 Flood Domain the edit form will be closed and the L3 Flood
1082 Domain list will be set to default value.
1084 To delete L3 Flood Domain select it from the L3 Flood Domain list and
1085 click Delete button.
1087 To add Subnet click the Add button next to the Subnet list. This will
1088 display the form for adding a new Subnet. After filling Subnet
1089 attributes click Save button. After saving of Subnet, form will be
1090 closed and the Subnet list will be set to default value.
1092 To view an existing Subnet, select the Subnet from the select box Subnet
1093 list. The view form is read-only and can be closed by clicking cross
1094 mark in the top right of the form.
1096 If user wants to edit selected Subnet, click the Edit button, which will
1097 display the edit form for selected Subnet. After editing click the Save
1098 button to save selected Subnet. After saving of Subnet the edit form
1099 will be closed and the Subnet list will be set to default value.
1101 To delete Subnet select it from the Subnet list and click Delete button.
1105 To add Classifier, click the Add button next to the Classifier list.
1106 This will display the form for adding a new Classifier. After filling
1107 Classifier attributes click Save button. After saving of Classifier,
1108 form will be closed and the Classifier list will be set to default
1111 To view an existing Classifier, select the Classifier from the select
1112 box Classifier list. The view form is read-only and can be closed by
1113 clicking cross mark in the top right of the form.
1115 If you want to edit selected Classifier, click the Edit button, which
1116 will display the edit form for selected Classifier. After editing click
1117 the Save button to save selected Classifier. After saving of Classifier
1118 the edit form will be closed and the Classifier list will be set to
1121 To delete Classifier select it from the Classifier list and click Delete
1126 To add Action, click the Add button next to the Action list. This will
1127 display the form for adding a new Action. After filling Action
1128 attributes click Save button. After saving of Action, form will be
1129 closed and the Action list will be set to default value.
1131 To view an existing Action, select the Action from the select box Action
1132 list. The view form is read-only and can be closed by clicking cross
1133 mark in the top right of the form.
1135 If user wants to edit selected Action, click the Edit button, which will
1136 display the edit form for selected Action. After editing click the Save
1137 button to save selected Action. After saving of Action the edit form
1138 will be closed and the Action list will be set to default value.
1140 To delete Action select it from the Action list and click Delete button.
1144 To add Endpoint, click the Add button next to the Endpoint list. This
1145 will display the form for adding a new Endpoint. To add EndpointGroup
1146 assignment click the Plus button next to the label EndpointGroups. To
1147 add Condition click Plus button next to the label Condition. To add L3
1148 Address click the Plus button next to the L3 Addresses label. After
1149 filling Endpoint attributes click Save button. After saving of Endpoint,
1150 form will be closed and the Endpoint list will be set to default value.
1152 To view an existing Endpoint just, the Endpoint from the select box
1153 Endpoint list. The view form is read-only and can be closed by clicking
1154 cross mark in the top right of the form.
1156 If you want to edit selected Endpoint, click the Edit button, which will
1157 display the edit form for selected Endpoint. After editing click the
1158 Save button to save selected Endpoint. After saving of Endpoint the edit
1159 form will be closed and the Endpoint list will be set to default value.
1161 To delete Endpoint select it from the Endpoint list and click Delete
1164 **L3 prefix endpoint**
1166 To add L3 prefix endpoint, click the Add button next to the L3 prefix
1167 endpoint list. This will display the form for adding a new Endpoint. To
1168 add EndpointGroup assignment, click the Plus button next to the label
1169 EndpointGroups. To add Condition, click Plus button next to the label
1170 Condition. To add L2 gateway click the Plus button next to the L2
1171 gateways label. To add L3 gateway, click the Plus button next to the L3
1172 gateways label. After filling L3 prefix endpoint attributes click Save
1173 button. After saving of L3 prefix endpoint, form will be closed and the
1174 Endpoint list will be set to default value.
1176 To view an existing L3 prefix endpoint, select the Endpoint from the
1177 select box L3 prefix endpoint list. The view form is read-only and can
1178 be closed by clicking cross mark in the top right of the form.
1180 If you want to edit selected L3 prefix endpoint, click the Edit button,
1181 which will display the edit form for selected L3 prefix endpoint. After
1182 editing click the Save button to save selected L3 prefix endpoint. After
1183 saving of Endpoint the edit form will be closed and the Endpoint list
1184 will be set to default value.
1186 To delete Endpoint select it from the L3 prefix endpoint list and click
1192 Wizard provides quick method to send basic data to controller necessary
1193 for basic usage of GBP application. It is useful in the case that there
1194 aren’t any data in controller. In the first tab is form for create
1195 tenant. The second tab is for CRUD operations with contracts and their
1196 sub elements such as subjects, rules, clauses, action refs and
1197 classifier refs. The last tab is for CRUD operations with EndpointGroups
1198 and their CNS and PNS. Created structure of data is possible to send by
1199 clicking on Submit button.
1201 .. figure:: ./images/groupbasedpolicy/ui-6-wizard.png
1211 - `Using the GBP OpenFlow Overlay (OfOverlay) renderer <#OfOverlay>`__
1213 - `Policy Resolution <#policyresolution>`__
1215 - `Forwarding Model <#forwarding>`__
1217 - `the **GBP** demo and development environments for tips <#demo>`__
1219 It is recommended to use either:
1221 - `Neutron mapper <#Neutron>`__
1225 If the REST API must be used, and the above resources are not
1228 - feature:install odl-dlux-yangui
1231 `http://<odl-controller>:8181/index.html <http://<odl-controller>:8181/index.html>`__
1232 and select YangUI from the left menu.
1234 to explore the various **GBP** REST options
1236 Using OpenStack with GBP
1237 ------------------------
1242 This section is for Application Developers and Network Administrators
1243 who are looking to integrate Group Based Policy with OpenStack.
1245 To enable the **GBP** Neutron Mapper feature, at the Karaf console:
1249 feature:install odl-groupbasedpolicy-neutronmapper
1251 Neutron Mapper has the following dependencies that are automatically
1258 Neutron Northbound implementing REST API used by OpenStack
1262 odl-groupbasedpolicy-base
1264 Base **GBP** feature set, such as policy resolution, data model etc.
1268 odl-groupbasedpolicy-ofoverlay
1270 REST calls from OpenStack Neutron are by the Neutron NorthBound project.
1272 **GBP** provides the implementation of the `Neutron V2.0
1273 API <http://developer.openstack.org/api-ref-networking-v2.html>`__.
1278 List of supported Neutron entities:
1286 - External provider L2/L3 network
1294 - Distributed functionality with local routing per compute
1296 - External gateway access per compute node (dedicated port required)
1298 - Multiple routers per tenant
1304 The mapping of Neutron entities to **GBP** entities is as follows:
1308 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
1313 The Neutron port is mapped to an endpoint.
1315 The current implementation supports one IP address per Neutron port.
1317 An endpoint and L3-endpoint belong to multiple EndpointGroups if the
1318 Neutron port is in multiple Neutron Security Groups.
1320 The key for endpoint is L2-bridge-domain obtained as the parent of
1321 L2-flood-domain representing Neutron network. The MAC address is from
1322 the Neutron port. An L3-endpoint is created based on L3-context (the
1323 parent of the L2-bridge-domain) and IP address of Neutron Port.
1327 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
1328 :alt: Neutron Network
1332 A Neutron network has the following characteristics:
1334 - defines a broadcast domain
1336 - defines a L2 transmission domain
1338 - defines a L2 name space.
1340 To represent this, a Neutron Network is mapped to multiple **GBP**
1341 entities. The first mapping is to an L2 flood-domain to reflect that the
1342 Neutron network is one flooding or broadcast domain. An L2-bridge-domain
1343 is then associated as the parent of L2 flood-domain. This reflects both
1344 the L2 transmission domain as well as the L2 addressing namespace.
1346 The third mapping is to L3-context, which represents the distinct L3
1347 address space. The L3-context is the parent of L2-bridge-domain.
1351 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
1352 :alt: Neutron Subnet
1356 Neutron subnet is associated with a Neutron network. The Neutron subnet
1357 is mapped to a **GBP** subnet where the parent of the subnet is
1358 L2-flood-domain representing the Neutron network.
1360 **Neutron Security Group**
1362 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
1363 :alt: Neutron Security Group and Rules
1365 Neutron Security Group and Rules
1367 **GBP** entity representing Neutron security-group is EndpointGroup.
1369 **Infrastructure EndpointGroups**
1371 Neutron-mapper automatically creates EndpointGroups to manage key
1372 infrastructure items such as:
1374 - DHCP EndpointGroup - contains endpoints representing Neutron DHCP
1377 - Router EndpointGroup - contains endpoints representing Neutron router
1380 - External EndpointGroup - holds L3-endpoints representing Neutron
1381 router gateway ports, also associated with FloatingIP ports.
1383 **Neutron Security Group Rules**
1385 This is the most involved amongst all the mappings because Neutron
1386 security-group-rules are mapped to contracts with clauses, subjects,
1387 rules, action-refs, classifier-refs, etc. Contracts are used between
1388 EndpointGroups representing Neutron Security Groups. For simplification
1389 it is important to note that Neutron security-group-rules are similar to
1390 a **GBP** rule containing:
1392 - classifier with direction
1394 - action of **allow**.
1398 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
1399 :alt: Neutron Router
1403 Neutron router is represented as a L3-context. This treats a router as a
1404 Layer3 namespace, and hence every network attached to it a part of that
1407 This allows for multiple routers per tenant with complete isolation.
1409 The mapping of the router to an endpoint represents the router’s
1410 interface or gateway port.
1412 The mapping to an EndpointGroup represents the internal infrastructure
1413 EndpointGroups created by the **GBP** Neutron Mapper
1415 When a Neutron router interface is attached to a network/subnet, that
1416 network/subnet and its associated endpoints or Neutron Ports are
1417 seamlessly added to the namespace.
1419 **Neutron FloatingIP**
1421 When associated with a Neutron Port, this leverages the
1422 `OfOverlay <#OfOverlay>`__ renderer’s NAT capabilities.
1424 A dedicated *external* interface on each Nova compute host allows for
1425 disitributed external access. Each Nova instance associated with a
1426 FloatingIP address can access the external network directly without
1427 having to route via the Neutron controller, or having to enable any form
1428 of Neutron distributed routing functionality.
1430 Assuming the gateway provisioned in the Neutron Subnet command for the
1431 external network is reachable, the combination of **GBP** Neutron Mapper
1432 and `OfOverlay renderer <#OfOverlay>`__ will automatically ARP for this
1433 default gateway, requiring no user intervention.
1435 **Troubleshooting within GBP**
1437 Logging level for the mapping functionality can be set for package
1438 org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling
1439 TRACE logging level on Karaf console:
1443 log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
1445 **Neutron mapping example**
1447 As an example for mapping can be used creation of Neutron network,
1448 subnet and port. When a Neutron network is created 3 **GBP** entities
1449 are created: l2-flood-domain, l2-bridge-domain, l3-context.
1451 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
1452 :alt: Neutron network mapping
1454 Neutron network mapping
1456 After an subnet is created in the network mapping looks like this.
1458 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
1459 :alt: Neutron subnet mapping
1461 Neutron subnet mapping
1463 If an Neutron port is created in the subnet an endpoint and l3-endpoint
1464 are created. The endpoint has key composed from l2-bridge-domain and MAC
1465 address from Neutron port. A key of l3-endpoint is compesed from
1466 l3-context and IP address. The network containment of endpoint and
1467 l3-endpoint points to the subnet.
1469 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
1470 :alt: Neutron port mapping
1472 Neutron port mapping
1474 Configuring GBP Neutron
1475 ~~~~~~~~~~~~~~~~~~~~~~~
1477 No intervention passed initial OpenStack setup is required by the user.
1479 More information about configuration can be found in our DevStack demo
1480 environment on the `**GBP**
1481 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__.
1483 Administering or Managing GBP Neutron
1484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1486 For consistencies sake, all provisioning should be performed via the
1487 Neutron API. (CLI or Horizon).
1489 The mapped policies can be augmented via the **GBP** `UX <#UX>`__, to:
1491 - Enable `Service Function Chaining <#SFC>`__
1493 - Add endpoints from outside of Neutron i.e. VMs/containers not
1494 provisioned in OpenStack
1496 - Augment policies/contracts derived from Security Group Rules
1498 - Overlay additional contracts or groupings
1503 A DevStack demo environment can be found on the `**GBP**
1504 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__.
1506 Using the GBP OpenFlow Overlay (OfOverlay) renderer
1507 ---------------------------------------------------
1512 The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
1513 renderer, which creates a network virtualization solution across nodes
1514 that host Open vSwitch software switches.
1516 Installing and Pre-requisites
1517 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1519 From the Karaf console in OpenDaylight:
1523 feature:install odl-groupbasedpolicy-ofoverlay
1525 This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although
1526 2.3 is strongly recommended) and OpenFlow 1.3.
1528 When used in conjunction with the `Neutron Mapper feature <#Neutron>`__
1529 no extra OfOverlay specific setup is required.
1531 When this feature is loaded "standalone", the user is required to
1532 configure infrastructure, such as
1534 - instantiating OVS bridges,
1536 - attaching hosts to the bridges,
1538 - and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
1540 The **GBP** OfOverlay renderer also supports a table offset option, to
1541 offset the pipeline post-table 0. The value of table offset is stored in
1542 the config datastore and it may be rewritten at runtime.
1546 PUT http://{{controllerIp}}:8181/restconf/config/ofoverlay:of-overlay-config
1548 "of-overlay-config": {
1549 "gbp-ofoverlay-table-offset": 6
1553 The default value is set by changing:
1554 <gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
1557 distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
1559 To avoid overwriting runtime changes, the default value is used only
1560 when the OfOverlay renderer starts and no other value has been written
1563 OpenFlow Overlay Architecture
1564 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1566 These are the primary components of **GBP**. The OfOverlay components
1567 are highlighted in red.
1569 .. figure:: ./images/groupbasedpolicy/ofoverlay-1-components.png
1570 :alt: OfOverlay within **GBP**
1572 OfOverlay within **GBP**
1574 In terms of the inner components of the **GBP** OfOverlay renderer:
1576 .. figure:: ./images/groupbasedpolicy/ofoverlay-2-components.png
1577 :alt: OfOverlay expanded view:
1579 OfOverlay expanded view:
1581 **OfOverlay Renderer**
1583 Launches components below:
1587 Policy resolution is completely domain independent, and the OfOverlay
1588 leverages process policy information internally. See `Policy Resolution
1589 process <#policyresolution>`__.
1591 It listens to inputs to the *Tenants* configuration datastore, validates
1592 tenant input, then writes this to the Tenants operational datastore.
1594 From there an internal notification is generated to the PolicyManager.
1596 In the next release, this will be moving to a non-renderer specific
1599 **Endpoint Manager**
1601 The endpoint repository operates in **orchestrated** mode. This means
1602 the user is responsible for the provisioning of endpoints via:
1610 When using the `Neutron mapper <#Neutron>`__ feature, everything is
1611 managed transparently via Neutron.
1613 The Endpoint Manager is responsible for listening to Endpoint repository
1614 updates and notifying the Switch Manager when a valid Endpoint has been
1617 It also supplies utility functions to the flow pipeline process.
1621 The Switch Manager is purely a state manager.
1623 Switches are in one of 3 states:
1631 **Ready** is denoted by a connected switch:
1633 - having a tunnel interface
1635 - having at least one endpoint connected.
1637 In this way **GBP** is not writing to switches it has no business to.
1639 **Preparing** simply means the switch has a controller connection but is
1640 missing one of the above *complete and necessary* conditions
1642 **Disconnected** means a previously connected switch is no longer
1643 present in the Inventory operational datastore.
1645 .. figure:: ./images/groupbasedpolicy/ofoverlay-3-flowpipeline.png
1646 :alt: OfOverlay Flow Pipeline
1648 OfOverlay Flow Pipeline
1650 The OfOverlay leverages Nicira registers as follows:
1652 - REG0 = Source EndpointGroup + Tenant ordinal
1654 - REG1 = Source Conditions + Tenant ordinal
1656 - REG2 = Destination EndpointGroup + Tenant ordinal
1658 - REG3 = Destination Conditions + Tenant ordinal
1660 - REG4 = Bridge Domain + Tenant ordinal
1662 - REG5 = Flood Domain + Tenant ordinal
1664 - REG6 = Layer 3 Context + Tenant ordinal
1668 Table 0 of the OpenFlow pipeline. Responsible for ensuring that only
1669 valid connections can send packets into the pipeline:
1673 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1674 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1675 cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
1676 cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
1677 cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
1678 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1679 cookie=0x0, <snip> , priority=111, ip actions=drop
1680 cookie=0x0, <snip> , priority=110,arp actions=drop
1681 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1682 cookie=0x0, <snip> , priority=1 actions=drop
1684 Ingress from tunnel interface, go to Table *Source Mapper*:
1688 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1690 Ingress from outside, goto Table *Ingress NAT Mapper*:
1694 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1696 ARP from Endpoint, go to Table *Source Mapper*:
1700 cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
1702 IPv4 from Endpoint, go to Table *Source Mapper*:
1706 cookie=0x0, <snip> , priority=120,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_src=10.1.1.3 actions=goto_table:2
1708 DHCP DORA from Endpoint, go to Table *Source Mapper*:
1712 cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
1714 Series of DROP tables with priority set to capture any non-specific
1715 traffic that should have matched above:
1719 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1720 cookie=0x0, <snip> , priority=111, ip actions=drop
1721 cookie=0x0, <snip> , priority=110,arp actions=drop
1723 "L2" catch all traffic not identified above:
1727 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1733 cookie=0x0, <snip> , priority=1 actions=drop
1735 **Ingress NAT Mapper**
1737 Table `*offset* <#offset>`__\ +1.
1739 ARP responder for external NAT address:
1743 cookie=0x0, <snip> , priority=150,arp,arp_tpa=192.168.111.51,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:58:c3:dd->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e58c3dd->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xc0a86f33->NXM_OF_ARP_SPA[],IN_PORT
1745 Translate from Outside to Inside and perform same functions as
1750 cookie=0x0, <snip> , priority=100,ip,nw_dst=192.168.111.51 actions=set_field:10.1.1.2->ip_dst,set_field:fa:16:3e:58:c3:dd->eth_dst,load:0x2->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0x3->NXM_NX_TUN_ID[0..31],goto_table:3
1754 Table `*offset* <#offset>`__\ +2.
1756 Determines based on characteristics from the ingress port, which:
1758 - EndpointGroup(s) it belongs to
1760 - Forwarding context
1762 - Tunnel VNID ordinal
1764 Establishes tunnels at valid destination switches for ingress.
1766 Ingress Tunnel established at remote node with VNID Ordinal that maps to
1767 Source EPG, Forwarding Context etc:
1771 cookie=0x0, <snip>, priority=150,tun_id=0xd,in_port=3 actions=load:0xc->NXM_NX_REG0[],load:0xffffff->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],goto_table:3
1773 Maps endpoint to Source EPG, Forwarding Context based on ingress port,
1778 cookie=0x0, <snip> , priority=100,in_port=5,dl_src=fa:16:3e:b4:b4:b1 actions=load:0xc->NXM_NX_REG0[],load:0x1->NXM_NX_REG1[],load:0x4->NXM_NX_REG4[],load:0x5->NXM_NX_REG5[],load:0x7->NXM_NX_REG6[],load:0xd->NXM_NX_TUN_ID[0..31],goto_table:3
1784 cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
1786 **Destination Mapper**
1788 Table `*offset* <#offset>`__\ +3.
1790 Determines based on characteristics of the endpoint:
1792 - EndpointGroup(s) it belongs to
1794 - Forwarding context
1796 - Tunnel Destination value
1798 Manages routing based on valid ingress nodes ARP’ing for their default
1799 gateway, and matches on either gateway MAC or destination endpoint MAC.
1801 ARP for default gateway for the 10.1.1.0/24 subnet:
1805 cookie=0x0, <snip> , priority=150,arp,reg6=0x7,arp_tpa=10.1.1.1,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:fa:16:3e:28:4c:82->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],load:0xfa163e284c82->NXM_NX_ARP_SHA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xa010101->NXM_OF_ARP_SPA[],IN_PORT
1807 Broadcast traffic destined for GroupTable:
1811 cookie=0x0, <snip> , priority=140,reg5=0x5,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 actions=load:0x5->NXM_NX_TUN_ID[0..31],group:5
1813 Layer3 destination matching flows, where priority=100+masklength. Since
1814 **GBP** now support L3Prefix endpoint, we can set default routes etc:
1818 cookie=0x0, <snip>, priority=132,ip,reg6=0x7,dl_dst=fa:16:3e:b4:b4:b1,nw_dst=10.1.1.3 actions=load:0xc->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x5->NXM_NX_REG7[],set_field:fa:16:3e:b4:b4:b1->eth_dst,dec_ttl,goto_table:4
1820 Layer2 destination matching flows, designed to be caught only after last
1821 IP flow (lowest priority IP flow is 100):
1825 cookie=0x0, duration=323.203s, table=3, n_packets=4, n_bytes=168, priority=50,reg4=0x4,dl_dst=fa:16:3e:58:c3:dd actions=load:0x2->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x2->NXM_NX_REG7[],goto_table:4
1827 General drop flow: cookie=0x0, duration=323.207s, table=3, n\_packets=6,
1828 n\_bytes=588, priority=1 actions=drop
1832 Table `*offset* <#offset>`__\ +4.
1834 Once the Source and Destination EndpointGroups are assigned, policy is
1835 enforced based on resolved rules.
1837 In the case of `Service Function Chaining <#SFC>`__, the encapsulation
1838 and destination for traffic destined to a chain, is discovered and
1841 Policy flow, allowing IP traffic between EndpointGroups:
1845 cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
1847 **Egress NAT Mapper**
1849 Table `*offset* <#offset>`__\ +5.
1851 Performs NAT function before Egressing OVS instance to the underlay
1854 Inside to Outside NAT translation before sending to underlay:
1858 cookie=0x0, <snip> , priority=100,ip,reg6=0x7,nw_src=10.1.1.2 actions=set_field:192.168.111.51->ip_src,goto_table:6
1862 Table `*offset* <#offset>`__\ +6.
1864 Manages post-policy enforcement for endpoint specific destination
1865 effects. Specifically for `Service Function Chaining <#SFC>`__, which is
1866 why we can support both symmetric and asymmetric chains and distributed
1867 ingress/egress classification.
1873 cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
1875 Configuring OpenFlow Overlay via REST
1876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1880 Please see the `UX <#UX>`__ section on how to configure **GBP** via
1887 POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
1890 "endpoint-group": "<epg0>",
1891 "endpoint-groups" : ["<epg1>","<epg2>"],
1892 "network-containment" : "<fowarding-model-context1>",
1893 "l2-context": "<bridge-domain1>",
1894 "mac-address": "<mac1>",
1897 "ip-address": "<ipaddress1>",
1898 "l3-context": "<l3_context1>"
1901 "*ofoverlay:port-name*": "<ovs port name>",
1902 "tenant": "<tenant1>"
1908 The usage of "port-name" preceded by "ofoverlay". In OpenDaylight,
1909 base datastore objects can be *augmented*. In **GBP**, the base
1910 endpoint model has no renderer specifics, hence can be leveraged
1911 across multiple renderers.
1913 **OVS Augmentations to Inventory**
1917 PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
1919 "opendaylight-inventory:nodes": {
1922 "id": "openflow:123456",
1923 "ofoverlay:tunnel": [
1925 "tunnel-type": "overlay:tunnel-type-vxlan",
1926 "ip": "<ip_address_of_ovs>",
1928 "node-connector-id": "openflow:123456:1"
1933 "id": "openflow:654321",
1934 "ofoverlay:tunnel": [
1936 "tunnel-type": "overlay:tunnel-type-vxlan",
1937 "ip": "<ip_address_of_ovs>",
1939 "node-connector-id": "openflow:654321:1"
1947 **Tenants** see `Policy Resolution <#policyresolution>`__ and
1948 `Forwarding Model <#forwarding>`__ for details:
1958 "name": "allow-http-clause",
1960 "allow-http-subject",
1961 "allow-icmp-subject"
1968 "name": "allow-http-subject",
1987 "name": "allow-http-rule"
1992 "name": "allow-icmp-subject",
2006 "name": "allow-icmp-rule"
2015 "consumer-named-selector": [
2024 "provider-named-selector": []
2027 "consumer-named-selector": [],
2029 "provider-named-selector": [
2040 "l2-bridge-domain": [
2046 "l2-flood-domain": [
2062 "subject-feature-instances": {
2063 "classifier-instance": [
2065 "classifier-definition-id": "<id>",
2066 "name": "http-dest",
2067 "parameter-value": [
2079 "classifier-definition-id": "<id>",
2081 "parameter-value": [
2088 "name": "sourceport"
2093 "classifier-definition-id": "<id>",
2095 "parameter-value": [
2103 "action-instance": [
2106 "action-definition-id": "<id>"
2113 "ip-prefix": "<ip_prefix>",
2115 "virtual-router-ip": "<ip address>"
2119 "ip-prefix": "<ip prefix>",
2121 "virtual-router-ip": "<ip address>"
2130 Comprehensive tutorials, along with a demonstration environment
2131 leveraging Vagrant can be found on the `**GBP**
2132 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__
2134 Using the GBP eBPF IO Visor Agent renderer
2135 ------------------------------------------
2140 The IO Visor renderer feature enables container endpoints (e.g. Docker,
2141 LXC) to leverage GBP policies.
2143 The renderer interacts with a IO Visor module from the Linux Foundation
2146 Installing and Pre-requisites
2147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2149 From the Karaf console in OpenDaylight:
2153 feature:install odl-groupbasedpolicy-iovisor odl-restconf
2155 Installation details, usage, and other information for the IO Visor GBP
2156 module can be found here: `**IO Visor** github repo for IO
2157 Modules <https://github.com/iovisor/iomodules>`__
2159 Using the GBP FaaS renderer
2160 ---------------------------
2165 The FaaS renderer feature enables leveraging the FaaS project as a GBP
2168 Installing and Pre-requisites
2169 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2171 From the Karaf console in OpenDaylight:
2175 feature:install odl-groupbasedpolicy-faas
2177 More information about FaaS can be found here:
2178 https://wiki.opendaylight.org/view/FaaS:GBPIntegration
2180 Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay
2181 ---------------------------------------------------------------------------
2186 Please refer to the Service Function Chaining project for specifics on
2187 SFC provisioning and theory.
2189 **GBP** allows for the use of a chain, by name, in policy.
2191 This takes the form of an *action* in **GBP**.
2193 Using the `**GBP** demo and development environment <#demo>`__ as an
2196 .. figure:: ./images/groupbasedpolicy/sfc-1-topology.png
2197 :alt: GBP and SFC integration environment
2199 GBP and SFC integration environment
2201 In the topology above, a symmetrical chain between H35\_2 and H36\_3
2204 H35\_2 to sw1 to sff1 to sf1 to sff1 to sff2 to sf2 to sff2 to sw6 to
2207 If symmetric chaining was desired, the return path is:
2209 .. figure:: ./images/groupbasedpolicy/sfc-2-symmetric.png
2210 :alt: GBP and SFC symmetric chain environment
2212 GBP and SFC symmetric chain environment
2214 If asymmetric chaining was desired, the return path could be direct, or
2215 an **entirely different chain**.
2217 .. figure:: ./images/groupbasedpolicy/sfc-3-asymmetric.png
2218 :alt: GBP and SFC assymmetric chain environment
2220 GBP and SFC assymmetric chain environment
2222 All these scenarios are supported by the integration.
2224 In the **Subject Feature Instance** section of the tenant config, we
2225 define the instances of the classifier definitions for ICMP and HTTP:
2229 "subject-feature-instances": {
2230 "classifier-instance": [
2233 "parameter-value": [
2241 "name": "http-dest",
2242 "parameter-value": [
2255 "parameter-value": [
2262 "name": "sourceport"
2268 Then the action instances to associate to traffic that matches
2269 classifiers are defined.
2271 Note the *SFC chain name* must exist in SFC, and is validated against
2272 the datastore once the tenant configuration is entered, before entering
2273 a valid tenant configuration into the operational datastore (which
2274 triggers policy resolution).
2278 "action-instance": [
2281 "parameter-value": [
2283 "name": "sfc-chain-name",
2284 "string-value": "SFCGBP"
2294 When ICMP is matched, allow the traffic:
2302 "name": "icmp-subject",
2305 "name": "allow-icmp-rule",
2323 When HTTP is matched, **in** to the provider of the contract with a TCP
2324 destination port of 80 (HTTP) or the HTTP request. The chain action is
2325 triggered, and similarly **out** from the provider for traffic with TCP
2326 source port of 80 (HTTP), or the HTTP response.
2331 "name": "http-subject",
2334 "name": "http-chain-rule-in",
2337 "name": "http-dest",
2349 "name": "http-chain-rule-out",
2366 To enable asymmetrical chaining, for instance, the user desires that
2367 HTTP requests traverse the chain, but the HTTP response does not, the
2368 HTTP response is set to *allow* instead of chain:
2373 "name": "http-chain-rule-out",
2388 Demo/Development environment
2389 ----------------------------
2391 The **GBP** project for Beryllium has two demo/development environments.
2393 - Docker based GBP and GBP+SFC integration Vagrant environment
2395 - DevStack based GBP+Neutron integration Vagrant environment
2398 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo>`__