Chapter 10. Configuring bridge mappings

In Red Hat OpenStack Platform (RHOSP), a bridge mapping associates a physical network name (an interface label) to a bridge created with the Modular Layer 2 plug-in mechanism drivers Open vSwitch (OVS) or Open Virtual Network (OVN). The RHOSP Networking service (neutron) uses bridge mappings to allow provider network traffic to reach the physical network.

The topics included in this section are:

10.1. Overview of bridge mappings

In the Red Hat OpenStack Platform (RHOSP) Networking service (neutron), you use bridge mappings to allow provider network traffic to reach the physical network. Traffic leaves the provider network from the qg-xxx interface of the router and arrives at the intermediate bridge (br-int).

The next part of the data path varies depending on which mechanism driver your deployment uses:

  • ML2/OVS: a patch port between br-int and br-ex allows the traffic to pass through the bridge of the provider network and out to the physical network.
  • ML2/OVN: the Networking service creates a patch port on a hypervisor only when there is a VM bound to the hypervisor and the VM requires the port.

You configure the bridge mapping on the network node on which the router is scheduled. Router traffic can egress using the correct physical network, as represented by the provider network.

Note

The Networking service supports only one bridge for each physical network. Do not map more than one physical network to the same bridge.

10.2. Traffic flow

Each external network is represented by an internal VLAN ID, which is tagged to the router qg-xxx port. When a packet reaches phy-br-ex, the br-ex port strips the VLAN tag and moves the packet to the physical interface and then to the external network.

The return packet from the external network arrives on br-ex and moves to br-int using phy-br-ex <-> int-br-ex. When the packet is going through br-ex to br-int, the packet’s external VLAN ID is replaced by an internal VLAN tag in br-int, and this allows qg-xxx to accept the packet.

In the case of egress packets, the packet’s internal VLAN tag is replaced with an external VLAN tag in br-ex (or in the external bridge that is defined in the NeutronNetworkVLANRanges parameter).

10.3. Configuring bridge mappings

To modify the bridge mappings that the Red Hat OpenStack Platform (RHOSP) Networking service (neutron) uses to connect provider network traffic with the physical network, you modify the necessary heat parameters and redeploy your overcloud.

Prerequisites

  • You must be able to access the underclod host as the stack user.
  • You must configure bridge mappings on the network node on which the router is scheduled.
  • You must also configure bridge mappings for your Compute nodes.

Procedure

  1. Log in to the undercloud host as the stack user.

  2. Source the undercloud credentials file: 

    $ source ~/stackrc

  3. Create a custom YAML environment file.

    Example

    $ vi /home/stack/templates/my_bridge_mappings.yaml

  4. Your environment file must contain the keywords parameter_defaults. Add the NeutronBridgeMappings heat parameter with values that are appropriate for your site after the parameter_defaults keyword.

    Example

    In this example, the NeutronBridgeMappings parameter associates the physical names, datacentre and tenant, the bridges br-ex and br-tenant, respectively. 

    parameter_defaults:
  NeutronBridgeMappings: "datacentre:br-ex,tenant:br-tenant"
    Note

    When the NeutronBridgeMappings parameter is not used, the default maps the external bridge on hosts (br-ex) to a physical name (datacentre).

  5. If you are using a flat network, add its name using the NeutronFlatNetworks parameter.

    Example

    In this example, the parameter associates physical name datacentre with bridge br-ex, and physical name tenant with bridge br-tenant." 

    parameter_defaults:
  NeutronBridgeMappings: "datacentre:br-ex,tenant:br-tenant"
  NeutronFlatNetworks: "my_flat_network"
    Note

    When the NeutronFlatNetworks parameter is not used, the default is datacentre.

  6. If you are using a VLAN network, specify the network name along with the range of VLANs it accesses by using the NeutronNetworkVLANRanges parameter.

    Example

    In this example, the NeutronNetworkVLANRanges parameter specifies the VLAN range of 1 - 1000 for the tenant network: 

    parameter_defaults:
 NeutronBridgeMappings: "datacentre:br-ex,tenant:br-tenant"
 NeutronNetworkVLANRanges: "tenant:1:1000"

  7. Run the deployment command and include the core heat templates, environment files, and this new custom environment file. 

    $ openstack overcloud deploy --templates \
  -e <your_environment_files> \
  -e /home/stack/templates/my_bridge_mappings.yaml

  8. Perform the following steps:

    1. Using the network VLAN ranges, create the provider networks that represent the corresponding external networks. (You use the physical name when creating neutron provider networks or floating IP networks.)
    2. Connect the external networks to your project networks with router interfaces.

Additional resources

10.4. Maintaining bridge mappings for OVS

After removing any OVS bridge mappings, you must perform a subsequent cleanup to ensure that the bridge configuration is cleared of any associated patch port entries. You can perform this operation in the following ways:

  • Manual port cleanup - requires careful removal of the superfluous patch ports. No outages of network connectivity are required.
  • Automated port cleanup - performs an automated cleanup, but requires an outage, and requires that the necessary bridge mappings be re-added. Choose this option during scheduled maintenance windows when network connectivity outages can be tolerated.
Note

When OVN bridge mappings are removed, the OVN controller automatically cleans up any associated patch ports.

10.4.1. Cleaning up OVS patch ports manually

After removing any OVS bridge mappings, you must also remove the associated patch ports.

Prerequisites

  • The patch ports that you are cleaning up must be Open Virtual Switch (OVS) ports.
  • A system outage is not required to perform a manual patch port cleanup.

  • You can identify the patch ports to cleanup by their naming convention:

    • In br-$external_bridge patch ports are named phy-<external bridge name> (for example, phy-br-ex2).
    • In br-int patch ports are named int-<external bridge name> (for example, int-br-ex2).

Procedure

  1. Use ovs-vsctl to remove the OVS patch ports associated with the removed bridge mapping entry: 

    # ovs-vsctl del-port br-ex2 datacentre
# ovs-vsctl del-port br-tenant tenant

  2. Restart neutron-openvswitch-agent: 

    # service neutron-openvswitch-agent restart

10.4.2. Cleaning up OVS patch ports automatically

After removing any OVS bridge mappings, you must also remove the associated patch ports.

Note

When OVN bridge mappings are removed, the OVN controller automatically cleans up any associated patch ports.

Prerequisites

  • The patch ports that you are cleaning up must be Open Virtual Switch (OVS) ports.
  • Cleaning up patch ports automatically with the neutron-ovs-cleanup command causes a network connectivity outage, and should be performed only during a scheduled maintenance window.
  • Use the flag --ovs_all_ports to remove all patch ports from br-int, cleaning up tunnel ends from br-tun, and patch ports from bridge to bridge.
  • The neutron-ovs-cleanup command unplugs all patch ports (instances, qdhcp/qrouter, among others) from all OVS bridges.

Procedure

  1. Run the neutron-ovs-cleanup command with the --ovs_all_ports flag.

    Important

    Performing this step will result in a total networking outage. 

    # /usr/bin/neutron-ovs-cleanup
--config-file /etc/neutron/plugins/ml2/openvswitch_agent.ini
--log-file /var/log/neutron/ovs-cleanup.log --ovs_all_ports

  2. Restore connectivity by redeploying the overcloud.

    When you rerun the openstack overcloud deploy command, your bridge mapping values are reapplied.

    Note

    After a restart, the OVS agent does not interfere with any connections that are not present in bridge_mappings. So, if you have br-int connected to br-ex2, and br-ex2 has some flows on it, removing br-int from the bridge_mappings configuration does not disconnect the two bridges when you restart the OVS agent or the node.

Additional resources