docs/opendaylight-with-openstack/openstack-with-gbp.rst

   1 OpenStack with GroupBasedPolicy
   2 ===============================
   3
   4 This section is for Application Developers and Network Administrators
   5 who are looking to integrate Group Based Policy with OpenStack.
   6
   7 To enable the **GBP** Neutron Mapper feature, at the karaf console:
   8
   9 .. code-block:: bash
  10
  11     feature:install odl-groupbasedpolicy-neutronmapper
  12
  13 Neutron Mapper has the following dependencies that are automatically loaded:
  14
  15 .. code-block:: bash
  16
  17     odl-neutron-service
  18
  19 Neutron Northbound implementing REST API used by OpenStack
  20
  21 .. code-block:: bash
  22
  23     odl-groupbasedpolicy-base
  24
  25 Base **GBP** feature set, such as policy resolution, data model etc.
  26
  27 .. code-block:: bash
  28
  29     odl-groupbasedpolicy-ofoverlay
  30
  31 For this release, **GBP** has one renderer, hence this is loaded by default.
  32
  33 REST calls from OpenStack Neutron are by the Neutron NorthBound project.
  34
  35 **GBP** provides the implementation of the `Neutron V2.0 API <neutron_v2api_>`_.
  36
  37 Features
  38 --------
  39
  40 List of supported Neutron entities:
  41
  42 * Port
  43 * Network
  44
  45   * Standard Internal
  46   * External provider L2/L3 network
  47
  48 * Subnet
  49 * Security-groups
  50 * Routers
  51
  52   * Distributed functionality with local routing per compute
  53   * External gateway access per compute node (dedicated port required)
  54   * Multiple routers per tenant
  55
  56 * FloatingIP NAT
  57 * IPv4/IPv6 support
  58
  59 The mapping of Neutron entities to **GBP** entities is as follows:
  60
  61 **Neutron Port**
  62
  63 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
  64
  65    Neutron Port
  66
  67 The Neutron port is mapped to an endpoint.
  68
  69 The current implementation supports one IP address per Neutron port.
  70
  71 An endpoint and L3-endpoint belong to multiple EndpointGroups if the Neutron
  72 port is in multiple Neutron Security Groups.
  73
  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
  76 Neutron port.
  77 An L3-endpoint is created based on L3-context (the parent of the
  78 L2-bridge-domain) and IP address of Neutron Port.
  79
  80 **Neutron Network**
  81
  82 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
  83
  84    Neutron Network
  85
  86 A Neutron network has the following characteristics:
  87
  88 * defines a broadcast domain
  89 * defines a L2 transmission domain
  90 * defines a L2 name space.
  91
  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.
  97
  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.
 100
 101 **Neutron Subnet**
 102
 103
 104 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
 105
 106    Neutron Subnet
 107
 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.
 111
 112 **Neutron Security Group**
 113
 114
 115 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
 116
 117    Neutron Security Group and Rules
 118
 119 **GBP** entity representing Neutron security-group is EndpointGroup.
 120
 121 **Infrastructure EndpointGroups**
 122
 123 Neutron-mapper automatically creates EndpointGroups to manage key infrastructure
 124 items such as:
 125
 126 * DHCP EndpointGroup - contains endpoints representing Neutron DHCP ports
 127 * Router EndpointGroup - contains endpoints representing Neutron router
 128   interfaces
 129 * External EndpointGroup - holds L3-endpoints representing Neutron router
 130   gateway ports, also associated with FloatingIP ports.
 131
 132 **Neutron Security Group Rules**
 133
 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:
 140
 141 * classifier with direction
 142 * action of *allow*.
 143
 144
 145 **Neutron Routers**
 146
 147
 148 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
 149
 150    Neutron Router
 151
 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.
 155
 156 This allows for multiple routers per tenant with complete isolation.
 157
 158 The mapping of the router to an endpoint represents the router's interface or
 159 gateway port.
 160
 161 The mapping to an EndpointGroup represents the internal infrastructure
 162 EndpointGroups created by the **GBP** Neutron Mapper
 163
 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.
 167
 168 **Neutron FloatingIP**
 169
 170 When associated with a Neutron Port, this leverages the *GBP* OfOverlay
 171 renderer's NAT capabilities.
 172
 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.
 178
 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.
 183
 184
 185 **Troubleshooting within GBP**
 186
 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:
 190
 191 .. code-block:: bash
 192
 193     log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
 194
 195 **Neutron mapping example**
 196
 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.
 200
 201 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
 202
 203    Neutron network mapping
 204
 205 After an subnet is created in the network mapping looks like this.
 206
 207 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
 208
 209    Neutron subnet mapping
 210
 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
 215 subnet.
 216
 217
 218 .. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
 219
 220    Neutron port mapping
 221
 222 Configuring GBP Neutron
 223 -----------------------
 224
 225 No intervention passed initial OpenStack setup is required by the user.
 226
 227 More information about configuration can be found in our DevStack demo
 228 environment on the `GBP wiki <gbp_wiki_>`_.
 229
 230 Administering or Managing GBP Neutron
 231 -------------------------------------
 232
 233 For consistencies sake, all provisioning should be performed via the Neutron API. (CLI or Horizon).
 234
 235 The mapped policies can be augmented via the **GBP** UX,UX, to:
 236
 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
 241
 242 Tutorials
 243 ---------
 244
 245 A DevStack demo environment can be found on the
 246 `GBP wiki <gbp_wiki_>`_.
 247
 248 .. _gbp_wiki: https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)
 249 .. _neutron_v2api: http://developer.openstack.org/api-ref-networking-v2.html