Neutron/TrunkPort

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
 * since Pike: in Heat
 * since Queens: in Horizon

Introduction

 * Introductory Presentation from the Sydney Summit, 2017 November
 * video (youtube.com)
 * slides (docs.google.com)
 * Introductory blog post (jimmdenton.com) by James Denton

Documentation

 * OpenStack Networking Guide
 * latest
 * pike
 * ocata
 * Heat
 * template guide
 * example template
 * Design Documents
 * 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

Basic
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
 * 1) Business as usual.

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

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

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

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

openstack network trunk list openstack network trunk show trunk0

openstack network trunk delete trunk0

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
 * 1) A trunk can be created with subports too.

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
 * 1) Use an image with support for vlan interfaces. CirrOS will not cut it.
 * 2) But see also: https://etherpad.openstack.org/p/cirros-respin
 * eg: sudo ip link add ... type vlan ...

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

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

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

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

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

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

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

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

Performance / Scaling

 * A separate wiki page documents some performance and scale measurments of the trunk API by Ericsson.
 * See also this openstack-dev thread about measurements by the QE team of HPE.

Links

 * related development
 * horizon
 * horizon blueprint
 * gerrit topic bp/neutron-trunk-ui
 * heat
 * heat spec
 * gerrit topic bp/support-trunk-port
 * nova
 * gerrit topic bp/expose-vlan-trunking
 * odl
 * openstack/networking-odl
 * 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 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


 * blueprints.launchpad.net
 * neutron: bp/vlan-aware-vms
 * nova: bp/neutron-ovs-bridge-name


 * specs.openstack.org
 * neutron-specs/newton/vlan-aware-vms
 * neutron-specs/mitaka/vlan-aware-vms


 * review.openstack.org
 * neutron-spec
 * v3, v4: neutron-specs/vlan-aware-vms
 * v1, v2: neutron-specs/vlan-aware-vms
 * neutron: project:openstack/neutron topic:bp/vlan-aware-vms
 * nova: topic:bp/neutron-ovs-bridge-name
 * python-neutronclient: project:openstack/python-neutronclient topic:bp/vlan-aware-vms
 * tempest: project:openstack/tempest topic:bp/vlan-aware-vms


 * obsolete blueprints/specs/code/etc.
 * bp/trunk-port
 * nova-specs/mitaka/trunk-port
 * neutron-specs/liberty/vlan-aware-vms
 * nova-specs/trunk-port
 * project:openstack/nova topic:bp/trunk-port
 * project:openstack/python-novaclient topic:bp/trunk-port
 * break down of work items: v2 (etherpad.openstack.org)
 * open design questions (etherpad.openstack.org)
 * log of design decisions (etherpad.openstack.org)


 * Mitaka Summit, Tokyo, 2015-10
 * etherpad of the trunk port contributors' meetup
 * vBrownBag session
 * slides (slideshare.net)
 * video (youtube.com)


 * meeting etherpads
 * irc meet @ 2015-11-18 00:00 (utc)
 * agenda
 * meeting log
 * etherpad of the trunk port contributors' meetup


 * unsorted etherpads
 * v4 backlog
 * vlan@tap experiment
 * trunk bridge experiment
 * trunk bridge with ovs firewall driver experiment