1 OpenStack with GroupBasedPolicy
2 ===============================
4 This section is for Application Developers and Network Administrators
5 who are looking to integrate Group Based Policy with OpenStack.
7 To enable the **GBP** Neutron Mapper feature, at the karaf console:
11 feature:install odl-groupbasedpolicy-neutronmapper
13 Neutron Mapper has the following dependencies that are automatically loaded:
19 Neutron Northbound implementing REST API used by OpenStack
23 odl-groupbasedpolicy-base
25 Base **GBP** feature set, such as policy resolution, data model etc.
29 odl-groupbasedpolicy-ofoverlay
31 For this release, **GBP** has one renderer, hence this is loaded by default.
33 REST calls from OpenStack Neutron are by the Neutron NorthBound project.
35 **GBP** provides the implementation of the `Neutron V2.0 API <neutron_v2api_>`_.
40 List of supported Neutron entities:
46 * External provider L2/L3 network
52 * Distributed functionality with local routing per compute
53 * External gateway access per compute node (dedicated port required)
54 * Multiple routers per tenant
59 The mapping of Neutron entities to **GBP** entities is as follows:
63 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
67 The Neutron port is mapped to an endpoint.
69 The current implementation supports one IP address per Neutron port.
71 An endpoint and L3-endpoint belong to multiple EndpointGroups if the Neutron
72 port is in multiple Neutron Security Groups.
74 The key for endpoint is L2-bridge-domain obtained as the parent of
75 L2-flood-domain representing Neutron network. The MAC address is from the
77 An L3-endpoint is created based on L3-context (the parent of the
78 L2-bridge-domain) and IP address of Neutron Port.
82 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
86 A Neutron network has the following characteristics:
88 * defines a broadcast domain
89 * defines a L2 transmission domain
90 * defines a L2 name space.
92 To represent this, a Neutron Network is mapped to multiple **GBP** entities.
93 The first mapping is to an L2 flood-domain to reflect that the Neutron network
94 is one flooding or broadcast domain.
95 An L2-bridge-domain is then associated as the parent of L2 flood-domain. This
96 reflects both the L2 transmission domain as well as the L2 addressing namespace.
98 The third mapping is to L3-context, which represents the distinct L3 address space.
99 The L3-context is the parent of L2-bridge-domain.
104 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
108 Neutron subnet is associated with a Neutron network. The Neutron subnet is
109 mapped to a *GBP* subnet where the parent of the subnet is L2-flood-domain
110 representing the Neutron network.
112 **Neutron Security Group**
115 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
117 Neutron Security Group and Rules
119 **GBP** entity representing Neutron security-group is EndpointGroup.
121 **Infrastructure EndpointGroups**
123 Neutron-mapper automatically creates EndpointGroups to manage key infrastructure
126 * DHCP EndpointGroup - contains endpoints representing Neutron DHCP ports
127 * Router EndpointGroup - contains endpoints representing Neutron router
129 * External EndpointGroup - holds L3-endpoints representing Neutron router
130 gateway ports, also associated with FloatingIP ports.
132 **Neutron Security Group Rules**
134 This mapping is most complicated among all others because Neutron
135 security-group-rules are mapped to contracts with clauses,
136 subjects, rules, action-refs, classifier-refs, etc.
137 Contracts are used between endpoint groups representing Neutron Security Groups.
138 For simplification it is important to note that Neutron security-group-rules are
139 similar to a **GBP** rule containing:
141 * classifier with direction
148 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
152 Neutron router is represented as a L3-context. This treats a router as a Layer3
153 namespace, and hence every network attached to it a part
154 of that Layer3 namespace.
156 This allows for multiple routers per tenant with complete isolation.
158 The mapping of the router to an endpoint represents the router's interface or
161 The mapping to an EndpointGroup represents the internal infrastructure
162 EndpointGroups created by the **GBP** Neutron Mapper
164 When a Neutron router interface is attached to a network/subnet, that
165 network/subnet and its associated endpoints or Neutron Ports are seamlessly
166 added to the namespace.
168 **Neutron FloatingIP**
170 When associated with a Neutron Port, this leverages the *GBP* OfOverlay
171 renderer's NAT capabilities.
173 A dedicated *external* interface on each Nova compute host allows for
174 disitributed external access. Each Nova instance associated with a
175 FloatingIP address can access the external network directly without having to
176 route via the Neutron controller, or having to enable any form
177 of Neutron distributed routing functionality.
179 Assuming the gateway provisioned in the Neutron Subnet command for the external
180 network is reachable, the combination of *GBP* Neutron Mapper and
181 OfOverlay renderer will automatically ARP for this default gateway, requiring
182 no user intervention.
185 **Troubleshooting within GBP**
187 Logging level for the mapping functionality can be set for package
188 org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE
189 logging level on karaf console:
193 log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
195 **Neutron mapping example**
197 As an example for mapping can be used creation of Neutron network, subnet and
198 port. When a Neutron network is created 3 **GBP** entities are created:
199 l2-flood-domain, l2-bridge-domain, l3-context.
201 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
203 Neutron network mapping
205 After an subnet is created in the network mapping looks like this.
207 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
209 Neutron subnet mapping
211 If an Neutron port is created in the subnet an endpoint and l3-endpoint are
212 created. The endpoint has key composed from l2-bridge-domain and MAC address
213 from Neutron port. A key of l3-endpoint is compesed from l3-context and IP
214 address. The network containment of endpoint and l3-endpoint points to the
218 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
222 Configuring GBP Neutron
223 -----------------------
225 No intervention passed initial OpenStack setup is required by the user.
227 More information about configuration can be found in our DevStack demo
228 environment on the `GBP wiki <gbp_wiki_>`_.
230 Administering or Managing GBP Neutron
231 -------------------------------------
233 For consistencies sake, all provisioning should be performed via the Neutron API. (CLI or Horizon).
235 The mapped policies can be augmented via the **GBP** UX,UX, to:
237 * Enable Service Function Chaining
238 * Add endpoints from outside of Neutron i.e. VMs/containers not provisioned in OpenStack
239 * Augment policies/contracts derived from Security Group Rules
240 * Overlay additional contracts or groupings
245 A DevStack demo environment can be found on the
246 `GBP wiki <gbp_wiki_>`_.
248 .. _gbp_wiki: https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)
249 .. _neutron_v2api: http://developer.openstack.org/api-ref-networking-v2.html