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 this 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, Contract
106 GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
108 .. figure:: ./images/groupbasedpolicy/GBPTerminology2.png
109 :alt: GBP Access Model Terminology - Subject, Classifier, Action
111 GBP Access Model Terminology - Subject, Classifier, Action
113 .. figure:: ./images/groupbasedpolicy/GBPTerminology3.png
114 :alt: GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2 Flood Context/Domain, Subnet
116 GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2
117 Flood Context/Domain, Subnet
121 Define concrete uniquely identifiable entities. In this release,
122 examples could be a Docker container, or a Neutron port
126 EndpointGroups are sets of endpoints that share a common set of
127 policies. EndpointGroups can participate in contracts that determine
128 the kinds of communication that are allowed. EndpointGroups *consume*
129 and *provide* contracts. They also expose both *requirements and
130 capabilities*, which are labels that help to determine how contracts
131 will be applied. An EndpointGroup can specify a parent EndpointGroup
132 from which it inherits.
136 Contracts determine which endpoints can communicate and in what way.
137 Contracts between pairs of EndpointGroups are selected by the
138 contract selectors defined by the EndpointGroup. Contracts expose
139 qualities, which are labels that can help EndpointGroups to select
140 contracts. Once the contract is selected, contracts have clauses that
141 can match against requirements and capabilities exposed by
142 EndpointGroups, as well as any conditions that may be set on
143 endpoints, in order to activate subjects that can allow specific
144 kinds of communication. A contract is allowed to specify a parent
145 contract from which it inherits.
149 Subjects describe some aspect of how two endpoints are allowed to
150 communicate. Subjects define an ordered list of rules that will match
151 against the traffic and perform any necessary actions on that
152 traffic. No communication is allowed unless a subject allows that
157 Clauses are defined as part of a contract. Clauses determine how a
158 contract should be applied to particular endpoints and
159 EndpointGroups. Clauses can match against requirements and
160 capabilities exposed by EndpointGroups, as well as any conditions
161 that may be set on endpoints. Matching clauses define some set of
162 subjects which can be applied to the communication between the pairs
165 Architecture and Value Proposition
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168 **GBP** offers an intent based interface, accessed via the :ref:`UX <gbp-ux>`,
169 via the `REST API <#REST>`__ or directly from a domain-specific-language
170 such as :ref:`Neutron <gbp-neutron>` through a mapping interface.
172 There are two models in **GBP**:
174 - the access (or core) model
176 - the forwarding model
178 .. figure:: ./images/groupbasedpolicy/GBP_AccessModel_simple.png
179 :alt: GBP Access (or Core) Model
181 GBP Access (or Core) Model
183 The *classifier* and *action* portions of the model can be thought of as
184 hooks, with their definition provided by each *renderer* about its
185 domain specific capabilities. In **GBP** for this release, there is one
186 renderer, the :ref:`OpenFlow Overlay renderer (OfOverlay). <gbp-of-overlay>`
188 These hooks are filled with *definitions* of the types of *features* the
189 renderer can provide the *subject*, and are called
190 **subject-feature-definitions**.
192 This means an *expressed intent* can be fulfilled by, and across,
193 multiple renderers simultaneously, without any specific provisioning
194 from the consumer of **GBP**.
196 Since **GBP** is implemented in OpenDaylight, which is an SDN
197 controller, it also must address networking. This is done via the
198 *forwarding model*, which is domain specific to networking, but could be
199 applied to many different *types* of networking.
201 .. figure:: ./images/groupbasedpolicy/GBP_ForwardingModel_simple.png
202 :alt: GBP Forwarding Model
206 Each endpoint is provisioned with a *network-containment*. This can be
211 - normal IP stack behaviour, where ARP is performed in subnet, and
212 for out of subnet, traffic is sent to default gateway.
214 - a subnet can be a child of any of the below forwarding model
215 contexts, but typically would be a child of a flood-domain
219 - allows flooding behaviour.
221 - is a n:1 child of a bridge-domain
223 - can have multiple children
227 - is a layer2 namespace
229 - is the realm where traffic can be sent at layer 2
231 - is a n:1 child of a L3 context
233 - can have multiple children
237 - is a layer3 namespace
239 - is the realm where traffic is passed at layer 3
241 - is a n:1 child of a tenant
243 - can have multiple children
245 A simple example of how the access and forwarding models work is as
248 .. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Contract.png
249 :alt: GBP Endpoints, EndpointGroups and Contracts
251 GBP Endpoints, EndpointGroups and Contracts
253 In this example, the **EPG:webservers** is *providing* the *web* and
254 *ssh* contracts. The **EPG:client** is consuming those contracts.
255 **EPG:client** is providing the *any* contract, which is consumed by
258 The *direction* keyword is always from the perspective of the *provider*
259 of the contract. In this case contract *web*, being *provided* by
260 **EPG:webservers**, with the classifier to match TCP destination port
263 - packets with a TCP destination port of 80
265 - sent to (*in*) endpoints in the **EPG:webservers**
269 .. figure:: ./images/groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png
270 :alt: GBP Endpoints and the Forwarding Model
272 GBP Endpoints and the Forwarding Model
274 When the forwarding model is considered in the figure above, it can be
275 seen that even though all endpoints are communicating using a common set
276 of contracts, their forwarding is *contained* by the forwarding model
277 contexts or namespaces. In the example shown, the endpoints associated
278 with a *network-containment* that has an ultimate parent of
279 *L3Context:Sales* can only communicate with other endpoints within this
280 L3Context. In this way L3VPN services can be implemented without any
281 impact to the **Intent** of the contract.
283 High-level implementation Architecture
284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
286 The overall architecture, including :ref:`Neutron <gbp-neutron>` domain
287 specific mapping, and the :ref:`OpenFlow Overlay renderer <gbp-of-overlay>`
290 .. figure:: ./images/groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png
291 :alt: GBP High Level Architecture
293 GBP High Level Architecture
295 The major benefit of this architecture is that the mapping of the
296 domain-specific-language is completely separate and independent of the
297 underlying renderer implementation.
299 For instance, using the :ref:`Neutron Mapper <gbp-neutron>`, which maps the
300 Neutron API to the **GBP** core model, any contract automatically
301 generated from this mapping can be augmented via the :ref:`UX <gbp-ux>` to use
302 :ref:`Service Function Chaining <gbp-sfc>`, a capability not currently
303 available in OpenStack Neutron.
305 When another renderer is added, for instance, NetConf, the same policy
306 can now be leveraged across NetConf devices simultaneously:
308 .. figure:: ./images/groupbasedpolicy/GBP_High-levelExtraRenderer.png
309 :alt: GBP High Level Architecture - adding a renderer
311 GBP High Level Architecture - adding a renderer
313 As other domain-specific mappings occur, they too can leverage the same
314 renderers, as the renderers only need to implement the **GBP** access
315 and forwarding models, and the domain-specific mapping need only manage
316 mapping to the access and forwarding models. For instance:
318 .. figure:: ./images/groupbasedpolicy/High-levelBerylliumArchitectureEvolution2.png
319 :alt: GBP High Level Architecture - adding a renderer
321 GBP High Level Architecture - adding a renderer
323 In summary, the **GBP** architecture:
325 - separates concerns: the Expressed Intent is kept completely separated
326 from the underlying renderers.
328 - is cohesive: each part does it’s part and it’s part only
330 - is scalable: code can be optimised around model
331 mapping/implementation, and functionality re-used
339 The first step in policy resolution is to select the contracts that are
342 EndpointGroups participate in contracts either as a *provider* or as a
343 *consumer* of a contract. Each EndpointGroup can participate in many
344 contracts at the same time, but for each contract it can be in only one
345 role at a time. In addition, there are two ways for an EndpointGroup to
346 select a contract: either with either a:
350 Named selectors simply select a specific contract by its contract ID.
354 Target selectors allow for additional flexibility by matching against
355 *qualities* of the contract’s *target.*
357 Thus, there are a total of 4 kinds of contract selector:
359 - provider named selector
361 Select a contract by contract ID, and participate as a provider.
363 - provider target selector
365 Match against a contract’s target with a quality matcher, and
366 participate as a provider.
368 - consumer named selector
370 Select a contract by contract ID, and participate as a consumer.
372 - consumer target selector
374 Match against a contract’s target with a quality matcher, and
375 participate as a consumer.
377 To determine which contracts are in scope, contracts are found where
378 either the source EndpointGroup selects a contract as either a provider
379 or consumer, while the destination EndpointGroup matches against the
380 same contract in the corresponding role. So if endpoint *x* in
381 EndpointGroup *X* is communicating with endpoint *y* in EndpointGroup
382 *Y*, a contract *C* is in scope if either *X* selects *C* as a provider
383 and *Y* selects *C* as a consumer, or vice versa.
385 The details of how quality matchers work are described further in
386 `Matchers <#Matchers>`__. Quality matchers provide a flexible mechanism
387 for contract selection based on labels.
389 The end result of the contract selection phase can be thought of as a
390 set of tuples representing selected contract scopes. The fields of the
395 - The provider EndpointGroup ID
397 - The name of the selector in the provider EndpointGroup that was used
398 to select the contract, called the *matching provider selector.*
400 - The consumer EndpointGroup ID
402 - The name of the selector in the consumer EndpointGroup that was used
403 to select the contract, called the *matching consumer selector.*
405 The result is then stored in the datastore under **Resolved Policy**.
410 The second phase in policy resolution is to determine which subjects are
411 in scope. The subjects define what kinds of communication are allowed
412 between endpoints in the EndpointGroups. For each of the selected
413 contract scopes from the contract selection phase, the subject selection
414 procedure is applied.
416 Labels called, capabilities, requirements and conditions are matched
417 against to bring a Subject *into scope*. EndpointGroups have
418 capabilities and requirements, while endpoints have conditions.
420 Requirements and Capabilities
421 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
423 When acting as a *provider*, EndpointGroups expose *capabilities,* which
424 are labels representing specific pieces of functionality that can be
425 exposed to other EndpointGroups that may meet functional requirements of
426 those EndpointGroups.
428 When acting as a *consumer*, EndpointGroups expose *requirements*, which
429 are labels that represent that the EndpointGroup requires some specific
430 piece of functionality.
432 As an example, we might create a capability called "user-database" which
433 indicates that an EndpointGroup contains endpoints that implement a
436 We might create a requirement also called "user-database" to indicate an
437 EndpointGroup contains endpoints that will need to communicate with the
438 endpoints that expose this service.
440 Note that in this example the requirement and capability have the same
441 name, but the user need not follow this convention.
443 The matching provider selector (that was used by the provider
444 EndpointGroup to select the contract) is examined to determine the
445 capabilities exposed by the provider EndpointGroup for this contract
448 The provider selector will have a list of capabilities either directly
449 included in the provider selector or inherited from a parent selector or
450 parent EndpointGroup. (See `Inheritance <#Inheritance>`__).
452 Similarly, the matching consumer selector will expose a set of
458 Endpoints can have *conditions*, which are labels representing some
459 relevant piece of operational state related to the endpoint.
461 An example of a condition might be "malware-detected," or
462 "authentication-succeeded." Conditions are used to affect how that
463 particular endpoint can communicate.
465 To continue with our example, the "malware-detected" condition might
466 cause an endpoint’s connectivity to be cut off, while
467 "authentication-succeeded" might open up communication with services
468 that require an endpoint to be first authenticated and then forward its
469 authentication credentials.
474 Clauses perform the actual selection of subjects. A clause has lists of
475 matchers in two categories. In order for a clause to become active, all
476 lists of matchers must match. A matching clause will select all the
477 subjects referenced by the clause. Note that an empty list of matchers
480 The first category is the consumer matchers, which match against the
481 consumer EndpointGroup and endpoints. The consumer matchers are:
483 - Group Idenfication Constraint: Requirement matchers
485 Matches against requirements in the matching consumer selector.
487 - Group Identification Constraint: GroupName
489 Matches against the group name
491 - Consumer condition matchers
493 Matches against conditions on endpoints in the consumer EndpointGroup
495 - Consumer Endpoint Identification Constraint
497 Label based criteria for matching against endpoints. In this release
498 this can be used to label endpoints based on IpPrefix.
500 The second category is the provider matchers, which match against the
501 provider EndpointGroup and endpoints. The provider matchers are:
503 - Group Idenfication Constraint: Capability matchers
505 Matches against capabilities in the matching provider selector.
507 - Group Identification Constraint: GroupName
509 Matches against the group name
511 - Consumer condition matchers
513 Matches against conditions on endpoints in the provider EndpointGroup
515 - Consumer Endpoint Identification Constraint
517 Label based criteria for matching against endpoints. In this release
518 this can be used to label endpoints based on IpPrefix.
520 Clauses have a list of subjects that apply when all the matchers in the
521 clause match. The output of the subject selection phase logically is a
522 set of subjects that are in scope for any particular pair of endpoints.
527 Now subjects have been selected that apply to the traffic between a
528 particular set of endpoints, policy can be applied to allow endpoints to
529 communicate. The applicable subjects from the previous step will each
530 contain a set of rules.
532 Rules consist of a set of *classifiers* and a set of *actions*.
533 Classifiers match against traffic between two endpoints. An example of a
534 classifier would be something that matches against all TCP traffic on
535 port 80, or one that matches against HTTP traffic containing a
536 particular cookie. Actions are specific actions that need to be taken on
537 the traffic before it reaches its destination. Actions could include
538 tagging or encapsulating the traffic in some way, redirecting the
539 traffic, or applying a :ref:`service function chain <gbp-sfc>`.
541 Rules, subjects, and actions have an *order* parameter, where a lower
542 order value means that a particular item will be applied first. All
543 rules from a particular subject will be applied before the rules of any
544 other subject, and all actions from a particular rule will be applied
545 before the actions from another rule. If more than item has the same
546 order parameter, ties are broken with a lexicographic ordering of their
547 names, with earlier names having logically lower order.
552 Matchers specify a set of labels (which include requirements,
553 capabilities, conditions, and qualities) to match against. There are
554 several kinds of matchers that operate similarly:
558 used in target selectors during the contract selection phase. Quality
559 matchers provide a more advanced and flexible way to select contracts
560 compared to a named selector.
562 - Requirement and capability matchers
564 used in clauses during the subject selection phase to match against
565 requirements and capabilities on EndpointGroups
569 used in clauses during the subject selection phase to match against
570 conditions on endpoints
572 A matcher is, at its heart, fairly simple. It will contain a list of
573 label names, along with a *match type*. The match type can be either:
577 which means the matcher matches when all of its labels match
581 which means the matcher matches when any of its labels match,
585 which means the matcher matches when none of its labels match.
587 Note a *match all* matcher can be made by matching against an empty set
588 of labels with a match type of "all."
590 Additionally each label to match can optionally include a relevant name
591 field. For quality matchers, this is a target name. For capability and
592 requirement matchers, this is a selector name. If the name field is
593 specified, then the matcher will only match against targets or selectors
594 with that name, rather than any targets or selectors.
599 Some objects in the system include references to parents, from which
600 they will inherit definitions. The graph of parent references must be
601 loop free. When resolving names, the resolution system must detect loops
602 and raise an exception. Objects that are part of these loops may be
603 considered as though they are not defined at all. Generally, inheritance
604 works by simply importing the objects in the parent into the child
605 object. When there are objects with the same name in the child object,
606 then the child object will override the parent object according to rules
607 which are specific to the type of object. We’ll next explore the
608 detailed rules for inheritance for each type of object
612 EndpointGroups will inherit all their selectors from their parent
613 EndpointGroups. Selectors with the same names as selectors in the parent
614 EndpointGroups will inherit their behavior as defined below.
618 Selectors include provider named selectors, provider target selectors,
619 consumer named selectors, and consumer target selectors. Selectors
620 cannot themselves have parent selectors, but when selectors have the
621 same name as a selector of the same type in the parent EndpointGroup,
622 then they will inherit from and override the behavior of the selector in
623 the parent EndpointGroup.
627 Named selectors will add to the set of contract IDs that are selected by
628 the parent named selector.
632 A target selector in the child EndpointGroup with the same name as a
633 target selector in the parent EndpointGroup will inherit quality
634 matchers from the parent. If a quality matcher in the child has the same
635 name as a quality matcher in the parent, then it will inherit as
636 described below under Matchers.
640 Contracts will inherit all their targets, clauses and subjects from
641 their parent contracts. When any of these objects have the same name as
642 in the parent contract, then the behavior will be as defined below.
646 Targets cannot themselves have a parent target, but it may inherit from
647 targets with the same name as the target in a parent contract. Qualities
648 in the target will be inherited from the parent. If a quality with the
649 same name is defined in the child, then this does not have any semantic
650 effect except if the quality has its inclusion-rule parameter set to
651 "exclude." In this case, then the label should be ignored for the
652 purpose of matching against this target.
656 Subjects cannot themselves have a parent subject, but it may inherit
657 from a subject with the same name as the subject in a parent contract.
658 The order parameter in the child subject, if present, will override the
659 order parameter in the parent subject. The rules in the parent subject
660 will be added to the rules in the child subject. However, the rules will
661 not override rules of the same name. Instead, all rules in the parent
662 subject will be considered to run with a higher order than all rules in
663 the child; that is all rules in the child will run before any rules in
664 the parent. This has the effect of overriding any rules in the parent
665 without the potentially-problematic semantics of merging the ordering.
669 Clauses cannot themselves have a parent clause, but it may inherit from
670 a clause with the same name as the clause in a parent contract. The list
671 of subject references in the parent clause will be added to the list of
672 subject references in the child clause. This is just a union operation.
673 A subject reference that refers to a subject name in the parent contract
674 might have that name overridden in the child contract. Each of the
675 matchers in the clause are also inherited by the child clause. Matchers
676 in the child of the same name and type as a matcher from the parent will
677 inherit from and override the parent matcher. See below under Matchers
678 for more information.
682 Matchers include quality matchers, condition matchers, requirement
683 matchers, and capability matchers. Matchers cannot themselves have
684 parent matchers, but when there is a matcher of the same name and type
685 in the parent object, then the matcher in the child object will inherit
686 and override the behavior of the matcher in the parent object. The match
687 type, if specified in the child, overrides the value specified in the
688 parent. Labels are also inherited from the parent object. If there is a
689 label with the same name in the child object, this does not have any
690 semantic effect except if the label has its inclusion-rule parameter set
691 to "exclude." In this case, then the label should be ignored for the
692 purpose of matching. Otherwise, the label with the same name will
693 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 :ref:`OfOverlay <gbp-of-overlay>` 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 :ref:`Service Function Chaining <gbp-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 - :ref:`gbp-of-overlay`
1213 - `Policy Resolution`_
1215 - `Forwarding Model <#forwarding>`__
1217 - `the **GBP** demo and development environments for tips <#demo>`__
1219 It is recommended to use either:
1221 - `Neutron mapper <gbp-neutron>`
1223 - :ref:`the UX <gbp-ux>`
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``
1232 and select YangUI from the left menu.
1234 to explore the various **GBP** REST options
1238 Using OpenStack with GBP
1239 ------------------------
1244 This section is for Application Developers and Network Administrators
1245 who are looking to integrate Group Based Policy with OpenStack.
1247 To enable the **GBP** Neutron Mapper feature, at the Karaf console:
1251 feature:install odl-groupbasedpolicy-neutronmapper
1253 Neutron Mapper has the following dependencies that are automatically
1260 Neutron Northbound implementing REST API used by OpenStack
1264 odl-groupbasedpolicy-base
1266 Base **GBP** feature set, such as policy resolution, data model etc.
1270 odl-groupbasedpolicy-ofoverlay
1272 REST calls from OpenStack Neutron are by the Neutron NorthBound project.
1274 **GBP** provides the implementation of the `Neutron V2.0
1275 API <http://developer.openstack.org/api-ref-networking-v2.html>`_.
1280 List of supported Neutron entities:
1288 - External provider L2/L3 network
1296 - Distributed functionality with local routing per compute
1298 - External gateway access per compute node (dedicated port required)
1300 - Multiple routers per tenant
1306 The mapping of Neutron entities to **GBP** entities is as follows:
1310 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
1315 The Neutron port is mapped to an endpoint.
1317 The current implementation supports one IP address per Neutron port.
1319 An endpoint and L3-endpoint belong to multiple EndpointGroups if the
1320 Neutron port is in multiple Neutron Security Groups.
1322 The key for endpoint is L2-bridge-domain obtained as the parent of
1323 L2-flood-domain representing Neutron network. The MAC address is from
1324 the Neutron port. An L3-endpoint is created based on L3-context (the
1325 parent of the L2-bridge-domain) and IP address of Neutron Port.
1329 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
1330 :alt: Neutron Network
1334 A Neutron network has the following characteristics:
1336 - defines a broadcast domain
1338 - defines a L2 transmission domain
1340 - defines a L2 name space.
1342 To represent this, a Neutron Network is mapped to multiple **GBP**
1343 entities. The first mapping is to an L2 flood-domain to reflect that the
1344 Neutron network is one flooding or broadcast domain. An L2-bridge-domain
1345 is then associated as the parent of L2 flood-domain. This reflects both
1346 the L2 transmission domain as well as the L2 addressing namespace.
1348 The third mapping is to L3-context, which represents the distinct L3
1349 address space. The L3-context is the parent of L2-bridge-domain.
1353 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
1354 :alt: Neutron Subnet
1358 Neutron subnet is associated with a Neutron network. The Neutron subnet
1359 is mapped to a **GBP** subnet where the parent of the subnet is
1360 L2-flood-domain representing the Neutron network.
1362 **Neutron Security Group**
1364 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
1365 :alt: Neutron Security Group and Rules
1367 Neutron Security Group and Rules
1369 **GBP** entity representing Neutron security-group is EndpointGroup.
1371 **Infrastructure EndpointGroups**
1373 Neutron-mapper automatically creates EndpointGroups to manage key
1374 infrastructure items such as:
1376 - DHCP EndpointGroup - contains endpoints representing Neutron DHCP
1379 - Router EndpointGroup - contains endpoints representing Neutron router
1382 - External EndpointGroup - holds L3-endpoints representing Neutron
1383 router gateway ports, also associated with FloatingIP ports.
1385 **Neutron Security Group Rules**
1387 This is the most involved amongst all the mappings because Neutron
1388 security-group-rules are mapped to contracts with clauses, subjects,
1389 rules, action-refs, classifier-refs, etc. Contracts are used between
1390 EndpointGroups representing Neutron Security Groups. For simplification
1391 it is important to note that Neutron security-group-rules are similar to
1392 a **GBP** rule containing:
1394 - classifier with direction
1396 - action of **allow**.
1400 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
1401 :alt: Neutron Router
1405 Neutron router is represented as a L3-context. This treats a router as a
1406 Layer3 namespace, and hence every network attached to it a part of that
1409 This allows for multiple routers per tenant with complete isolation.
1411 The mapping of the router to an endpoint represents the router’s
1412 interface or gateway port.
1414 The mapping to an EndpointGroup represents the internal infrastructure
1415 EndpointGroups created by the **GBP** Neutron Mapper
1417 When a Neutron router interface is attached to a network/subnet, that
1418 network/subnet and its associated endpoints or Neutron Ports are
1419 seamlessly added to the namespace.
1421 **Neutron FloatingIP**
1423 When associated with a Neutron Port, this leverages the
1424 :ref:`OfOverlay <gbp-of-overlay>` renderer’s NAT capabilities.
1426 A dedicated *external* interface on each Nova compute host allows for
1427 disitributed external access. Each Nova instance associated with a
1428 FloatingIP address can access the external network directly without
1429 having to route via the Neutron controller, or having to enable any form
1430 of Neutron distributed routing functionality.
1432 Assuming the gateway provisioned in the Neutron Subnet command for the
1433 external network is reachable, the combination of **GBP** Neutron Mapper
1434 and :ref:`OfOverlay renderer <gbp-of-overlay>` will automatically ARP for this
1435 default gateway, requiring no user intervention.
1437 **Troubleshooting within GBP**
1439 Logging level for the mapping functionality can be set for package
1440 org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling
1441 TRACE logging level on Karaf console:
1445 log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
1447 **Neutron mapping example**
1449 As an example for mapping can be used creation of Neutron network,
1450 subnet and port. When a Neutron network is created 3 **GBP** entities
1451 are created: l2-flood-domain, l2-bridge-domain, l3-context.
1453 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
1454 :alt: Neutron network mapping
1456 Neutron network mapping
1458 After an subnet is created in the network mapping looks like this.
1460 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
1461 :alt: Neutron subnet mapping
1463 Neutron subnet mapping
1465 If an Neutron port is created in the subnet an endpoint and l3-endpoint
1466 are created. The endpoint has key composed from l2-bridge-domain and MAC
1467 address from Neutron port. A key of l3-endpoint is compesed from
1468 l3-context and IP address. The network containment of endpoint and
1469 l3-endpoint points to the subnet.
1471 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
1472 :alt: Neutron port mapping
1474 Neutron port mapping
1476 Configuring GBP Neutron
1477 ~~~~~~~~~~~~~~~~~~~~~~~
1479 No intervention passed initial OpenStack setup is required by the user.
1481 More information about configuration can be found in our DevStack demo
1482 environment on the `GBP
1483 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`_.
1485 Administering or Managing GBP Neutron
1486 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1488 For consistencies sake, all provisioning should be performed via the
1489 Neutron API. (CLI or Horizon).
1491 The mapped policies can be augmented via the **GBP** :ref:`UX <gbp-ux>`, to:
1493 - Enable :ref:`Service Function Chaining <gbp-sfc>`
1495 - Add endpoints from outside of Neutron i.e. VMs/containers not
1496 provisioned in OpenStack
1498 - Augment policies/contracts derived from Security Group Rules
1500 - Overlay additional contracts or groupings
1505 A DevStack demo environment can be found on the `GBP
1506 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`_.
1508 GBP Renderer manager
1509 --------------------
1514 The GBP Renderer manager is an integral part of **GBP** base module.
1515 It dispatches information about endpoints'
1516 policy configuration to specific device renderer
1517 by writing a renderer policy configuration into the
1518 registered renderer's policy store.
1520 Installing and Pre-requisites
1521 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1523 Renderer manager is integrated into GBP base module,
1524 so no additional installation is required.
1529 Renderer manager gets data notifications about:
1531 - Endoints (base-endpoint.yang)
1533 - EndpointLocations (base-endpoint.yang)
1535 - ResolvedPolicies (resolved-policy.yang)
1537 - Forwarding (forwarding.yang)
1539 Based on data from notifications it creates a configuration task for
1540 specific renderers by writing a renderer policy configuration into the
1541 registered renderer's policy store.
1542 Configuration is stored to CONF data store as Renderers (renderer.yang).
1544 Configuration is signed with version number which is incremented by every change.
1545 All renderers are supposed to be on the same version. Renderer manager waits
1546 for all renderers to respond with version update in OPER data store.
1547 After a version of every renderer in OPER data store has the same value
1548 as the one in CONF data store,
1549 renderer manager moves to the next configuration with incremented version.
1551 GBP Location manager
1552 --------------------
1557 Location manager monitors information about Endpoint Location providers
1558 (see endpoint-location-provider.yang) and manages Endpoint locations in OPER data store accordingly.
1560 Installing and Pre-requisites
1561 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1563 Location manager is integrated into GBP base module,
1564 so no additional installation is required.
1569 The endpoint-locations container in OPER data store (see base-endpoint.yang)
1570 contains two lists for two types of EP location,
1571 namely address-endpoint-location and containment-endpoint-location.
1572 LocationResolver is a class that processes Location providers in CONF data store
1573 and puts location information to OPER data store.
1575 When a new Location provider is created in CONF data store, its Address EP locations
1576 are being processed first, and their info is stored locally in accordance with processed
1577 Location provider's priority. Then a location of type "absolute" with the highest priority
1578 is selected for an EP, and is put in OPER data store. If Address EP locations contain
1579 locations of type "relative", those are put to OPER data store.
1581 If current Location provider contains Containment EP locations of type "relative",
1582 then those are put to OPER data store.
1584 Similarly, when a Location provider is deleted, information of its locations
1585 is removed from the OPER data store.
1589 Using the GBP OpenFlow Overlay (OfOverlay) renderer
1590 ---------------------------------------------------
1595 The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
1596 renderer, which creates a network virtualization solution across nodes
1597 that host Open vSwitch software switches.
1599 Installing and Pre-requisites
1600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1602 From the Karaf console in OpenDaylight:
1606 feature:install odl-groupbasedpolicy-ofoverlay
1608 This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although
1609 2.3 is strongly recommended) and OpenFlow 1.3.
1611 When used in conjunction with the :ref:`Neutron Mapper feature <gbp-neutron>`
1612 no extra OfOverlay specific setup is required.
1614 When this feature is loaded "standalone", the user is required to
1615 configure infrastructure, such as
1617 - instantiating OVS bridges,
1619 - attaching hosts to the bridges,
1621 - and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
1625 The **GBP** OfOverlay renderer also supports a table offset option, to
1626 offset the pipeline post-table 0. The value of table offset is stored in
1627 the config datastore and it may be rewritten at runtime.
1631 PUT http://{{controllerIp}}:8181/restconf/config/ofoverlay:of-overlay-config
1633 "of-overlay-config": {
1634 "gbp-ofoverlay-table-offset": 6
1638 The default value is set by changing:
1639 <gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
1642 distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
1644 To avoid overwriting runtime changes, the default value is used only
1645 when the OfOverlay renderer starts and no other value has been written
1648 OpenFlow Overlay Architecture
1649 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1651 These are the primary components of **GBP**. The OfOverlay components
1652 are highlighted in red.
1654 .. figure:: ./images/groupbasedpolicy/ofoverlay-1-components.png
1655 :alt: OfOverlay within **GBP**
1657 OfOverlay within **GBP**
1659 In terms of the inner components of the **GBP** OfOverlay renderer:
1661 .. figure:: ./images/groupbasedpolicy/ofoverlay-2-components.png
1662 :alt: OfOverlay expanded view:
1664 OfOverlay expanded view:
1666 **OfOverlay Renderer**
1668 Launches components below:
1672 Policy resolution is completely domain independent, and the OfOverlay
1673 leverages process policy information internally. See `Policy Resolution
1674 process <Policy Resolution>`_.
1676 It listens to inputs to the *Tenants* configuration datastore, validates
1677 tenant input, then writes this to the Tenants operational datastore.
1679 From there an internal notification is generated to the PolicyManager.
1681 In the next release, this will be moving to a non-renderer specific
1684 **Endpoint Manager**
1686 The endpoint repository operates in **orchestrated** mode. This means
1687 the user is responsible for the provisioning of endpoints via:
1689 - :ref:`UX/GUI <gbp-ux>`
1695 When using the :ref:`Neutron mapper <gbp-neutron>` feature, everything is
1696 managed transparently via Neutron.
1698 The Endpoint Manager is responsible for listening to Endpoint repository
1699 updates and notifying the Switch Manager when a valid Endpoint has been
1702 It also supplies utility functions to the flow pipeline process.
1706 The Switch Manager is purely a state manager.
1708 Switches are in one of 3 states:
1716 **Ready** is denoted by a connected switch:
1718 - having a tunnel interface
1720 - having at least one endpoint connected.
1722 In this way **GBP** is not writing to switches it has no business to.
1724 **Preparing** simply means the switch has a controller connection but is
1725 missing one of the above *complete and necessary* conditions
1727 **Disconnected** means a previously connected switch is no longer
1728 present in the Inventory operational datastore.
1730 .. figure:: ./images/groupbasedpolicy/ofoverlay-3-flowpipeline.png
1731 :alt: OfOverlay Flow Pipeline
1733 OfOverlay Flow Pipeline
1735 The OfOverlay leverages Nicira registers as follows:
1737 - REG0 = Source EndpointGroup + Tenant ordinal
1739 - REG1 = Source Conditions + Tenant ordinal
1741 - REG2 = Destination EndpointGroup + Tenant ordinal
1743 - REG3 = Destination Conditions + Tenant ordinal
1745 - REG4 = Bridge Domain + Tenant ordinal
1747 - REG5 = Flood Domain + Tenant ordinal
1749 - REG6 = Layer 3 Context + Tenant ordinal
1753 Table 0 of the OpenFlow pipeline. Responsible for ensuring that only
1754 valid connections can send packets into the pipeline:
1758 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1759 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1760 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
1761 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
1762 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
1763 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1764 cookie=0x0, <snip> , priority=111, ip actions=drop
1765 cookie=0x0, <snip> , priority=110,arp actions=drop
1766 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1767 cookie=0x0, <snip> , priority=1 actions=drop
1769 Ingress from tunnel interface, go to Table *Source Mapper*:
1773 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1775 Ingress from outside, goto Table *Ingress NAT Mapper*:
1779 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1781 ARP from Endpoint, go to Table *Source Mapper*:
1785 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
1787 IPv4 from Endpoint, go to Table *Source Mapper*:
1791 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
1793 DHCP DORA from Endpoint, go to Table *Source Mapper*:
1797 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
1799 Series of DROP tables with priority set to capture any non-specific
1800 traffic that should have matched above:
1804 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1805 cookie=0x0, <snip> , priority=111, ip actions=drop
1806 cookie=0x0, <snip> , priority=110,arp actions=drop
1808 "L2" catch all traffic not identified above:
1812 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1818 cookie=0x0, <snip> , priority=1 actions=drop
1820 **Ingress NAT Mapper**
1822 Table :ref:`offset <gbp-offset>` +1.
1824 ARP responder for external NAT address:
1828 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
1830 Translate from Outside to Inside and perform same functions as
1835 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
1839 Table :ref:`offset <gbp-offset>` +2.
1841 Determines based on characteristics from the ingress port, which:
1843 - EndpointGroup(s) it belongs to
1845 - Forwarding context
1847 - Tunnel VNID ordinal
1849 Establishes tunnels at valid destination switches for ingress.
1851 Ingress Tunnel established at remote node with VNID Ordinal that maps to
1852 Source EPG, Forwarding Context etc:
1856 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
1858 Maps endpoint to Source EPG, Forwarding Context based on ingress port,
1863 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
1869 cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
1871 **Destination Mapper**
1873 Table :ref:`offset <gbp-offset>` +3.
1875 Determines based on characteristics of the endpoint:
1877 - EndpointGroup(s) it belongs to
1879 - Forwarding context
1881 - Tunnel Destination value
1883 Manages routing based on valid ingress nodes ARP’ing for their default
1884 gateway, and matches on either gateway MAC or destination endpoint MAC.
1886 ARP for default gateway for the 10.1.1.0/24 subnet:
1890 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
1892 Broadcast traffic destined for GroupTable:
1896 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
1898 Layer3 destination matching flows, where priority=100+masklength. Since
1899 **GBP** now support L3Prefix endpoint, we can set default routes etc:
1903 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
1905 Layer2 destination matching flows, designed to be caught only after last
1906 IP flow (lowest priority IP flow is 100):
1910 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
1912 General drop flow: cookie=0x0, duration=323.207s, table=3, n\_packets=6,
1913 n\_bytes=588, priority=1 actions=drop
1917 Table :ref:`offset <gbp-offset>` +4.
1919 Once the Source and Destination EndpointGroups are assigned, policy is
1920 enforced based on resolved rules.
1922 In the case of :ref:`Service Function Chaining <gbp-sfc>`, the encapsulation
1923 and destination for traffic destined to a chain, is discovered and
1926 Policy flow, allowing IP traffic between EndpointGroups:
1930 cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
1932 **Egress NAT Mapper**
1934 Table :ref:`offset <gbp-offset>` +5.
1936 Performs NAT function before Egressing OVS instance to the underlay
1939 Inside to Outside NAT translation before sending to underlay:
1943 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
1947 Table :ref:`offset <gbp-offset>` +6.
1949 Manages post-policy enforcement for endpoint specific destination
1950 effects. Specifically for :ref:`Service Function Chaining <gbp-sfc>`, which is
1951 why we can support both symmetric and asymmetric chains and distributed
1952 ingress/egress classification.
1958 cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
1960 Configuring OpenFlow Overlay via REST
1961 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1965 Please see the :ref:`UX <gbp-ux>` section on how to configure **GBP** via
1972 POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
1975 "endpoint-group": "<epg0>",
1976 "endpoint-groups" : ["<epg1>","<epg2>"],
1977 "network-containment" : "<fowarding-model-context1>",
1978 "l2-context": "<bridge-domain1>",
1979 "mac-address": "<mac1>",
1982 "ip-address": "<ipaddress1>",
1983 "l3-context": "<l3_context1>"
1986 "*ofoverlay:port-name*": "<ovs port name>",
1987 "tenant": "<tenant1>"
1993 The usage of "port-name" preceded by "ofoverlay". In OpenDaylight,
1994 base datastore objects can be *augmented*. In **GBP**, the base
1995 endpoint model has no renderer specifics, hence can be leveraged
1996 across multiple renderers.
1998 **OVS Augmentations to Inventory**
2002 PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
2004 "opendaylight-inventory:nodes": {
2007 "id": "openflow:123456",
2008 "ofoverlay:tunnel": [
2010 "tunnel-type": "overlay:tunnel-type-vxlan",
2011 "ip": "<ip_address_of_ovs>",
2013 "node-connector-id": "openflow:123456:1"
2018 "id": "openflow:654321",
2019 "ofoverlay:tunnel": [
2021 "tunnel-type": "overlay:tunnel-type-vxlan",
2022 "ip": "<ip_address_of_ovs>",
2024 "node-connector-id": "openflow:654321:1"
2032 **Tenants** see `Policy Resolution`_ and
2033 `Forwarding Model <#forwarding>`__ for details:
2043 "name": "allow-http-clause",
2045 "allow-http-subject",
2046 "allow-icmp-subject"
2053 "name": "allow-http-subject",
2072 "name": "allow-http-rule"
2077 "name": "allow-icmp-subject",
2091 "name": "allow-icmp-rule"
2100 "consumer-named-selector": [
2109 "provider-named-selector": []
2112 "consumer-named-selector": [],
2114 "provider-named-selector": [
2125 "l2-bridge-domain": [
2131 "l2-flood-domain": [
2147 "subject-feature-instances": {
2148 "classifier-instance": [
2150 "classifier-definition-id": "<id>",
2151 "name": "http-dest",
2152 "parameter-value": [
2164 "classifier-definition-id": "<id>",
2166 "parameter-value": [
2173 "name": "sourceport"
2178 "classifier-definition-id": "<id>",
2180 "parameter-value": [
2188 "action-instance": [
2191 "action-definition-id": "<id>"
2198 "ip-prefix": "<ip_prefix>",
2200 "virtual-router-ip": "<ip address>"
2204 "ip-prefix": "<ip prefix>",
2206 "virtual-router-ip": "<ip address>"
2215 Comprehensive tutorials, along with a demonstration environment
2216 leveraging Vagrant can be found on the `GBP
2217 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__
2219 Using the GBP eBPF IO Visor Agent renderer
2220 ------------------------------------------
2225 The IO Visor renderer feature enables container endpoints (e.g. Docker,
2226 LXC) to leverage GBP policies.
2228 The renderer interacts with a IO Visor module from the Linux Foundation
2231 Installing and Pre-requisites
2232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2234 From the Karaf console in OpenDaylight:
2238 feature:install odl-groupbasedpolicy-iovisor odl-restconf
2240 Installation details, usage, and other information for the IO Visor GBP
2241 module can be found here: `IO Visor github repo for IO
2242 Modules <https://github.com/iovisor/iomodules>`_
2244 Using the GBP FaaS renderer
2245 ---------------------------
2250 The FaaS renderer feature enables leveraging the FaaS project as a GBP
2253 Installing and Pre-requisites
2254 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2256 From the Karaf console in OpenDaylight:
2260 feature:install odl-groupbasedpolicy-faas
2262 More information about FaaS can be found here:
2263 https://wiki.opendaylight.org/view/FaaS:GBPIntegration
2267 Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay
2268 ---------------------------------------------------------------------------
2273 Please refer to the Service Function Chaining project for specifics on
2274 SFC provisioning and theory.
2276 **GBP** allows for the use of a chain, by name, in policy.
2278 This takes the form of an *action* in **GBP**.
2280 Using the `GBP demo and development environment <#demo>`__ as an
2283 .. figure:: ./images/groupbasedpolicy/sfc-1-topology.png
2284 :alt: GBP and SFC integration environment
2286 GBP and SFC integration environment
2288 In the topology above, a symmetrical chain between H35\_2 and H36\_3
2291 H35\_2 to sw1 to sff1 to sf1 to sff1 to sff2 to sf2 to sff2 to sw6 to
2294 If symmetric chaining was desired, the return path is:
2296 .. figure:: ./images/groupbasedpolicy/sfc-2-symmetric.png
2297 :alt: GBP and SFC symmetric chain environment
2299 GBP and SFC symmetric chain environment
2301 If asymmetric chaining was desired, the return path could be direct, or
2302 an **entirely different chain**.
2304 .. figure:: ./images/groupbasedpolicy/sfc-3-asymmetric.png
2305 :alt: GBP and SFC assymmetric chain environment
2307 GBP and SFC assymmetric chain environment
2309 All these scenarios are supported by the integration.
2311 In the **Subject Feature Instance** section of the tenant config, we
2312 define the instances of the classifier definitions for ICMP and HTTP:
2316 "subject-feature-instances": {
2317 "classifier-instance": [
2320 "parameter-value": [
2328 "name": "http-dest",
2329 "parameter-value": [
2342 "parameter-value": [
2349 "name": "sourceport"
2355 Then the action instances to associate to traffic that matches
2356 classifiers are defined.
2358 Note the *SFC chain name* must exist in SFC, and is validated against
2359 the datastore once the tenant configuration is entered, before entering
2360 a valid tenant configuration into the operational datastore (which
2361 triggers policy resolution).
2365 "action-instance": [
2368 "parameter-value": [
2370 "name": "sfc-chain-name",
2371 "string-value": "SFCGBP"
2381 When ICMP is matched, allow the traffic:
2389 "name": "icmp-subject",
2392 "name": "allow-icmp-rule",
2410 When HTTP is matched, **in** to the provider of the contract with a TCP
2411 destination port of 80 (HTTP) or the HTTP request. The chain action is
2412 triggered, and similarly **out** from the provider for traffic with TCP
2413 source port of 80 (HTTP), or the HTTP response.
2418 "name": "http-subject",
2421 "name": "http-chain-rule-in",
2424 "name": "http-dest",
2436 "name": "http-chain-rule-out",
2453 To enable asymmetrical chaining, for instance, the user desires that
2454 HTTP requests traverse the chain, but the HTTP response does not, the
2455 HTTP response is set to *allow* instead of chain:
2460 "name": "http-chain-rule-out",
2475 Demo/Development environment
2476 ----------------------------
2478 The **GBP** project for this release has two demo/development environments.
2480 - Docker based GBP and GBP+SFC integration Vagrant environment
2482 - DevStack based GBP+Neutron integration Vagrant environment
2485 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo>`_