3 Group Based Policy User Guide
4 =============================
9 OpenDaylight Group Based Policy allows users to express network
10 configuration in a declarative versus imperative way.
12 This is often described as asking for **"what you want"**, rather than
15 In order to achieve this Group Based Policy (herein referred to as
16 **GBP**) is an implementation of an **Intent System**.
20 - is a process around an intent driven data model
22 - contains no domain specifics
24 - is capable of addressing multiple semantic definitions of intent
26 To this end, **GBP** Policy views an **Intent System** visually as:
28 .. figure:: ./images/groupbasedpolicy/IntentSystemPolicySurfaces.png
29 :alt: Intent System Process and Policy Surfaces
31 Intent System Process and Policy Surfaces
33 - **expressed intent** is the entry point into the system.
35 - **operational constraints** provide policy for the usage of the
36 system which modulates how the system is consumed. For instance *"All
37 Financial applications must use a specific encryption standard"*.
39 - **capabilities and state** are provided by *renderers*. *Renderers*
40 dynamically provide their capabilities to the core model, allowing
41 the core model to remain non-domain specific.
43 - **governance** provides feedback on the delivery of the *expressed
44 intent*. i.e. *"Did we do what you asked us?"*
46 In summary **GBP is about the Automation of Intent**.
48 By thinking of **Intent Systems** in this way, it enables:
50 - **automation of intent**
52 By focusing on **Model. Process. Automation**, a consistent policy
53 resolution process enables for mapping between the **expressed
54 intent** and renderers responsible for providing the capabilities of
55 implementing that intent.
57 - recursive/intent level-independent behaviour.
59 Where *one person’s concrete is another’s abstract*, intent can be
60 fulfilled through a hierarchical implementation of non-domain
61 specific policy resolution. Domain specifics are provided by the
62 *renderers*, and exposed via the API, at each policy resolution
63 instance. For example:
65 - To DNS: The name "www.foo.com" is *abstract*, and it’s IPv4
66 address 10.0.0.10 is *concrete*,
68 - To an IP stack: 10.0.0.10 is *abstract* and the MAC
69 08:05:04:03:02:01 is *concrete*,
71 - To an Ethernet switch: The MAC 08:05:04:03:02:01 is *abstract*,
72 the resolution to a port in it’s CAM table is *concrete*,
74 - To an optical network: The port maybe *abstract*, yet the optical
75 wavelength is *concrete*.
79 *This is a very domain specific analogy, tied to something most
80 readers will understand. It in no way implies the **GBP** should be
81 implemented in an OSI type fashion. The premise is that by
82 implementing a full **Intent System**, the user is freed from a lot
83 of the constraints of how the expressed intent is realised.*
85 It is important to show the overall philosophy of **GBP** as it sets the
88 In this release of OpenDaylight, **GBP** focused on **expressed
89 intent**, **refactoring of how renderers consume and publish Subject
90 Feature Definitions for multi-renderer support**.
92 GBP Base Architecture and Value Proposition
93 -------------------------------------------
98 In order to explain the fundamental value proposition of **GBP**, an
99 illustrated example is given. In order to do that some terminology must
102 The Access Model is the core of the **GBP** Intent System policy
105 .. figure:: ./images/groupbasedpolicy/GBPTerminology1.png
106 :alt: GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
108 GBP Access Model Terminology - Endpoints, EndpointGroups, Contract
110 .. figure:: ./images/groupbasedpolicy/GBPTerminology2.png
111 :alt: GBP Access Model Terminology - Subject, Classifier, Action
113 GBP Access Model Terminology - Subject, Classifier, Action
115 .. figure:: ./images/groupbasedpolicy/GBPTerminology3.png
116 :alt: GBP Forwarding Model Terminology - L3 Context, L2 Bridge 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 this release,
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 :ref:`UX <gbp-ux>`,
171 via the `REST API <#REST>`__ or directly from a domain-specific-language
172 such as :ref:`Neutron <gbp-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** for this release, there is one
188 renderer, the :ref:`OpenFlow Overlay renderer (OfOverlay). <gbp-of-overlay>`
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 :ref:`Neutron <gbp-neutron>` domain
289 specific mapping, and the :ref:`OpenFlow Overlay renderer <gbp-of-overlay>`
292 .. figure:: ./images/groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png
293 :alt: GBP High Level Architecture
295 GBP High Level 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 :ref:`Neutron Mapper <gbp-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 :ref:`UX <gbp-ux>` to use
304 :ref:`Service Function Chaining <gbp-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 Architecture - adding a renderer
313 GBP High Level 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 Architecture - adding a renderer
323 GBP High Level 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 this release
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 this release
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 :ref:`service function chain <gbp-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.
699 Using the GBP UX interface
700 --------------------------
705 These following components make up this application and are described in
706 more detail in following sections:
712 - Policy Expression view
716 The **GBP** UX is access via:
720 http://<odl controller>:8181/index.html
725 Basic view contains 5 navigation buttons which switch user to the
726 desired section of application:
728 - Governance – switch to the Governance view (middle of graphic has the
731 - Renderer configuration – switch to the Policy expression view with
732 Renderers section expanded
734 - Policy expression – switch to the Policy expression view with Policy
737 - Operational constraints – placeholder for development in next release
739 .. figure:: ./images/groupbasedpolicy/ui-1-basicview.png
747 Governance view consists from three columns.
749 .. figure:: ./images/groupbasedpolicy/ui-2-governanceview.png
750 :alt: Governance view
754 **Governance view – Basic view – Left column**
756 In the left column is Health section with Exception and Conflict buttons
757 with no functionality yet. This is a placeholder for development in
760 **Governance view – Basic view – Middle column**
762 In the top half of this section is select box with list of tenants for
763 select. Once the tenant is selected, all sub sections in application
764 operate and display data with actual selected tenant.
766 Below the select box are buttons which display Expressed or Delivered
767 policy of Governance section. In the bottom half of this section is
768 select box with list of renderers for select. There is currently only
769 :ref:`OfOverlay <gbp-of-overlay>` renderer available.
771 Below the select box is Renderer configuration button, which switch the
772 app into the Policy expression view with Renderers section expanded for
773 performing CRUD operations. Renderer state button display Renderer state
776 **Governance view – Basic view – Right column**
778 In the bottom part of the right section of Governance view is Home
779 button which switch the app to the Basic view.
781 In the top part is situated navigation menu with four main sections.
783 Policy expression button expand/collapse sub menu with three main parts
784 of Policy expression. By clicking on sub menu buttons, user will be
785 switched into the Policy expressions view with appropriate section
786 expanded for performing CRUD operations.
788 Renderer configuration button switches user into the Policy expressions
791 Governance button expand/collapse sub menu with four main parts of
792 Governance section. Sub menu buttons of Governance section display
793 appropriate section of Governance view.
795 Operational constraints have no functionality yet, and is a placeholder
796 for development in further releases.
798 Below the menu is place for view info section which displays info about
799 actual selected element from the topology (explained below).
801 **Governance view – Expressed policy**
803 In this view are displayed contracts with their consumed and provided
804 EndpointGroups of actual selected tenant, which can be changed in select
805 box in the upper left corner.
807 By single-clicking on any contract or EPG, the data of actual selected
808 element will be shown in the right column below the menu. A Manage
809 button launches a display wizard window for managing configuration of
810 items such as :ref:`Service Function Chaining <gbp-sfc>`.
812 .. figure:: ./images/groupbasedpolicy/ui-3-governanceview-expressed.png
813 :alt: Expressed policy
817 **Governance view – Delivered policy** In this view are displayed
818 subjects with their consumed and provided EndpointGroups of actual
819 selected tenant, which can be changed in select box in the upper left
822 By single-clicking on any subject or EPG, the data of actual selected
823 element will be shown in the right column below the menu.
825 By double-click on subject the subject detail view will be displayed
826 with subject’s rules of actual selected subject, which can be changed in
827 select box in the upper left corner.
829 By single-clicking on rule or subject, the data of actual selected
830 element will be shown in the right column below the menu.
832 By double-clicking on EPG in Delivered policy view, the EPG detail view
833 will be displayed with EPG’s endpoints of actual selected EPG, which can
834 be changed in select box in the upper left corner.
836 By single-clicking on EPG or endpoint the data of actual selected
837 element will be shown in the right column below the menu.
839 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-0.png
840 :alt: Delivered policy
844 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-1-subject.png
849 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-delivered-2-epg.png
854 **Governance view – Renderer state**
856 In this part are displayed Subject feature definition data with two main
857 parts: Action definition and Classifier definition.
859 By clicking on the down/right arrow in the circle is possible to
860 expand/hide data of appropriate container or list. Next to the list node
861 are displayed names of list’s elements where one is always selected and
862 element’s data are shown (blue line under the name).
864 By clicking on names of children nodes is possible to select desired
865 node and node’s data will be displayed.
867 .. figure:: ./images/groupbasedpolicy/ui-4-governanceview-renderer.png
872 Policy expression view
873 ~~~~~~~~~~~~~~~~~~~~~~
875 In the left part of this view is placed topology of actual selected
876 elements with the buttons for switching between types of topology at the
879 Right column of this view contains four parts. At the top of this column
880 are displayed breadcrumbs with actual position in the application.
882 Below the breadcrumbs is select box with list of tenants for select. In
883 the middle part is situated navigation menu, which allows switch to the
884 desired section for performing CRUD operations.
886 At the bottom is quick navigation menu with Access Model Wizard button
887 which display Wizard view, Home button which switch application to the
888 Basic view and occasionally Back button, which switch application to the
891 **Policy expression - Navigation menu**
893 To open Policy expression, select Policy expression from the GBP Home
896 In the top of navigation box you can select the tenant from the tenants
897 list to activate features addicted to selected tenant.
899 In the right menu, by default, the Policy menu section is expanded.
900 Subitems of this section are modules for CRUD (creating, reading,
901 updating and deleting) of tenants, EndpointGroups, contracts, L2/L3
904 - Section Renderers contains CRUD forms for Classifiers and Actions.
906 - Section Endpoints contains CRUD forms for Endpoint and L3 prefix
909 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-1.png
910 :alt: Navigation menu
914 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-2.png
915 :alt: CRUD operations
919 **Policy expression - Types of topology**
921 There are three different types of topology:
923 - Configured topology - EndpointGroups and contracts between them from
926 - Operational topology - displays same information but is based on
929 - L2/L3 - displays relationships between L3Contexts, L2 Bridge domains,
930 L2 Flood domains and Subnets.
932 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-3.png
937 .. figure:: ./images/groupbasedpolicy/ui-5-expresssion-4.png
938 :alt: Config Topology
942 **Policy expression - CRUD operations**
944 In this part are described basic flows for viewing, adding, editing and
945 deleting system elements like tenants, EndpointGroups etc.
950 To edit tenant objects click the Tenants button in the right menu. You
951 can see the CRUD form containing tenants list and control buttons.
953 To add new tenant, click the Add button This will display the form for
954 adding a new tenant. After filling tenant attributes Name and
955 Description click Save button. Saving of any object can be performed
956 only if all the object attributes are filled correctly. If some
957 attribute doesn’t have correct value, exclamation mark with mouse-over
958 tooltip will be displayed next to the label for the attribute. After
959 saving of tenant the form will be closed and the tenants list will be
960 set to default value.
962 To view an existing tenant, select the tenant from the select box
963 Tenants list. The view form is read-only and can be closed by clicking
964 cross mark in the top right of the form.
966 To edit selected tenant, click the Edit button, which will display the
967 edit form for selected tenant. After editing the Name and Description of
968 selected tenant click the Save button to save selected tenant. After
969 saving of tenant the edit form will be closed and the tenants list will
970 be set to default value.
972 To delete tenant select the tenant from the Tenants list and click
975 To return to the Policy expression click Back button on the bottom of
980 For managing EndpointGroups (EPG) the tenant from the top Tenants list
983 To add new EPG click Add button and after filling required attributes
984 click Save button. After adding the EPG you can edit it and assign
985 Consumer named selector or Provider named selector to it.
987 To edit EPG click the Edit button after selecting the EPG from Group
990 To add new Consumer named selector (CNS) click the Add button next to
991 the Consumer named selectors list. While CNS editing you can set one or
992 more contracts for current CNS pressing the Plus button and selecting
993 the contract from the Contracts list. To remove the contract, click on
994 the cross mark next to the contract. Added CNS can be viewed, edited or
995 deleted by selecting from the Consumer named selectors list and clicking
996 the Edit and Delete buttons like with the EPG or tenants.
998 To add new Provider named selector (PNS) click the Add button next to
999 the Provider named selectors list. While PNS editing you can set one or
1000 more contracts for current PNS pressing the Plus button and selecting
1001 the contract from the Contracts list. To remove the contract, click on
1002 the cross mark next to the contract. Added PNS can be viewed, edited or
1003 deleted by selecting from the Provider named selectors list and clicking
1004 the Edit and Delete buttons like with the EPG or tenants.
1006 To delete EPG, CNS or PNS select it in selectbox and click the Delete
1007 button next to the selectbox.
1011 For managing contracts the tenant from the top Tenants list must be
1014 To add new Contract click Add button and after filling required fields
1017 After adding the Contract user can edit it by selecting in the Contracts
1018 list and clicking Edit button.
1020 To add new Clause click Add button next to the Clause list while editing
1021 the contract. While editing the Clause after selecting clause from the
1022 Clause list user can assign clause subjects by clicking the Plus button
1023 next to the Clause subjects label. Adding and editing action must be
1024 submitted by pressing Save button. To manage Subjects you can use CRUD
1025 form like with the Clause list.
1029 For managing L2/L3 the tenant from the top Tenants list must be
1032 To add L3 Context click the Add button next to the L3 Context list
1033 ,which will display the form for adding a new L3 Context. After filling
1034 L3 Context attributes click Save button. After saving of L3 Context,
1035 form will be closed and the L3 Context list will be set to default
1038 To view an existing L3 Context, select the L3 Context from the select
1039 box L3 Context list. The view form is read-only and can be closed by
1040 clicking cross mark in the top right of the form.
1042 If user wants to edit selected L3 Context, click the Edit button, which
1043 will display the edit form for selected L3 Context. After editing click
1044 the Save button to save selected L3 Context. After saving of L3 Context,
1045 the edit form will be closed and the L3 Context list will be set to
1048 To delete L3 Context, select it from the L3 Context list and click
1051 To add L2 Bridge Domain, click the Add button next to the L2 Bridge
1052 Domain list. This will display the form for adding a new L2 Bridge
1053 Domain. After filling L2 Bridge Domain attributes click Save button.
1054 After saving of L2 Bridge Domain, form will be closed and the L2 Bridge
1055 Domain list will be set to default value.
1057 To view an existing L2 Bridge Domain, select the L2 Bridge Domain from
1058 the select box L2 Bridge Domain list. The view form is read-only and can
1059 be closed by clicking cross mark in the top right of the form.
1061 If user wants to edit selected L2 Bridge Domain, click the Edit button,
1062 which will display the edit form for selected L2 Bridge Domain. After
1063 editing click the Save button to save selected L2 Bridge Domain. After
1064 saving of L2 Bridge Domain the edit form will be closed and the L2
1065 Bridge Domain list will be set to default value.
1067 To delete L2 Bridge Domain select it from the L2 Bridge Domain list and
1068 click Delete button.
1070 To add L3 Flood Domain, click the Add button next to the L3 Flood Domain
1071 list. This will display the form for adding a new L3 Flood Domain. After
1072 filling L3 Flood Domain attributes click Save button. After saving of L3
1073 Flood Domain, form will be closed and the L3 Flood Domain list will be
1074 set to default value.
1076 To view an existing L3 Flood Domain, select the L3 Flood Domain from the
1077 select box L3 Flood Domain list. The view form is read-only and can be
1078 closed by clicking cross mark in the top right of the form.
1080 If user wants to edit selected L3 Flood Domain, click the Edit button,
1081 which will display the edit form for selected L3 Flood Domain. After
1082 editing click the Save button to save selected L3 Flood Domain. After
1083 saving of L3 Flood Domain the edit form will be closed and the L3 Flood
1084 Domain list will be set to default value.
1086 To delete L3 Flood Domain select it from the L3 Flood Domain list and
1087 click Delete button.
1089 To add Subnet click the Add button next to the Subnet list. This will
1090 display the form for adding a new Subnet. After filling Subnet
1091 attributes click Save button. After saving of Subnet, form will be
1092 closed and the Subnet list will be set to default value.
1094 To view an existing Subnet, select the Subnet from the select box Subnet
1095 list. The view form is read-only and can be closed by clicking cross
1096 mark in the top right of the form.
1098 If user wants to edit selected Subnet, click the Edit button, which will
1099 display the edit form for selected Subnet. After editing click the Save
1100 button to save selected Subnet. After saving of Subnet the edit form
1101 will be closed and the Subnet list will be set to default value.
1103 To delete Subnet select it from the Subnet list and click Delete button.
1107 To add Classifier, click the Add button next to the Classifier list.
1108 This will display the form for adding a new Classifier. After filling
1109 Classifier attributes click Save button. After saving of Classifier,
1110 form will be closed and the Classifier list will be set to default
1113 To view an existing Classifier, select the Classifier from the select
1114 box Classifier list. The view form is read-only and can be closed by
1115 clicking cross mark in the top right of the form.
1117 If you want to edit selected Classifier, click the Edit button, which
1118 will display the edit form for selected Classifier. After editing click
1119 the Save button to save selected Classifier. After saving of Classifier
1120 the edit form will be closed and the Classifier list will be set to
1123 To delete Classifier select it from the Classifier list and click Delete
1128 To add Action, click the Add button next to the Action list. This will
1129 display the form for adding a new Action. After filling Action
1130 attributes click Save button. After saving of Action, form will be
1131 closed and the Action list will be set to default value.
1133 To view an existing Action, select the Action from the select box Action
1134 list. The view form is read-only and can be closed by clicking cross
1135 mark in the top right of the form.
1137 If user wants to edit selected Action, click the Edit button, which will
1138 display the edit form for selected Action. After editing click the Save
1139 button to save selected Action. After saving of Action the edit form
1140 will be closed and the Action list will be set to default value.
1142 To delete Action select it from the Action list and click Delete button.
1146 To add Endpoint, click the Add button next to the Endpoint list. This
1147 will display the form for adding a new Endpoint. To add EndpointGroup
1148 assignment click the Plus button next to the label EndpointGroups. To
1149 add Condition click Plus button next to the label Condition. To add L3
1150 Address click the Plus button next to the L3 Addresses label. After
1151 filling Endpoint attributes click Save button. After saving of Endpoint,
1152 form will be closed and the Endpoint list will be set to default value.
1154 To view an existing Endpoint just, the Endpoint from the select box
1155 Endpoint list. The view form is read-only and can be closed by clicking
1156 cross mark in the top right of the form.
1158 If you want to edit selected Endpoint, click the Edit button, which will
1159 display the edit form for selected Endpoint. After editing click the
1160 Save button to save selected Endpoint. After saving of Endpoint the edit
1161 form will be closed and the Endpoint list will be set to default value.
1163 To delete Endpoint select it from the Endpoint list and click Delete
1166 **L3 prefix endpoint**
1168 To add L3 prefix endpoint, click the Add button next to the L3 prefix
1169 endpoint list. This will display the form for adding a new Endpoint. To
1170 add EndpointGroup assignment, click the Plus button next to the label
1171 EndpointGroups. To add Condition, click Plus button next to the label
1172 Condition. To add L2 gateway click the Plus button next to the L2
1173 gateways label. To add L3 gateway, click the Plus button next to the L3
1174 gateways label. After filling L3 prefix endpoint attributes click Save
1175 button. After saving of L3 prefix endpoint, form will be closed and the
1176 Endpoint list will be set to default value.
1178 To view an existing L3 prefix endpoint, select the Endpoint from the
1179 select box L3 prefix endpoint list. The view form is read-only and can
1180 be closed by clicking cross mark in the top right of the form.
1182 If you want to edit selected L3 prefix endpoint, click the Edit button,
1183 which will display the edit form for selected L3 prefix endpoint. After
1184 editing click the Save button to save selected L3 prefix endpoint. After
1185 saving of Endpoint the edit form will be closed and the Endpoint list
1186 will be set to default value.
1188 To delete Endpoint select it from the L3 prefix endpoint list and click
1194 Wizard provides quick method to send basic data to controller necessary
1195 for basic usage of GBP application. It is useful in the case that there
1196 aren’t any data in controller. In the first tab is form for create
1197 tenant. The second tab is for CRUD operations with contracts and their
1198 sub elements such as subjects, rules, clauses, action refs and
1199 classifier refs. The last tab is for CRUD operations with EndpointGroups
1200 and their CNS and PNS. Created structure of data is possible to send by
1201 clicking on Submit button.
1203 .. figure:: ./images/groupbasedpolicy/ui-6-wizard.png
1213 - :ref:`gbp-of-overlay`
1215 - `Policy Resolution`_
1217 - `Forwarding Model <#forwarding>`__
1219 - `the **GBP** demo and development environments for tips <#demo>`__
1221 It is recommended to use either:
1223 - `Neutron mapper <gbp-neutron>`
1225 - :ref:`the UX <gbp-ux>`
1227 If the REST API must be used, and the above resources are not
1230 - feature:install odl-dluxapps-yangui
1233 ``http://<odl-controller>:8181/index.html``
1234 and select YangUI from the left menu.
1236 to explore the various **GBP** REST options
1240 Using OpenStack with GBP
1241 ------------------------
1246 This section is for Application Developers and Network Administrators
1247 who are looking to integrate Group Based Policy with OpenStack.
1249 To enable the **GBP** Neutron Mapper feature, at the Karaf console:
1253 feature:install odl-groupbasedpolicy-neutronmapper
1255 Neutron Mapper has the following dependencies that are automatically
1262 Neutron Northbound implementing REST API used by OpenStack
1266 odl-groupbasedpolicy-base
1268 Base **GBP** feature set, such as policy resolution, data model etc.
1272 odl-groupbasedpolicy-ofoverlay
1274 REST calls from OpenStack Neutron are by the Neutron NorthBound project.
1276 **GBP** provides the implementation of the `Neutron V2.0
1277 API <http://developer.openstack.org/api-ref-networking-v2.html>`_.
1282 List of supported Neutron entities:
1290 - External provider L2/L3 network
1298 - Distributed functionality with local routing per compute
1300 - External gateway access per compute node (dedicated port required)
1302 - Multiple routers per tenant
1308 The mapping of Neutron entities to **GBP** entities is as follows:
1312 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
1317 The Neutron port is mapped to an endpoint.
1319 The current implementation supports one IP address per Neutron port.
1321 An endpoint and L3-endpoint belong to multiple EndpointGroups if the
1322 Neutron port is in multiple Neutron Security Groups.
1324 The key for endpoint is L2-bridge-domain obtained as the parent of
1325 L2-flood-domain representing Neutron network. The MAC address is from
1326 the Neutron port. An L3-endpoint is created based on L3-context (the
1327 parent of the L2-bridge-domain) and IP address of Neutron Port.
1331 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
1332 :alt: Neutron Network
1336 A Neutron network has the following characteristics:
1338 - defines a broadcast domain
1340 - defines a L2 transmission domain
1342 - defines a L2 name space.
1344 To represent this, a Neutron Network is mapped to multiple **GBP**
1345 entities. The first mapping is to an L2 flood-domain to reflect that the
1346 Neutron network is one flooding or broadcast domain. An L2-bridge-domain
1347 is then associated as the parent of L2 flood-domain. This reflects both
1348 the L2 transmission domain as well as the L2 addressing namespace.
1350 The third mapping is to L3-context, which represents the distinct L3
1351 address space. The L3-context is the parent of L2-bridge-domain.
1355 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
1356 :alt: Neutron Subnet
1360 Neutron subnet is associated with a Neutron network. The Neutron subnet
1361 is mapped to a **GBP** subnet where the parent of the subnet is
1362 L2-flood-domain representing the Neutron network.
1364 **Neutron Security Group**
1366 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
1367 :alt: Neutron Security Group and Rules
1369 Neutron Security Group and Rules
1371 **GBP** entity representing Neutron security-group is EndpointGroup.
1373 **Infrastructure EndpointGroups**
1375 Neutron-mapper automatically creates EndpointGroups to manage key
1376 infrastructure items such as:
1378 - DHCP EndpointGroup - contains endpoints representing Neutron DHCP
1381 - Router EndpointGroup - contains endpoints representing Neutron router
1384 - External EndpointGroup - holds L3-endpoints representing Neutron
1385 router gateway ports, also associated with FloatingIP ports.
1387 **Neutron Security Group Rules**
1389 This is the most involved amongst all the mappings because Neutron
1390 security-group-rules are mapped to contracts with clauses, subjects,
1391 rules, action-refs, classifier-refs, etc. Contracts are used between
1392 EndpointGroups representing Neutron Security Groups. For simplification
1393 it is important to note that Neutron security-group-rules are similar to
1394 a **GBP** rule containing:
1396 - classifier with direction
1398 - action of **allow**.
1402 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
1403 :alt: Neutron Router
1407 Neutron router is represented as a L3-context. This treats a router as a
1408 Layer3 namespace, and hence every network attached to it a part of that
1411 This allows for multiple routers per tenant with complete isolation.
1413 The mapping of the router to an endpoint represents the router’s
1414 interface or gateway port.
1416 The mapping to an EndpointGroup represents the internal infrastructure
1417 EndpointGroups created by the **GBP** Neutron Mapper
1419 When a Neutron router interface is attached to a network/subnet, that
1420 network/subnet and its associated endpoints or Neutron Ports are
1421 seamlessly added to the namespace.
1423 **Neutron FloatingIP**
1425 When associated with a Neutron Port, this leverages the
1426 :ref:`OfOverlay <gbp-of-overlay>` renderer’s NAT capabilities.
1428 A dedicated *external* interface on each Nova compute host allows for
1429 disitributed external access. Each Nova instance associated with a
1430 FloatingIP address can access the external network directly without
1431 having to route via the Neutron controller, or having to enable any form
1432 of Neutron distributed routing functionality.
1434 Assuming the gateway provisioned in the Neutron Subnet command for the
1435 external network is reachable, the combination of **GBP** Neutron Mapper
1436 and :ref:`OfOverlay renderer <gbp-of-overlay>` will automatically ARP for this
1437 default gateway, requiring no user intervention.
1439 **Troubleshooting within GBP**
1441 Logging level for the mapping functionality can be set for package
1442 org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling
1443 TRACE logging level on Karaf console:
1447 log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
1449 **Neutron mapping example**
1451 As an example for mapping can be used creation of Neutron network,
1452 subnet and port. When a Neutron network is created 3 **GBP** entities
1453 are created: l2-flood-domain, l2-bridge-domain, l3-context.
1455 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
1456 :alt: Neutron network mapping
1458 Neutron network mapping
1460 After an subnet is created in the network mapping looks like this.
1462 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
1463 :alt: Neutron subnet mapping
1465 Neutron subnet mapping
1467 If an Neutron port is created in the subnet an endpoint and l3-endpoint
1468 are created. The endpoint has key composed from l2-bridge-domain and MAC
1469 address from Neutron port. A key of l3-endpoint is compesed from
1470 l3-context and IP address. The network containment of endpoint and
1471 l3-endpoint points to the subnet.
1473 .. figure:: ./images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
1474 :alt: Neutron port mapping
1476 Neutron port mapping
1478 Configuring GBP Neutron
1479 ~~~~~~~~~~~~~~~~~~~~~~~
1481 No intervention passed initial OpenStack setup is required by the user.
1483 More information about configuration can be found in our DevStack demo
1484 environment on the `GBP
1485 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`_.
1487 Administering or Managing GBP Neutron
1488 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1490 For consistencies sake, all provisioning should be performed via the
1491 Neutron API. (CLI or Horizon).
1493 The mapped policies can be augmented via the **GBP** :ref:`UX <gbp-ux>`, to:
1495 - Enable :ref:`Service Function Chaining <gbp-sfc>`
1497 - Add endpoints from outside of Neutron i.e. VMs/containers not
1498 provisioned in OpenStack
1500 - Augment policies/contracts derived from Security Group Rules
1502 - Overlay additional contracts or groupings
1507 A DevStack demo environment can be found on the `GBP
1508 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`_.
1510 GBP Renderer manager
1511 --------------------
1516 The GBP Renderer manager is an integral part of **GBP** base module.
1517 It dispatches information about endpoints'
1518 policy configuration to specific device renderer
1519 by writing a renderer policy configuration into the
1520 registered renderer's policy store.
1522 Installing and Pre-requisites
1523 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1525 Renderer manager is integrated into GBP base module,
1526 so no additional installation is required.
1531 Renderer manager gets data notifications about:
1533 - Endoints (base-endpoint.yang)
1535 - EndpointLocations (base-endpoint.yang)
1537 - ResolvedPolicies (resolved-policy.yang)
1539 - Forwarding (forwarding.yang)
1541 Based on data from notifications it creates a configuration task for
1542 specific renderers by writing a renderer policy configuration into the
1543 registered renderer's policy store.
1544 Configuration is stored to CONF data store as Renderers (renderer.yang).
1546 Configuration is signed with version number which is incremented by every change.
1547 All renderers are supposed to be on the same version. Renderer manager waits
1548 for all renderers to respond with version update in OPER data store.
1549 After a version of every renderer in OPER data store has the same value
1550 as the one in CONF data store,
1551 renderer manager moves to the next configuration with incremented version.
1553 GBP Location manager
1554 --------------------
1559 Location manager monitors information about Endpoint Location providers
1560 (see endpoint-location-provider.yang) and manages Endpoint locations in OPER data store accordingly.
1562 Installing and Pre-requisites
1563 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1565 Location manager is integrated into GBP base module,
1566 so no additional installation is required.
1571 The endpoint-locations container in OPER data store (see base-endpoint.yang)
1572 contains two lists for two types of EP location,
1573 namely address-endpoint-location and containment-endpoint-location.
1574 LocationResolver is a class that processes Location providers in CONF data store
1575 and puts location information to OPER data store.
1577 When a new Location provider is created in CONF data store, its Address EP locations
1578 are being processed first, and their info is stored locally in accordance with processed
1579 Location provider's priority. Then a location of type "absolute" with the highest priority
1580 is selected for an EP, and is put in OPER data store. If Address EP locations contain
1581 locations of type "relative", those are put to OPER data store.
1583 If current Location provider contains Containment EP locations of type "relative",
1584 then those are put to OPER data store.
1586 Similarly, when a Location provider is deleted, information of its locations
1587 is removed from the OPER data store.
1591 Using the GBP OpenFlow Overlay (OfOverlay) renderer
1592 ---------------------------------------------------
1597 The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
1598 renderer, which creates a network virtualization solution across nodes
1599 that host Open vSwitch software switches.
1601 Installing and Pre-requisites
1602 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1604 From the Karaf console in OpenDaylight:
1608 feature:install odl-groupbasedpolicy-ofoverlay
1610 This renderer is designed to work with OpenVSwitch (OVS) 2.1+ (although
1611 2.3 is strongly recommended) and OpenFlow 1.3.
1613 When used in conjunction with the :ref:`Neutron Mapper feature <gbp-neutron>`
1614 no extra OfOverlay specific setup is required.
1616 When this feature is loaded "standalone", the user is required to
1617 configure infrastructure, such as
1619 - instantiating OVS bridges,
1621 - attaching hosts to the bridges,
1623 - and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
1627 The **GBP** OfOverlay renderer also supports a table offset option, to
1628 offset the pipeline post-table 0. The value of table offset is stored in
1629 the config datastore and it may be rewritten at runtime.
1633 PUT http://{{controllerIp}}:8181/restconf/config/ofoverlay:of-overlay-config
1635 "of-overlay-config": {
1636 "gbp-ofoverlay-table-offset": 6
1640 The default value is set by changing:
1641 <gbp-ofoverlay-table-offset>0</gbp-ofoverlay-table-offset>
1644 distribution-karaf/target/assembly/etc/opendaylight/karaf/15-groupbasedpolicy-ofoverlay.xml
1646 To avoid overwriting runtime changes, the default value is used only
1647 when the OfOverlay renderer starts and no other value has been written
1650 OpenFlow Overlay Architecture
1651 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1653 These are the primary components of **GBP**. The OfOverlay components
1654 are highlighted in red.
1656 .. figure:: ./images/groupbasedpolicy/ofoverlay-1-components.png
1657 :alt: OfOverlay within **GBP**
1659 OfOverlay within **GBP**
1661 In terms of the inner components of the **GBP** OfOverlay renderer:
1663 .. figure:: ./images/groupbasedpolicy/ofoverlay-2-components.png
1664 :alt: OfOverlay expanded view:
1666 OfOverlay expanded view:
1668 **OfOverlay Renderer**
1670 Launches components below:
1674 Policy resolution is completely domain independent, and the OfOverlay
1675 leverages process policy information internally. See `Policy Resolution
1676 process <Policy Resolution>`_.
1678 It listens to inputs to the *Tenants* configuration datastore, validates
1679 tenant input, then writes this to the Tenants operational datastore.
1681 From there an internal notification is generated to the PolicyManager.
1683 In the next release, this will be moving to a non-renderer specific
1686 **Endpoint Manager**
1688 The endpoint repository operates in **orchestrated** mode. This means
1689 the user is responsible for the provisioning of endpoints via:
1691 - :ref:`UX/GUI <gbp-ux>`
1697 When using the :ref:`Neutron mapper <gbp-neutron>` feature, everything is
1698 managed transparently via Neutron.
1700 The Endpoint Manager is responsible for listening to Endpoint repository
1701 updates and notifying the Switch Manager when a valid Endpoint has been
1704 It also supplies utility functions to the flow pipeline process.
1708 The Switch Manager is purely a state manager.
1710 Switches are in one of 3 states:
1718 **Ready** is denoted by a connected switch:
1720 - having a tunnel interface
1722 - having at least one endpoint connected.
1724 In this way **GBP** is not writing to switches it has no business to.
1726 **Preparing** simply means the switch has a controller connection but is
1727 missing one of the above *complete and necessary* conditions
1729 **Disconnected** means a previously connected switch is no longer
1730 present in the Inventory operational datastore.
1732 .. figure:: ./images/groupbasedpolicy/ofoverlay-3-flowpipeline.png
1733 :alt: OfOverlay Flow Pipeline
1735 OfOverlay Flow Pipeline
1737 The OfOverlay leverages Nicira registers as follows:
1739 - REG0 = Source EndpointGroup + Tenant ordinal
1741 - REG1 = Source Conditions + Tenant ordinal
1743 - REG2 = Destination EndpointGroup + Tenant ordinal
1745 - REG3 = Destination Conditions + Tenant ordinal
1747 - REG4 = Bridge Domain + Tenant ordinal
1749 - REG5 = Flood Domain + Tenant ordinal
1751 - REG6 = Layer 3 Context + Tenant ordinal
1755 Table 0 of the OpenFlow pipeline. Responsible for ensuring that only
1756 valid connections can send packets into the pipeline:
1760 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1761 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1762 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
1763 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
1764 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
1765 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1766 cookie=0x0, <snip> , priority=111, ip actions=drop
1767 cookie=0x0, <snip> , priority=110,arp actions=drop
1768 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1769 cookie=0x0, <snip> , priority=1 actions=drop
1771 Ingress from tunnel interface, go to Table *Source Mapper*:
1775 cookie=0x0, <snip> , priority=200,in_port=3 actions=goto_table:2
1777 Ingress from outside, goto Table *Ingress NAT Mapper*:
1781 cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
1783 ARP from Endpoint, go to Table *Source Mapper*:
1787 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
1789 IPv4 from Endpoint, go to Table *Source Mapper*:
1793 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
1795 DHCP DORA from Endpoint, go to Table *Source Mapper*:
1799 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
1801 Series of DROP tables with priority set to capture any non-specific
1802 traffic that should have matched above:
1806 cookie=0x0, <snip> , priority=112,ipv6 actions=drop
1807 cookie=0x0, <snip> , priority=111, ip actions=drop
1808 cookie=0x0, <snip> , priority=110,arp actions=drop
1810 "L2" catch all traffic not identified above:
1814 cookie=0x0, <snip> ,in_port=5,dl_src=fa:16:3e:d5:b9:8d actions=goto_table:2
1820 cookie=0x0, <snip> , priority=1 actions=drop
1822 **Ingress NAT Mapper**
1824 Table :ref:`offset <gbp-offset>` +1.
1826 ARP responder for external NAT address:
1830 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
1832 Translate from Outside to Inside and perform same functions as
1837 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
1841 Table :ref:`offset <gbp-offset>` +2.
1843 Determines based on characteristics from the ingress port, which:
1845 - EndpointGroup(s) it belongs to
1847 - Forwarding context
1849 - Tunnel VNID ordinal
1851 Establishes tunnels at valid destination switches for ingress.
1853 Ingress Tunnel established at remote node with VNID Ordinal that maps to
1854 Source EPG, Forwarding Context etc:
1858 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
1860 Maps endpoint to Source EPG, Forwarding Context based on ingress port,
1865 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
1871 cookie=0x0, duration=197.622s, table=2, n_packets=0, n_bytes=0, priority=1 actions=drop
1873 **Destination Mapper**
1875 Table :ref:`offset <gbp-offset>` +3.
1877 Determines based on characteristics of the endpoint:
1879 - EndpointGroup(s) it belongs to
1881 - Forwarding context
1883 - Tunnel Destination value
1885 Manages routing based on valid ingress nodes ARP’ing for their default
1886 gateway, and matches on either gateway MAC or destination endpoint MAC.
1888 ARP for default gateway for the 10.1.1.0/24 subnet:
1892 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
1894 Broadcast traffic destined for GroupTable:
1898 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
1900 Layer3 destination matching flows, where priority=100+masklength. Since
1901 **GBP** now support L3Prefix endpoint, we can set default routes etc:
1905 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
1907 Layer2 destination matching flows, designed to be caught only after last
1908 IP flow (lowest priority IP flow is 100):
1912 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
1914 General drop flow: cookie=0x0, duration=323.207s, table=3, n\_packets=6,
1915 n\_bytes=588, priority=1 actions=drop
1919 Table :ref:`offset <gbp-offset>` +4.
1921 Once the Source and Destination EndpointGroups are assigned, policy is
1922 enforced based on resolved rules.
1924 In the case of :ref:`Service Function Chaining <gbp-sfc>`, the encapsulation
1925 and destination for traffic destined to a chain, is discovered and
1928 Policy flow, allowing IP traffic between EndpointGroups:
1932 cookie=0x0, <snip> , priority=64998,ip,reg0=0x8,reg1=0x1,reg2=0xc,reg3=0x1 actions=goto_table:5
1934 **Egress NAT Mapper**
1936 Table :ref:`offset <gbp-offset>` +5.
1938 Performs NAT function before Egressing OVS instance to the underlay
1941 Inside to Outside NAT translation before sending to underlay:
1945 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
1949 Table :ref:`offset <gbp-offset>` +6.
1951 Manages post-policy enforcement for endpoint specific destination
1952 effects. Specifically for :ref:`Service Function Chaining <gbp-sfc>`, which is
1953 why we can support both symmetric and asymmetric chains and distributed
1954 ingress/egress classification.
1960 cookie=0x0, <snip>, priority=100 actions=output:NXM_NX_REG7[]
1962 Configuring OpenFlow Overlay via REST
1963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1967 Please see the :ref:`UX <gbp-ux>` section on how to configure **GBP** via
1974 POST http://{{controllerIp}}:8181/restconf/operations/endpoint:register-endpoint
1977 "endpoint-group": "<epg0>",
1978 "endpoint-groups" : ["<epg1>","<epg2>"],
1979 "network-containment" : "<fowarding-model-context1>",
1980 "l2-context": "<bridge-domain1>",
1981 "mac-address": "<mac1>",
1984 "ip-address": "<ipaddress1>",
1985 "l3-context": "<l3_context1>"
1988 "*ofoverlay:port-name*": "<ovs port name>",
1989 "tenant": "<tenant1>"
1995 The usage of "port-name" preceded by "ofoverlay". In OpenDaylight,
1996 base datastore objects can be *augmented*. In **GBP**, the base
1997 endpoint model has no renderer specifics, hence can be leveraged
1998 across multiple renderers.
2000 **OVS Augmentations to Inventory**
2004 PUT http://{{controllerIp}}:8181/restconf/config/opendaylight-inventory:nodes/
2006 "opendaylight-inventory:nodes": {
2009 "id": "openflow:123456",
2010 "ofoverlay:tunnel": [
2012 "tunnel-type": "overlay:tunnel-type-vxlan",
2013 "ip": "<ip_address_of_ovs>",
2015 "node-connector-id": "openflow:123456:1"
2020 "id": "openflow:654321",
2021 "ofoverlay:tunnel": [
2023 "tunnel-type": "overlay:tunnel-type-vxlan",
2024 "ip": "<ip_address_of_ovs>",
2026 "node-connector-id": "openflow:654321:1"
2034 **Tenants** see `Policy Resolution`_ and
2035 `Forwarding Model <#forwarding>`__ for details:
2045 "name": "allow-http-clause",
2047 "allow-http-subject",
2048 "allow-icmp-subject"
2055 "name": "allow-http-subject",
2074 "name": "allow-http-rule"
2079 "name": "allow-icmp-subject",
2093 "name": "allow-icmp-rule"
2102 "consumer-named-selector": [
2111 "provider-named-selector": []
2114 "consumer-named-selector": [],
2116 "provider-named-selector": [
2127 "l2-bridge-domain": [
2133 "l2-flood-domain": [
2149 "subject-feature-instances": {
2150 "classifier-instance": [
2152 "classifier-definition-id": "<id>",
2153 "name": "http-dest",
2154 "parameter-value": [
2166 "classifier-definition-id": "<id>",
2168 "parameter-value": [
2175 "name": "sourceport"
2180 "classifier-definition-id": "<id>",
2182 "parameter-value": [
2190 "action-instance": [
2193 "action-definition-id": "<id>"
2200 "ip-prefix": "<ip_prefix>",
2202 "virtual-router-ip": "<ip address>"
2206 "ip-prefix": "<ip prefix>",
2208 "virtual-router-ip": "<ip address>"
2217 Comprehensive tutorials, along with a demonstration environment
2218 leveraging Vagrant can be found on the `GBP
2219 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)>`__
2221 Using the GBP eBPF IO Visor Agent renderer
2222 ------------------------------------------
2227 The IO Visor renderer feature enables container endpoints (e.g. Docker,
2228 LXC) to leverage GBP policies.
2230 The renderer interacts with a IO Visor module from the Linux Foundation
2233 Installing and Pre-requisites
2234 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2236 From the Karaf console in OpenDaylight:
2240 feature:install odl-groupbasedpolicy-iovisor odl-restconf
2242 Installation details, usage, and other information for the IO Visor GBP
2243 module can be found here: `IO Visor github repo for IO
2244 Modules <https://github.com/iovisor/iomodules>`_
2246 Using the GBP FaaS renderer
2247 ---------------------------
2252 The FaaS renderer feature enables leveraging the FaaS project as a GBP
2255 Installing and Pre-requisites
2256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2258 From the Karaf console in OpenDaylight:
2262 feature:install odl-groupbasedpolicy-faas
2264 More information about FaaS can be found here:
2265 https://wiki.opendaylight.org/view/FaaS:GBPIntegration
2269 Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay
2270 ---------------------------------------------------------------------------
2275 Please refer to the Service Function Chaining project for specifics on
2276 SFC provisioning and theory.
2278 **GBP** allows for the use of a chain, by name, in policy.
2280 This takes the form of an *action* in **GBP**.
2282 Using the `GBP demo and development environment <#demo>`__ as an
2285 .. figure:: ./images/groupbasedpolicy/sfc-1-topology.png
2286 :alt: GBP and SFC integration environment
2288 GBP and SFC integration environment
2290 In the topology above, a symmetrical chain between H35\_2 and H36\_3
2293 H35\_2 to sw1 to sff1 to sf1 to sff1 to sff2 to sf2 to sff2 to sw6 to
2296 If symmetric chaining was desired, the return path is:
2298 .. figure:: ./images/groupbasedpolicy/sfc-2-symmetric.png
2299 :alt: GBP and SFC symmetric chain environment
2301 GBP and SFC symmetric chain environment
2303 If asymmetric chaining was desired, the return path could be direct, or
2304 an **entirely different chain**.
2306 .. figure:: ./images/groupbasedpolicy/sfc-3-asymmetric.png
2307 :alt: GBP and SFC assymmetric chain environment
2309 GBP and SFC assymmetric chain environment
2311 All these scenarios are supported by the integration.
2313 In the **Subject Feature Instance** section of the tenant config, we
2314 define the instances of the classifier definitions for ICMP and HTTP:
2318 "subject-feature-instances": {
2319 "classifier-instance": [
2322 "parameter-value": [
2330 "name": "http-dest",
2331 "parameter-value": [
2344 "parameter-value": [
2351 "name": "sourceport"
2357 Then the action instances to associate to traffic that matches
2358 classifiers are defined.
2360 Note the *SFC chain name* must exist in SFC, and is validated against
2361 the datastore once the tenant configuration is entered, before entering
2362 a valid tenant configuration into the operational datastore (which
2363 triggers policy resolution).
2367 "action-instance": [
2370 "parameter-value": [
2372 "name": "sfc-chain-name",
2373 "string-value": "SFCGBP"
2383 When ICMP is matched, allow the traffic:
2391 "name": "icmp-subject",
2394 "name": "allow-icmp-rule",
2412 When HTTP is matched, **in** to the provider of the contract with a TCP
2413 destination port of 80 (HTTP) or the HTTP request. The chain action is
2414 triggered, and similarly **out** from the provider for traffic with TCP
2415 source port of 80 (HTTP), or the HTTP response.
2420 "name": "http-subject",
2423 "name": "http-chain-rule-in",
2426 "name": "http-dest",
2438 "name": "http-chain-rule-out",
2455 To enable asymmetrical chaining, for instance, the user desires that
2456 HTTP requests traverse the chain, but the HTTP response does not, the
2457 HTTP response is set to *allow* instead of chain:
2462 "name": "http-chain-rule-out",
2477 Demo/Development environment
2478 ----------------------------
2480 The **GBP** project for this release has two demo/development environments.
2482 - Docker based GBP and GBP+SFC integration Vagrant environment
2484 - DevStack based GBP+Neutron integration Vagrant environment
2487 wiki <https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Consumability/Demo>`_