Jump to: navigation, search

Difference between revisions of "Neutron/TrunkPort"

(→‎Links)
 
(183 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
−
Neutron extension to access lots of neutron networks over a single vNIC as encapsulated traffic.
+
Neutron extension to access lots of neutron networks over a single vNIC as tagged/encapsulated traffic.
  
−
=== API ===
+
Implementations exist for
 +
* since Newton: Open vSwitch [https://github.com/openstack/neutron/tree/9.1.1/neutron/services/trunk/drivers/openvswitch (src)],
 +
* since Newton: Linux Bridge [https://github.com/openstack/neutron/tree/9.1.1/neutron/services/trunk/drivers/linuxbridge (src)],
 +
* since Newton: OVN [https://github.com/openstack/networking-ovn/blob/1.0.0/networking_ovn/ml2/trunk_driver.py (src)],
 +
* since Ocata? / Carbon: OpenDaylight (src: [https://review.openstack.org/421895 networking-odl], [https://git.opendaylight.org/gerrit/50615 odl]), and
 +
* since Ocata: VMWare NSX [https://github.com/openstack/vmware-nsx/tree/master/vmware_nsx/services/trunk (src)].
 +
* since Pike: Ironic [https://bugs.launchpad.net/neutron/+bug/1648129 (rfe)].
 +
* since Pike: Dragonflow [https://review.openstack.org/#/c/438683/ (src)] [https://review.openstack.org/#/c/437486/ (spec)]
 +
* since ?: Cisco-Nexus [https://review.openstack.org/474364 (src)]
 +
* since Rocky: baremetal trunks on Arista [https://review.openstack.org/563784 (src)]
  
−
==== trunk port ====
+
There's further support
 +
* since Pike: [https://blueprints.launchpad.net/heat/+spec/support-trunk-port in Heat]
 +
* since Queens: [https://blueprints.launchpad.net/horizon/+spec/neutron-trunk-ui in Horizon]
  
−
FIXME attribute types
+
== Introduction ==
 +
 
 +
* Introductory Presentation from the Sydney Summit, 2017 November
 +
** [https://www.youtube.com/watch?v=c3JmWgrnfKI video (youtube.com)]
 +
** [https://docs.google.com/presentation/d/1LgGJBWODar7hUGxN84xP_JTF5QSB6JovFJMAunjb9No/view slides (docs.google.com)]
 +
* Introductory [http://www.jimmdenton.com/neutron-trunks blog post (jimmdenton.com)] by James Denton
 +
 
 +
== Documentation ==
 +
 
 +
* OpenStack Networking Guide
 +
** [https://github.com/openstack/neutron/blob/master/doc/source/admin/config-trunking.rst latest]
 +
** [https://docs.openstack.org/neutron/pike/admin/config-trunking.html pike]
 +
** [http://docs.openstack.org/ocata/networking-guide/config-trunking.html ocata]
 +
* Heat
 +
** [https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Neutron::Trunk template guide]
 +
** [https://github.com/openstack/heat-templates/blob/master/hot/neutron/instance_trunk_port.yaml example template]
 +
* Design Documents
 +
** [http://specs.openstack.org/openstack/neutron-specs/specs/newton/vlan-aware-vms.html neutron spec]
 +
 
 +
=== API Reference ===
 +
 
 +
* read-write, extension=trunk
 +
** http://developer.openstack.org/api-ref/networking/v2/#trunk-networking
 +
** http://git.openstack.org/cgit/openstack/neutron/tree/neutron/extensions/trunk.py
 +
* read-only convenience, extension=trunk-details
 +
** http://developer.openstack.org/api-ref/networking/v2/#trunk-details-extended-attributes-ports
 +
** http://git.openstack.org/cgit/openstack/neutron/tree/neutron/extensions/trunk_details.py
 +
 
 +
==== Network dump ====
 +
 
 +
Dump of the API as released in Newton: https://etherpad.openstack.org/p/trunk-api-dump-newton
 +
 
 +
==== API-CLI mapping ====
  
 
{| class="wikitable sortable"
 
{| class="wikitable sortable"
−
! attribute name
+
! CLI verb
−
! attribute type
+
! HTTP method
−
|-
+
! URL
−
| admin_state_up
+
! CLI verb (as in the spec, obsolete)
−
|
 
−
|-
 
−
| binding:host_id
 
−
| str
 
−
|-
 
−
| binding:vif_details
 
−
|
 
 
|-
 
|-
−
| binding:vif_type
+
| openstack network trunk create
−
|
+
| POST
 +
| /v2.0/trunks
 +
| trunk-create
 
|-
 
|-
−
| device_id
+
| openstack network trunk delete
−
| uuid
+
| DELETE
 +
| /v2.0/trunks/$trunk_id
 +
| trunk-delete
 
|-
 
|-
−
| device_owner
+
| openstack network trunk list
−
|
+
| GET
 +
| /v2.0/trunks
 +
| trunk-list
 
|-
 
|-
−
| id
+
| openstack network trunk show
−
| uuid
+
| GET
 +
| /v2.0/trunks/$trunk_id
 +
| trunk-show
 
|-
 
|-
−
| mac_address
+
| openstack network trunk set
−
|
+
| PUT
 +
| /v2.0/trunks/$trunk_id
 +
| trunk-update
 
|-
 
|-
−
| name
+
| openstack network trunk set --subport
−
| str
+
| PUT
 +
| /v2.0/trunks/$trunk_id/add_subports
 +
| trunk-subport-add
 
|-
 
|-
−
| status
+
| openstack network trunk unset --subport
−
|
+
| PUT
 +
| /v2.0/trunks/$trunk_id/remove_subports
 +
| trunk-subport-delete
 
|-
 
|-
−
| tenant_id
+
| openstack network subport list
−
| uuid
+
| GET
 +
| /v2.0/trunks/$trunk_id/get_subports
 +
| trunk-subport-list
 
|}
 
|}
  
−
whishlist attributes:
+
== CLI usage examples ==
−
* subport_count
 
  
−
=== CLI usage example ===
+
=== Basic ===
  
 
<pre>
 
<pre>
−
# Trunk ports are created independently of networks.
+
# Business as usual.
−
neutron trunk-port-create --name trunk-port0
+
openstack network create net0
 +
openstack network create net1
 +
openstack network create net2
 +
openstack subnet create --network net0 --subnet-range 10.0.4.0/24 subnet0
 +
openstack subnet create --network net1 --subnet-range 10.0.5.0/24 subnet1
 +
openstack subnet create --network net2 --subnet-range 10.0.6.0/24 subnet2
 +
 
 +
openstack port create --network net0 port0 # will become a parent port
 +
 
 +
# As of pike there's no standard automation to tell the guest OS the MAC addresses of child ports. So
 +
#
 +
#    # (a) either create child ports having the same MAC address as the parent port
 +
#    # (remember, they are on different networks),
 +
#    # NOTE This approach was affected by a bug of the openvswitch firewall driver:
 +
#    # https://bugs.launchpad.net/neutron/+bug/1626010 # the fix made the Pike release
 +
#            openstack port create --network ... parent-port
 +
#            parent_mac="$( openstack port show parent-port | awk '/ mac_address / { print $4 }' )"
 +
#            openstack port create --mac-address "$parent_mac" --network ... child-port
 +
#            openstack network trunk create --parent-port parent-port trunk0
 +
#            openstack network trunk set --subport port=child-port,segmentation-type=vlan,segmentation-id=101 trunk0
 +
#            openstack server-create --nic port-id=parent-port ... --wait vm0
 +
#            ssh vm0 sudo ip link add link eth0 name eth0.101 type vlan id 101
 +
#            # eth0 and eth0.101 have the same MAC address
 +
#
 +
#    # (b) or create the VLAN subinterfaces with MAC addresses as random-assigned by neutron.
 +
#            openstack port create --network ... parent-port
 +
#            openstack port create --network ... child-port
 +
#            child_mac="$( openstack port show child-port | awk '/ mac_address / { print $4 }' )"
 +
#            openstack network trunk create --parent-port parent-port trunk0
 +
#            openstack network trunk set --subport port=child-port,segmentation-type=vlan,segmentation-id=101 trunk0
 +
#            openstack server-create --nic port-id=parent-port ... --wait vm0
 +
#            ssh vm0 sudo ip link add link eth0 name eth0.101 address "$child_mac" type vlan id 101
 +
#            # eth0 and eth0.101 have different MAC addresses
 +
#
 +
# We follow option (a) here:
 +
parent_mac="$( openstack port show port0 | awk '/ mac_address / { print $4 }' )"
 +
 
 +
openstack port create --network net1 --mac-address "$parent_mac" port1 # will become a child port: at trunk create time
 +
openstack port create --network net2 --mac-address "$parent_mac" port2 # will become a child port: later
 +
 
 +
# Create a trunk using port0 as parent port (ie. turn port0 into a trunk port).
 +
openstack network trunk create --parent-port port0 trunk0
 +
# A port can be part of one trunk only.
 +
# Error expected: Port UUID is currently in use and is not eligible for use as a parent port.
 +
openstack network trunk create --parent-port port0 trunk1
  
−
# Networks for later subports.
+
openstack network trunk list
−
neutron net-create net0
+
openstack network trunk show trunk0
−
neutron net-create net1
 
  
−
# Optional subnets.
+
openstack network trunk delete trunk0
−
neutron subnet-create net0 10.0.0.0/24
 
−
neutron subnet-create net1 10.0.1.0/24
 
  
−
# Ports having --device-owner 'network:trunk-port' are subports of the trunk port given by uuid.
+
# A trunk can be created with subports too.
−
# The subport without --trunk-port:* options is the default subport.
+
openstack network trunk create --parent-port port0 --subport port=port1,segmentation-type=vlan,segmentation-id=101 trunk0
−
# The default subport's traffic will be seen as untagged inside the instance.
+
openstack network trunk list
−
# You likely want network connectivity during boot, so you should create at least the default subport before booting.
+
openstack network trunk show trunk0
−
neutron port-create net0 --name port0 --device-owner network:trunk-port --device-id TRUNK-PORT0-UUID
+
openstack network subport list --trunk trunk0
  
−
# Other subports can be created at any time, including before boot.
+
# Use an image with support for vlan interfaces. CirrOS will not cut it.
−
# The traffic of further subports has to be differentiated inside the instance by encapsulation, so you need to provide a segmentation type and id.
+
# But see also: https://etherpad.openstack.org/p/cirros-respin
−
neutron port-create net1 --name port1 --device-owner network:trunk-port --device-id TRUNK-PORT0-UUID --trunk-port:segmentation-type vlan --trunk-port:segmentation-id 101
+
# eg: sudo ip link add ... type vlan ...
 +
wget --timestamping --tries=1 https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
 +
openstack image create --disk-format qcow2 --public --file trusty-server-cloudimg-amd64-disk1.img vlan-capable-image
  
−
# The only vNIC in your instance corresponds to the trunk port, so boot your instance with the trunk port given. Do not add subports as NICs to 'nova boot'.
+
# The only vNIC in your instance corresponds to the parent port, so boot your instance with the parent port given.
−
# Use an image with support for vlan interfaces. CirrOS will not cut it. eg: sudo ip link add ... type vlan ...
+
# Do not add child ports as NICs to 'nova boot / openstack server create'.
−
nova boot ... --image VLAN-CAPABLE-IMAGE --nic trunk-port-id=TRUNK-PORT0-UUID --poll vm0
+
openstack server create --flavor ds512M --image vlan-capable-image --nic port-id=port0 --wait vm0
  
−
# The typical cloud image will auto-configure eth0 only and not the vlan interfaces (eth0.VLAN-ID).
+
# The typical cloud image will auto-configure the first NIC (eg. eth0) only and not the vlan interfaces (eg. eth0.VLAN-ID).
 
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.101 type vlan id 101
 
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.101 type vlan id 101
  
−
# Other subports can be created at any time, including after boot.
+
# Error expected: Failed to add subports to trunk 'trunk0': Port UUID is in use by another trunk.
−
neutron net-create net2
+
openstack network trunk set --subport port=port1,segmentation-type=vlan,segmentation-id=999 trunk0
−
neutron subnet-create net2 10.0.2.0/24
+
# Error expected: Failed to add subports to trunk 'trunk0': segmentation_type vlan and segmentation_id 101 already in use on trunk UUID.
−
neutron port-create net2 --name port2 --device-owner network:trunk-port --device-id TRUNK-PORT0-UUID --trunk-port:segmentation-type vlan --trunk-port:segmentation-id 102
+
openstack network trunk set --subport port=port2,segmentation-type=vlan,segmentation-id=101 trunk0
 +
# Add subports to a running instance.
 +
openstack network trunk set --subport port=port2,segmentation-type=vlan,segmentation-id=102 trunk0
 +
openstack network trunk show trunk0
  
 
# Again you need to bring your subport vlan interfaces up.
 
# Again you need to bring your subport vlan interfaces up.
 
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.102 type vlan id 102
 
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.102 type vlan id 102
  
−
# Subports can be deleted at runtime too.
+
# Delete subports from a running instance.
 
ssh VM0-ADDRESS sudo ip link delete dev eth0.102
 
ssh VM0-ADDRESS sudo ip link delete dev eth0.102
−
neutron port-delete port1
+
openstack network trunk unset --subport port2 trunk0
 +
 
 +
# Cannot delete ports used as parent or subports. Delete the trunk first.
 +
# Error expected: FIXME HttpException: Conflict
 +
openstack port delete port0
 +
# Error expected: FIXME HttpException: Conflict
 +
openstack port delete port1
  
−
# When you're all done, deleting the trunk port deletes all the subports too.
+
# Clean up.
−
nova delete vm0
+
openstack server delete vm0
−
neutron trunk-port-delete trunk-port0
+
openstack network trunk delete trunk0
−
neutron net-delete net2
+
openstack port delete port2 port1 port0
−
neutron net-delete net1
+
openstack network delete net2 net1 net0
−
neutron net-delete net0
 
 
</pre>
 
</pre>
  
−
=== openvswitch vlan model ===
+
=== Inherit the provider network's segmentation details ===
 +
 
 +
When the switch is incapable of remapping (tag pop-push) you may want to expose the provider network's segmentation details (think of Ironic):
  
 
<pre>
 
<pre>
−
# create trunk bridge
+
openstack network create net0 --provider-network-type vlan --provider-physical-network test --provider-segment 100
−
ovs-vsctl --may-exist add-br TRUNK-BRIDGE
+
openstack network create net1 --provider-network-type vlan --provider-physical-network test --provider-segment 101
−
ovs-ofctl del-flows TRUNK-BRIDGE
+
openstack subnet create subnet0 --network net0 --subnet-range 10.0.4.0/24
 +
openstack subnet create subnet1 --network net1 --subnet-range 10.0.5.0/24
 +
openstack port create port0 --network net0
 +
openstack port create port1 --network net1
 +
openstack network trunk create trunk0 --parent-port port0
 +
openstack network trunk set trunk0 --subport port=port1,segmentation-type=inherit
 +
openstack network subport list --trunk itrunk0 -f value -c 'Segmentation ID' # prints 101
 +
</pre>
 +
 
 +
<!--
 +
Beware that by default policies the provider network's segmentation details are admin-only, but (after inheriting) the trunk's segmentation are readable by non-admins. So only enable the trunk extension if you do not consider the segmentation details of your provider networks sensitive information.
 +
-->
 +
 
 +
== Drawings ==
  
−
# patch trunk bridge to integration bridge
+
<gallery mode="traditional" widths=320px>
−
ovs-vsctl add-port TRUNK-BRIDGE PATCH-TRUNK-END-PORT -- set Interface PATCH-TRUNK-END-PORT type=patch options:peer=PATCH-INT-END-PORT
+
File:TrunkVnicsBefore.svg|legacy model of attaching many networks
−
ovs-vsctl add-port br-int PATCH-INT-END-PORT -- set Interface PATCH-INT-END-PORT type=patch options:peer=PATCH-TRUNK-END-PORT
+
File:TrunkVnicsAfter.svg|trunk model of attaching many networks
 +
</gallery>
  
−
# install default drop flows on patch ports
+
<gallery mode="traditional" widths=240px>
−
ovs-ofctl add-flow TRUNK-BRIDGE hard_timeout=0,idle_timeout=0,priority=2,in_port=PATCH-TRUNK-END-OFPORT,actions=drop
+
File:TrunkApiBefore.svg|legacy API
−
ovs-ofctl add-flow br-int hard_timeout=0,idle_timeout=0,priority=2,in_port=PATCH-INT-END-OFPORT,actions=drop
+
File:TrunkApiAfter.svg|trunk API
 +
</gallery>
  
−
# install remap flows for untagged traffic (default subport)
+
<gallery mode="traditional" widths=240px>
−
ovs-ofctl add-flow TRUNK-BRIDGE hard_timeout=0,idle_timeout=0,priority=3,dl_vlan=COMPUTE-INTERNAL-VLAN-ID,in_port=PATCH-TRUNK-END-OFPORT,actions=strip_vlan,normal
+
File:TrunkOvsModel.svg|example of trunk Open vSwitch model
−
ovs-ofctl add-flow br-int hard_timeout=0,idle_timeout=0,priority=3,dl_vlan=0xffff,in_port=PATCH-INT-END-OFPORT,actions=mod_vlan_vid:COMPUTE-INTERNAL-VLAN-ID,normal
+
</gallery>
  
−
# install remap flows for tagged traffic (other subports)
+
== Screenshots ==
−
ovs-ofctl add-flow TRUNK-BRIDGE hard_timeout=0,idle_timeout=0,priority=3,dl_vlan=COMPUTE-INTERNAL-VLAN-ID,in_port=PATCH-TRUNK-END-OFPORT,actions=mod_vlan_vid:INNER-VLAN-ID,normal
 
−
ovs-ofctl add-flow br-int hard_timeout=0,idle_timeout=0,priority=3,dl_vlan=INNER-VLAN-ID,in_port=PATCH-INT-END-OFPORT,actions=mod_vlan_vid:COMPUTE-INTERNAL-VLAN-ID,normal
 
  
−
# make the tap port pass all tags
+
<gallery mode="traditional" widths=240px>
−
ovs-vsctl set Port TAP-PORT vlan_mode=trunk
+
File:Trunk-panel.png|Horizon screenshot: Project/Network/Trunks panel
−
</pre>
+
File:Trunk-detail.png|Horizon screenshot: Trunk detail
 +
File:Trunk-create-subports.png|Horizon screenshot: Subport(s) selector step of create workflow
 +
</gallery>
  
−
== Work Items ==
+
== Performance / Scaling ==
  
 +
* A separate wiki page documents some [[Neutron Trunk API Performance and Scaling|performance and scale measurments]] of the trunk API by Ericsson.
 +
* See also [http://lists.openstack.org/pipermail/openstack-dev/2016-December/108462.html this openstack-dev thread] about measurements by the QE team of HPE.
  
 
== Links ==
 
== Links ==
  
−
* Mitaka Summit, Tokyo, 2015-10
+
* related development
−
** [https://etherpad.openstack.org/p/vlan-aware-vms etherpad of the trunk port contributors' meetup]
+
** horizon
−
** vBrownBag session
+
*** [https://blueprints.launchpad.net/horizon/+spec/neutron-trunk-ui horizon blueprint]
−
*** [http://www.slideshare.net/benceromsics/openstack-trunk-port slides (slideshare.net)]
+
*** [https://review.openstack.org/#/q/topic:bp/neutron-trunk-ui gerrit topic bp/neutron-trunk-ui]
−
*** [https://youtu.be/v-Ia2FObjxs video (youtube.com)]
+
** heat
 +
*** [https://review.openstack.org/424571 heat spec]
 +
*** [https://review.openstack.org/#/q/topic:bp/support-trunk-port gerrit topic bp/support-trunk-port]
 +
** nova
 +
*** [https://review.openstack.org/#/q/topic:bp/expose-vlan-trunking gerrit topic bp/expose-vlan-trunking]
 +
** odl
 +
*** [https://review.openstack.org/421895 openstack/networking-odl]
 +
*** [https://git.opendaylight.org/gerrit/50615 odl yang model]
 +
 
 +
* bugs
 +
** https://bugs.launchpad.net/neutron/+bugs?field.tag=trunk
 +
** https://bugs.launchpad.net/neutron/+bug/1626010
 +
 
 +
* openvswitch vlan model
 +
** https://opendev.org/openstack/neutron/src/commit/7d48bde722fecfa5efffb1c4e7018dab8b8d6366/doc/source/contributor/internals/openvswitch_agent.rst#tackling-the-network-trunking-use-case
 +
** https://etherpad.openstack.org/p/trunk-bridge-tagged-patch-ovs-firewall-experiment
 +
 
 +
* tests
 +
** repo [https://github.com/openstack/neutron openstack/neutron]
 +
*** neutron/tests/unit/services/trunk/
 +
*** neutron/tests/functional/services/trunk/
 +
*** neutron/tests/fullstack/test_trunk.py
 +
*** neutron/tests/tempest/scenario/test_trunk.py
 +
*** neutron/tests/tempest/api/test_trunk.py
 +
*** neutron/tests/tempest/api/test_trunk_negative.py
 +
*** neutron/tests/tempest/api/test_trunk_details.py
 +
*** rally-jobs/plugins/trunk_scenario.py
 +
** repo [https://github.com/openstack/heat openstack/heat]
 +
*** heat/tests/openstack/neutron/test_neutron_trunk.py
 +
*** heat_integrationtests/functional/test_create_update_neutron_trunk.py
 +
** repo [https://github.com/openstack/horizon openstack/horizon]
 +
*** openstack_dashboard/static/app/core/trunks/**/*.spec.js
 +
*** openstack_dashboard/test/api_tests/neutron_*.py
  
 
* blueprints.launchpad.net
 
* blueprints.launchpad.net
 
** neutron: [https://blueprints.launchpad.net/neutron/+spec/vlan-aware-vms bp/vlan-aware-vms]
 
** neutron: [https://blueprints.launchpad.net/neutron/+spec/vlan-aware-vms bp/vlan-aware-vms]
−
** nova: [https://blueprints.launchpad.net/nova/+spec/trunk-port bp/trunk-port]
+
** nova: [https://blueprints.launchpad.net/nova/+spec/neutron-ovs-bridge-name bp/neutron-ovs-bridge-name]
 +
 
 
* specs.openstack.org
 
* specs.openstack.org
−
** neutron: [http://specs.openstack.org/openstack/neutron-specs/specs/liberty/vlan-aware-vms.html neutron-specs/liberty/vlan-aware-vms]
+
** [http://specs.openstack.org/openstack/neutron-specs/specs/newton/vlan-aware-vms.html neutron-specs/newton/vlan-aware-vms]
−
** <strike>nova: [http://specs.openstack.org/openstack/nova-specs/specs/mitaka/trunk-port.html nova-specs/mitaka/trunk-port]</strike>
+
** [http://specs.openstack.org/openstack/neutron-specs/specs/mitaka/vlan-aware-vms.html neutron-specs/mitaka/vlan-aware-vms]
 +
 
 
* review.openstack.org
 
* review.openstack.org
−
** neutron-spec: [https://review.openstack.org/94612 neutron-specs/vlan-aware-vms]
+
** neutron-spec
−
** nova-spec: [https://review.openstack.org/213644 nova-specs/trunk-port]
+
*** v3, v4: [https://review.openstack.org/243786 neutron-specs/vlan-aware-vms]
 +
*** v1, v2: [https://review.openstack.org/94612 neutron-specs/vlan-aware-vms]
 
** neutron: [https://review.openstack.org/#/q/project:openstack/neutron+topic:bp/vlan-aware-vms,n,z project:openstack/neutron topic:bp/vlan-aware-vms]
 
** neutron: [https://review.openstack.org/#/q/project:openstack/neutron+topic:bp/vlan-aware-vms,n,z project:openstack/neutron topic:bp/vlan-aware-vms]
−
** <strike>nova: [https://review.openstack.org/#/q/project:openstack/nova+topic:bp/trunk-port,n,z project:openstack/nova topic:bp/trunk-port]</strike>
+
** nova: [https://review.openstack.org/#/q/topic:bp/neutron-ovs-bridge-name topic:bp/neutron-ovs-bridge-name]
 
** python-neutronclient: [https://review.openstack.org/#/q/project:openstack/python-neutronclient+topic:bp/vlan-aware-vms,n,z project:openstack/python-neutronclient topic:bp/vlan-aware-vms]
 
** python-neutronclient: [https://review.openstack.org/#/q/project:openstack/python-neutronclient+topic:bp/vlan-aware-vms,n,z project:openstack/python-neutronclient topic:bp/vlan-aware-vms]
−
** <strike>python-novaclient: [https://review.openstack.org/#/q/project:openstack/python-novaclient+topic:bp/trunk-port,n,z project:openstack/python-novaclient topic:bp/trunk-port]</strike>
 
 
** tempest: [https://review.openstack.org/#/q/project:openstack/tempest+topic:bp/vlan-aware-vms,n,z project:openstack/tempest topic:bp/vlan-aware-vms]
 
** tempest: [https://review.openstack.org/#/q/project:openstack/tempest+topic:bp/vlan-aware-vms,n,z project:openstack/tempest topic:bp/vlan-aware-vms]
  
−
* [https://etherpad.openstack.org/p/trunk-port-breakdown break down of work items (etherpad.openstack.org)]
+
* obsolete blueprints/specs/code/etc.
−
* [https://etherpad.openstack.org/p/trunkport-design open design questions (etherpad.openstack.org)]
+
** [https://blueprints.launchpad.net/nova/+spec/trunk-port bp/trunk-port]
−
* [https://etherpad.openstack.org/p/trunk-port-design-log log of design decisions (etherpad.openstack.org)]
+
** [http://specs.openstack.org/openstack/nova-specs/specs/mitaka/trunk-port.html nova-specs/mitaka/trunk-port]
 +
** [http://specs.openstack.org/openstack/neutron-specs/specs/liberty/vlan-aware-vms.html neutron-specs/liberty/vlan-aware-vms]
 +
** [https://review.openstack.org/213644 nova-specs/trunk-port]
 +
** [https://review.openstack.org/#/q/project:openstack/nova+topic:bp/trunk-port,n,z project:openstack/nova topic:bp/trunk-port]
 +
** [https://review.openstack.org/#/q/project:openstack/python-novaclient+topic:bp/trunk-port,n,z project:openstack/python-novaclient topic:bp/trunk-port]
 +
** [https://etherpad.openstack.org/p/trunk-port-breakdown break down of work items: v2 (etherpad.openstack.org)]
 +
** [https://etherpad.openstack.org/p/trunkport-design open design questions (etherpad.openstack.org)]
 +
** [https://etherpad.openstack.org/p/trunk-port-design-log log of design decisions (etherpad.openstack.org)]
 +
 
 +
* Mitaka Summit, Tokyo, 2015-10
 +
** [https://etherpad.openstack.org/p/vlan-aware-vms etherpad of the trunk port contributors' meetup]
 +
** vBrownBag session
 +
*** [http://www.slideshare.net/benceromsics/openstack-trunk-port slides (slideshare.net)]
 +
*** [https://youtu.be/v-Ia2FObjxs video (youtube.com)]
 +
 
 +
* meeting etherpads
 +
** irc meet @ 2015-11-18 00:00 (utc)
 +
*** [https://etherpad.openstack.org/p/meet-trunk-port-2015-11-18 agenda]
 +
*** [https://etherpad.openstack.org/p/meet-trunk-port-2015-11-18.log meeting log]
 +
** [https://etherpad.openstack.org/p/vlan-aware-vms etherpad of the trunk port contributors' meetup]
 +
 
 +
* unsorted etherpads
 +
** [https://etherpad.openstack.org/p/trunk-port-v4-backlog v4 backlog]
 +
** [https://etherpad.openstack.org/p/vlan@tap_experiment vlan@tap experiment]
 +
** [https://etherpad.openstack.org/p/trunk-bridge-tagged-patch-experiment trunk bridge experiment]
 +
** [https://etherpad.openstack.org/p/trunk-bridge-tagged-patch-ovs-firewall-experiment trunk bridge with ovs firewall driver experiment]

Latest revision as of 08:17, 10 September 2019

Overview

Neutron extension to access lots of neutron networks over a single vNIC as tagged/encapsulated traffic.

Implementations exist for

  • since Newton: Open vSwitch (src),
  • since Newton: Linux Bridge (src),
  • since Newton: OVN (src),
  • since Ocata? / Carbon: OpenDaylight (src: networking-odl, odl), and
  • since Ocata: VMWare NSX (src).
  • since Pike: Ironic (rfe).
  • since Pike: Dragonflow (src) (spec)
  • since ?: Cisco-Nexus (src)
  • since Rocky: baremetal trunks on Arista (src)

There's further support

Introduction

Documentation

API Reference

Network dump

Dump of the API as released in Newton: https://etherpad.openstack.org/p/trunk-api-dump-newton

API-CLI mapping

CLI verb HTTP method URL CLI verb (as in the spec, obsolete)
openstack network trunk create POST /v2.0/trunks trunk-create
openstack network trunk delete DELETE /v2.0/trunks/$trunk_id trunk-delete
openstack network trunk list GET /v2.0/trunks trunk-list
openstack network trunk show GET /v2.0/trunks/$trunk_id trunk-show
openstack network trunk set PUT /v2.0/trunks/$trunk_id trunk-update
openstack network trunk set --subport PUT /v2.0/trunks/$trunk_id/add_subports trunk-subport-add
openstack network trunk unset --subport PUT /v2.0/trunks/$trunk_id/remove_subports trunk-subport-delete
openstack network subport list GET /v2.0/trunks/$trunk_id/get_subports trunk-subport-list

CLI usage examples

Basic

# Business as usual.
openstack network create net0
openstack network create net1
openstack network create net2
openstack subnet create --network net0 --subnet-range 10.0.4.0/24 subnet0
openstack subnet create --network net1 --subnet-range 10.0.5.0/24 subnet1
openstack subnet create --network net2 --subnet-range 10.0.6.0/24 subnet2

openstack port create --network net0 port0 # will become a parent port

# As of pike there's no standard automation to tell the guest OS the MAC addresses of child ports. So
#
#     # (a) either create child ports having the same MAC address as the parent port
#     # (remember, they are on different networks),
#     # NOTE This approach was affected by a bug of the openvswitch firewall driver:
#     # https://bugs.launchpad.net/neutron/+bug/1626010 # the fix made the Pike release
#            openstack port create --network ... parent-port
#            parent_mac="$( openstack port show parent-port | awk '/ mac_address / { print $4 }' )"
#            openstack port create --mac-address "$parent_mac" --network ... child-port
#            openstack network trunk create --parent-port parent-port trunk0
#            openstack network trunk set --subport port=child-port,segmentation-type=vlan,segmentation-id=101 trunk0
#            openstack server-create --nic port-id=parent-port ... --wait vm0
#            ssh vm0 sudo ip link add link eth0 name eth0.101 type vlan id 101
#            # eth0 and eth0.101 have the same MAC address
#
#     # (b) or create the VLAN subinterfaces with MAC addresses as random-assigned by neutron.
#            openstack port create --network ... parent-port
#            openstack port create --network ... child-port
#            child_mac="$( openstack port show child-port | awk '/ mac_address / { print $4 }' )"
#            openstack network trunk create --parent-port parent-port trunk0
#            openstack network trunk set --subport port=child-port,segmentation-type=vlan,segmentation-id=101 trunk0
#            openstack server-create --nic port-id=parent-port ... --wait vm0
#            ssh vm0 sudo ip link add link eth0 name eth0.101 address "$child_mac" type vlan id 101
#            # eth0 and eth0.101 have different MAC addresses
#
# We follow option (a) here:
parent_mac="$( openstack port show port0 | awk '/ mac_address / { print $4 }' )"

openstack port create --network net1 --mac-address "$parent_mac" port1 # will become a child port: at trunk create time
openstack port create --network net2 --mac-address "$parent_mac" port2 # will become a child port: later

# Create a trunk using port0 as parent port (ie. turn port0 into a trunk port).
openstack network trunk create --parent-port port0 trunk0
# A port can be part of one trunk only.
# Error expected: Port UUID is currently in use and is not eligible for use as a parent port.
openstack network trunk create --parent-port port0 trunk1

openstack network trunk list
openstack network trunk show trunk0

openstack network trunk delete trunk0

# A trunk can be created with subports too.
openstack network trunk create --parent-port port0 --subport port=port1,segmentation-type=vlan,segmentation-id=101 trunk0
openstack network trunk list
openstack network trunk show trunk0
openstack network subport list --trunk trunk0

# Use an image with support for vlan interfaces. CirrOS will not cut it.
# But see also: https://etherpad.openstack.org/p/cirros-respin
# eg: sudo ip link add ... type vlan ...
wget --timestamping --tries=1 https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img
openstack image create --disk-format qcow2 --public --file trusty-server-cloudimg-amd64-disk1.img vlan-capable-image

# The only vNIC in your instance corresponds to the parent port, so boot your instance with the parent port given.
# Do not add child ports as NICs to 'nova boot / openstack server create'.
openstack server create --flavor ds512M --image vlan-capable-image --nic port-id=port0 --wait vm0

# The typical cloud image will auto-configure the first NIC (eg. eth0) only and not the vlan interfaces (eg. eth0.VLAN-ID).
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.101 type vlan id 101

# Error expected: Failed to add subports to trunk 'trunk0': Port UUID is in use by another trunk.
openstack network trunk set --subport port=port1,segmentation-type=vlan,segmentation-id=999 trunk0
# Error expected: Failed to add subports to trunk 'trunk0': segmentation_type vlan and segmentation_id 101 already in use on trunk UUID.
openstack network trunk set --subport port=port2,segmentation-type=vlan,segmentation-id=101 trunk0
# Add subports to a running instance.
openstack network trunk set --subport port=port2,segmentation-type=vlan,segmentation-id=102 trunk0
openstack network trunk show trunk0

# Again you need to bring your subport vlan interfaces up.
ssh VM0-ADDRESS sudo ip link add link eth0 name eth0.102 type vlan id 102

# Delete subports from a running instance.
ssh VM0-ADDRESS sudo ip link delete dev eth0.102
openstack network trunk unset --subport port2 trunk0

# Cannot delete ports used as parent or subports. Delete the trunk first.
# Error expected: FIXME HttpException: Conflict
openstack port delete port0
# Error expected: FIXME HttpException: Conflict
openstack port delete port1

# Clean up.
openstack server delete vm0
openstack network trunk delete trunk0
openstack port delete port2 port1 port0
openstack network delete net2 net1 net0

Inherit the provider network's segmentation details

When the switch is incapable of remapping (tag pop-push) you may want to expose the provider network's segmentation details (think of Ironic): 

openstack network create net0 --provider-network-type vlan --provider-physical-network test --provider-segment 100
openstack network create net1 --provider-network-type vlan --provider-physical-network test --provider-segment 101
openstack subnet create subnet0 --network net0 --subnet-range 10.0.4.0/24
openstack subnet create subnet1 --network net1 --subnet-range 10.0.5.0/24
openstack port create port0 --network net0
openstack port create port1 --network net1
openstack network trunk create trunk0 --parent-port port0
openstack network trunk set trunk0 --subport port=port1,segmentation-type=inherit
openstack network subport list --trunk itrunk0 -f value -c 'Segmentation ID' # prints 101


Drawings

  • legacy model of attaching many networks

  • trunk model of attaching many networks

  • legacy API

  • trunk API

  • example of trunk Open vSwitch model

Screenshots

  • Horizon screenshot: Project/Network/Trunks panel

  • Horizon screenshot: Trunk detail

  • Horizon screenshot: Subport(s) selector step of create workflow

Performance / Scaling

Links

  • tests
    • repo openstack/neutron
      • neutron/tests/unit/services/trunk/
      • neutron/tests/functional/services/trunk/
      • neutron/tests/fullstack/test_trunk.py
      • neutron/tests/tempest/scenario/test_trunk.py
      • neutron/tests/tempest/api/test_trunk.py
      • neutron/tests/tempest/api/test_trunk_negative.py
      • neutron/tests/tempest/api/test_trunk_details.py
      • rally-jobs/plugins/trunk_scenario.py
    • repo openstack/heat
      • heat/tests/openstack/neutron/test_neutron_trunk.py
      • heat_integrationtests/functional/test_create_update_neutron_trunk.py
    • repo openstack/horizon
      • openstack_dashboard/static/app/core/trunks/**/*.spec.js
      • openstack_dashboard/test/api_tests/neutron_*.py
Retrieved from "https://wiki.openstack.org/w/index.php?title=Neutron/TrunkPort&oldid=172404"