Merge pull request #7468 from tomassedovic/kuryr-docs

Automatic merge from submit-queue.

Add Kuryr documentation

This provides a more detailed explanation of what Kuryr is and how to
set it up.

Fixes #7385

playbooks/openstack/README.md

@@ -148,6 +148,7 @@ additional options. These include:
 * Set Up Authentication (TODO)
 * [Multiple Masters with a load balancer][loadbalancer]
 * [External DNS][external-dns]
+* [Kuryr SDN][kuryr-sdn]
 * Multiple Clusters (TODO)
 * [Cinder Registry][cinder-registry]
 
@@ -238,3 +239,4 @@ $ ansible-playbook --user openshift \
 [log-in-using-the-command-line]: ./post-install.md#log-in-using-the-command-line
 [access-the-ui]: ./post-install.md#access-the-ui
 [dynamic]: http://docs.ansible.com/ansible/latest/intro_dynamic_inventory.html
+[kuryr-sdn]: ./configuration.md#kuryr-networking-configuration

playbooks/openstack/configuration.md

@@ -171,17 +171,106 @@ another external DNS server.
 
 ## Kuryr Networking Configuration
 
-If you opt to use Kuryr for networking, make sure that you review all
-the Kuryr options. The following parameters should be uncommented in
-`inventory/group_vars/all.yml`:
+Kuryr is an SDN that uses OpenStack Neutron. This prevents the double overlay
+overhead one would get when running OpenShift on OpenStack using the default
+OpenShift SDN.
+
+https://docs.openstack.org/kuryr-kubernetes/latest/readme.html
+
+### OpenStack Requirements
+
+Kuryr has a few additional requirements on the underlying OpenStack deployment:
+
+* The Trunk Ports extension must be enabled:
+  * https://docs.openstack.org/neutron/pike/admin/config-trunking.html
+  * Make sure to restart `neutron-server` after you change the configuration
+* Neutron must use the Open vSwitch firewall driver:
+  * https://docs.openstack.org/neutron/pike/admin/config-ovsfwdriver.html
+  * Make sure to restart `neutron-openvswitch-agent` after the config change
+* A Load Balancer as a Service (implementing LBaaS v2 API) must be available
+  * Octavia is the only supported solution right now
+  * You could try the native Neutron LBaaSv2 but it is deprecated and buggy
+
+We recommend you use the Queens or newer release of OpenStack.
+
+
+### Necessary Kuryr Options
+
+This is is the minimum you need to set (in `group_vars/all.yml`):
+
+```yaml
+openshift_use_kuryr: true
+openshift_use_openshift_sdn: false
+os_sdn_network_plugin_name: cni
+openshift_node_proxy_mode: userspace
+openshift_hosted_manage_registry: false
+use_trunk_ports: true
+
+openshift_master_open_ports:
+- service: dns tcp
+  port: 53/tcp
+- service: dns udp
+  port: 53/udp
+openshift_node_open_ports:
+- service: dns tcp
+  port: 53/tcp
+- service: dns udp
+  port: 53/udp
+
+kuryr_openstack_public_subnet_id: <public/external subnet UUID>
+```
+
+The `kuryr_openstack_public_subnet_id` value must be set to the UUID of the
+public subnet in your OpenStack. In other words, the subnet with the Floating
+IP range defined. It corresponds to the public network, which is often called
+`public`, `external` or `ext-net`.
+
+**NOTE**: A lot of OpenStack deployments do not make the public subnet
+accessible to regular users. We will add an option to enter the network here
+instead. This issue is tracked at:
+
+https://github.com/openshift/openshift-ansible/issues/7383
+
+### Port pooling
+
+It is possible to pre-create Neutron ports for later use. This means that
+several ports (each port will be attached to an OpenShift pod) would be created
+at once. This will speed up individual pod creation at the cost of having a few
+extra ports that are not currently in use.
+
+For more information on the Kuryr port pools, check out the Kuryr
+documentation:
+
+https://docs.openstack.org/kuryr-kubernetes/latest/installation/ports-pool.html
+
+To enable this feature, you must set:
+
+```yaml
+kuryr_openstack_enable_pools: true
+```
+
+You can control the port pooling characteristics with these options:
+
+```yaml
+kuryr_openstack_pool_max: 0
+kuryr_openstack_pool_min: 1
+kuryr_openstack_pool_batch: 5
+kuryr_openstack_pool_update_frequency: 20
+```
+
+### Deploying OpenShift Registry
+
+Since we've disabled the OpenShift registry creation, you will have to create
+it manually afterwards. SSH to a master node and run this as root:
+
+```yaml
+oadm registry --config=/etc/origin/master/admin.kubeconfig --service-account=registry
+```
+
+For more information (e.g. how to use a specific storage backend), please
+follow the OpenShift documentation on the registry:
 
-* `openshift_use_kuryr`
-* `use_trunk_ports`
-* `openshift_use_openshift_sdn`
-* `os_sdn_network_plugin_name`
-* `openshift_node_proxy_mode`
-* `openshift_hosted_manage_registry`
-* `kuryr_openstack_public_subnet_id` Set to uuid of the public subnet.
+https://docs.openshift.org/latest/install_config/registry/index.html
 
 And if you also want to enable the ports pooling options, as well as
 preloading them, you should uncomment and set the next: