Add documentation about subports management for kuryr

It adds documentation about trunk ports and subports management
for OpenShift deployments on top of OpenStack VMs with kuryr. It
describes how trunks, parent ports and subports are created and
how can they be deleted. Additionally, it describes how we can add
manually created Neutron ports to specific pools (kuryr option to
speed up containers boot up time)

playbooks/openstack/post-install.md

@@ -5,6 +5,7 @@
 * [Log in Using the Command Line](#log-in-using-the-command-line)
 * [Access the UI](#access-the-ui)
 * [Run Custom Post-Provision Actions](#run-custom-post-provision-actions)
+* [Manage Trunk ports and subports](#manage-trunk-ports-and-subports)
 
 
 ## Configure DNS
@@ -219,3 +220,114 @@ A library of custom post-provision actions exists in `openshift-ansible-contrib/
 
 
 [external-dns]: ./configuration.md#dns-configuration
+
+## Manage Trunk ports and subports
+
+Running OpenShift on top of OpenStack VMs without the problem of double
+encapsulation is achieved by using kuryr which leverages Neutron Trunk Ports
+feature.
+
+With the Trunk Ports (also known as VLAN aware VMs), we can create a trunk,
+associate a parent port for it that will be used by the VM (in our case, the
+master, infra and app-node VMs), and then we can create a normal Neutron port
+and attach it to the trunk to become a subport of it. These subports are later
+used by the pods running inside those VMs to connect to the Neutron networks.
+
+Next we show a few example of how to manage trunks, parents and subports.
+
+#### Create a Trunk port
+
+```
+# Create a Neutron port
+openstack port create --network VM_NETWORK parent-port-0
+# Create a trunk with that port as parent port
+openstack network trunk create --parent-port parent-port-0 trunk-0
+```
+
+Note you need to first create the port, then the trunk with that port, and only
+then you can create the VM by using the parent port created, in the example
+above parent-port-0.
+
+#### Attach subports to the trunk
+
+```
+# Create a Neutron port
+openstack port create --network POD_NETWORK subport-0
+# Attach the port as a subport of the trunk
+openstack network trunk set --subport port=subport-0,segmentation-type=vlan,segmentation-id=101 trunk-0
+```
+
+#### Remove subports
+
+In order to remove the subports Neutron ports, you need to first detach them
+from the trunk, and then delete them:
+
+```
+# Detach subport from trunk
+openstack network trunk unset --subport subport-0 trunk-0
+# Remove port (as usual)
+openstack port delete subport-0
+```
+
+#### Create subports for the Kuryr Ports Pools
+
+Kuryr Ports Pool is a feature to speed up containers boot up time by reducing
+the number of interactions between Kuryr-controller and Neutron API -- which in
+turn reduces the load on the Neutron server, also improving the overall
+performance. To achieve this, the Kuryr-controller maintains a pool of neutron
+ports ready to be used -- instead of creating a port/subport upon pod creation.
+For the nested case where pods will be created inside an OpenShift cluster
+installed on top of OpenStack VMs, there will be several pools, one for each
+pair of:
+- Trunk port (i.e., VM belonging to OpenShift cluster)
+- Set of security groups used by the pods
+- Neutron Network used by the pods
+- Project ID used to create the pods (i.e., OpenStack tenant)
+
+Note, default kuryr drivers creates all the pods with the same security groups
+set, subnets and project. Thus, in practice there is a pool per trunk port,
+i.e., per VM belonging to the OpenShift cluster.
+
+In order to manually populate one specific pool, the next can be done:
+
+```
+# Create port with the right project_id, security group set and network
+openstack port create --network POD_NETWORK --security-group SG_1
+--security-group SG_2 subport-1
+# Attach the subport to the trunk where you want to add the port to the pool
+openstack network trunk set --subport port=subport-1,segmentation-type=vlan,segmentation-id=1 APP_NODE_VM_TRUNK
+```
+
+Note you need to choose a segmentation id that is not already in use at that
+trunk. To see the current subports attached to that trunk, and their associated
+segmentation ids, you can do:
+
+```
+openstack network trunk show APP_NODE_VM_TRUNK
++-----------------+--------------------------------------------------------------------------------------------------+
+| Field           | Value                                                                                            |
++-----------------+--------------------------------------------------------------------------------------------------+
+| admin_state_up  | UP                                                                                               |
+| created_at      | 2018-03-28T15:06:54Z                                                                             |
+| description     |                                                                                                  |
+| id              | 9048c109-c1aa-4a41-9508-71b2ba98f3b0                                                             |
+| name            | APP_NODE_VM_TRUNK                                                                                |
+| port_id         | 4180a2e5-e184-424a-93d4-54b48490f50d                                                             |
+| project_id      | a05f6ec0abd04cba80cd160f8baaac99                                                                 |
+| revision_number | 43                                                                                               |
+| status          | ACTIVE                                                                                           |
+| sub_ports       | port_id='1de77073-7127-4c39-a47b-cef15f98849c', segmentation_id='101', segmentation_type='vlan'  |
+| tags            | []                                                                                               |
+| tenant_id       | a05f6ec0abd04cba80cd160f8baaac99                                                                 |
+| updated_at      | 2018-03-29T06:12:39Z                                                                             |
++-----------------+--------------------------------------------------------------------------------------------------+
+```
+
+Finally, next time the kuryr-controller pod gets restarted it will recover the
+subports attached to each trunk, and add them to their respective pools -- if
+they are not in used by a pod already. This can also be forced by manually
+restarting the kuryr-controller by killing the running pod:
+
+```
+kubectl -n openshift-infra delete pod kuryr-controller-XXXXX
+```