From f50e2140f9b1e067d7efd50977ff0e9e7769fdc8 Mon Sep 17 00:00:00 2001 From: Kirill Zaitsev Date: Fri, 9 Jun 2017 14:57:17 +0300 Subject: [PATCH] Update installation documentation This commit moves installation/configuration documentation from README file to installation section of the actual docs (which has been rather short thus far). This commit splits a single README into multiple installation sub-docs. It also expands the manual on installation and configuration of kuryr-k8s-controller and kuryr-cni. Change-Id: I88862f28d0bbbd8bf5259209c4fa3c41130479d1 --- README.rst | 165 +------------------ doc/source/conf.py | 1 + doc/source/index.rst | 2 +- doc/source/installation.rst | 12 -- doc/source/installation/https_kubernetes.rst | 23 +++ doc/source/installation/index.rst | 34 ++++ doc/source/installation/manual.rst | 114 +++++++++++++ doc/source/installation/nested-macvlan.rst | 51 ++++++ doc/source/installation/nested-vlan.rst | 62 +++++++ 9 files changed, 288 insertions(+), 176 deletions(-) delete mode 100644 doc/source/installation.rst create mode 100644 doc/source/installation/https_kubernetes.rst create mode 100644 doc/source/installation/index.rst create mode 100644 doc/source/installation/manual.rst create mode 100644 doc/source/installation/nested-macvlan.rst create mode 100644 doc/source/installation/nested-vlan.rst diff --git a/README.rst b/README.rst index ee6b47f39..3bfeb3112 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,3 @@ -======================== Team and repository tags ======================== @@ -7,9 +6,8 @@ Team and repository tags .. Change things from this point on -=============================== -kuryr-kubernetes -=============================== +Project description +=================== Kubernetes integration with OpenStack networking @@ -25,165 +23,6 @@ require it or to use different segments and, for example, route between them. * Overview and demo: http://superuser.openstack.org/articles/networking-kubernetes-kuryr -Configuring Kuryr -~~~~~~~~~~~~~~~~~ - -Generate sample config, `etc/kuryr.conf.sample`, running the following:: - - $ ./tools/generate_config_file_samples.sh - - -Rename and copy config file at required path:: - - $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf - - -Edit Neutron section in `/etc/kuryr/kuryr.conf`, replace ADMIN_PASSWORD:: - - [neutron] - auth_url = http://127.0.0.1:35357/v3/ - username = admin - user_domain_name = Default - password = ADMIN_PASSWORD - project_name = service - project_domain_name = Default - auth_type = password - - -In the same file uncomment the `bindir` parameter with the path to the Kuryr -vif binding executables. For example, if you installed it on Debian or Ubuntu:: - - [DEFAULT] - bindir = /usr/local/libexec/kuryr - - -How to try out nested-pods locally (VLAN + trunk) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Following are the instructions for an all-in-one setup where K8s will also be -running inside the same Nova VM in which Kuryr-controller and Kuryr-cni will be -running. 4GB memory and 2 vCPUs, is the minimum resource requirement for the VM: - -1. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``. - Ensure that "trunk" service plugin is enabled in ``/etc/neutron/neutron.conf``:: - - [DEFAULT] - service_plugins = neutron.services.l3_router.l3_router_plugin.L3RouterPlugin,neutron.services.trunk.plugin.TrunkPlugin - -2. Launch a VM with `Neutron trunk port. `_ -3. Inside VM, install and setup Kubernetes along with Kuryr using devstack: - - Since undercloud Neutron will be used by pods, Neutron services should be - disabled in localrc. - - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``. - With this config devstack will not configure Neutron resources for the - local cloud. These variables have to be added manually - to ``/etc/kuryr/kuryr.conf``. -4. Once devstack is done and all services are up inside VM: - - Configure ``/etc/kuryr/kuryr.conf`` to set UUID of Neutron resources from undercloud Neutron:: - - [neutron_defaults] - ovs_bridge = br-int - pod_security_groups = - pod_subnet = - project = - service_subnet = - - - Configure worker VMs subnet:: - - [pod_vif_nested] - worker_nodes_subnet = - - - Configure “pod_vif_driver” as “nested-vlan”:: - - [kubernetes] - pod_vif_driver = nested-vlan - - - Configure binding section:: - - [binding] - driver = kuryr.lib.binding.drivers.vlan - link_iface = - - - Restart kuryr-k8s-controller:: - - sudo systemctl restart devstack@kuryr-kubernetes.service - -Now launch pods using kubectl, Undercloud Neutron will serve the networking. - -How to try out nested-pods locally (MACVLAN) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Following are the instructions for an all-in-one setup, as above, but using the -nested MACVLAN driver rather than VLAN and trunk ports. - -1. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``. -2. Launch a Nova VM with MACVLAN support -3. Log into the VM and set up Kubernetes along with Kuryr using devstack: - - Since undercloud Neutron will be used by pods, Neutron services should be - disabled in localrc. - - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``. - With this config devstack will not configure Neutron resources for the - local cloud. These variables have to be added manually - to ``/etc/kuryr/kuryr.conf``. - -4. Once devstack is done and all services are up inside VM: - - Configure ``/etc/kuryr/kuryr.conf`` with the following content, replacing - the values with correct UUIDs of Neutron resources from the undercloud:: - - [neutron_defaults] - pod_security_groups = - pod_subnet = - project = - service_subnet = - - - Configure worker VMs subnet:: - - [pod_vif_nested] - worker_nodes_subnet = - - - Configure “pod_vif_driver” as “nested-macvlan”:: - - [kubernetes] - pod_vif_driver = nested-macvlan - - - Configure binding section:: - - [binding] - link_iface = - - - Restart kuryr-k8s-controller:: - - sudo systemctl restart devstack@kuryr-kubernetes.service - -Now launch pods using kubectl, Undercloud Neutron will serve the networking. - -How to watch K8S api-server over HTTPS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add absolute path of client side cert file and key file for K8S server in kuryr.conf:: - - [kubernetes] - api_root = https://your_server_address:server_ssl_port - ssl_client_crt_file = - ssl_client_key_file = - -If server ssl certification verification is also to be enabled, add absolute path to the ca cert:: - - [kubernetes] - ssl_ca_crt_file = - ssl_verify_server_crt = True - -If want to query HTTPS K8S api server with "--insecure" mode:: - - [kubernetes] - ssl_verify_server_crt = False - - -Features --------- - -* TODO - Contribution guidelines ----------------------- For the process of new feature addition, refer to the `Kuryr Policy `_ diff --git a/doc/source/conf.py b/doc/source/conf.py index f483aa01e..4b34ec424 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.todo', #'sphinx.ext.intersphinx', 'oslosphinx' ] diff --git a/doc/source/index.rst b/doc/source/index.rst index 2b201d160..bc627096c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,7 +12,7 @@ Contents: :maxdepth: 2 readme - installation + installation/index usage contributing diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index e8e65eb3e..000000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,12 +0,0 @@ -============ -Installation -============ - -At the command line:: - - $ pip install kuryr-kubernetes - -Or, if you have virtualenvwrapper installed:: - - $ mkvirtualenv kuryr-kubernetes - $ pip install kuryr-kubernetes diff --git a/doc/source/installation/https_kubernetes.rst b/doc/source/installation/https_kubernetes.rst new file mode 100644 index 000000000..4c484b634 --- /dev/null +++ b/doc/source/installation/https_kubernetes.rst @@ -0,0 +1,23 @@ +Watching K8S api-server over HTTPS +================================== + +Add absolute path of client side cert file and key file for K8S server +in ``kuryr.conf``:: + + [kubernetes] + api_root = https://your_server_address:server_ssl_port + ssl_client_crt_file = + ssl_client_key_file = + +If server ssl certification verification is also to be enabled, add absolute +path to the ca cert:: + + [kubernetes] + ssl_ca_crt_file = + ssl_verify_server_crt = True + +If want to query HTTPS K8S api server with ``--insecure`` mode:: + + [kubernetes] + ssl_verify_server_crt = False + diff --git a/doc/source/installation/index.rst b/doc/source/installation/index.rst new file mode 100644 index 000000000..7f2a15ce0 --- /dev/null +++ b/doc/source/installation/index.rst @@ -0,0 +1,34 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Neutron devref: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Installation +============ + +This section describes how you can install and configure kuryr-kubernetes + +.. toctree:: + :maxdepth: 2 + + manual + nested-vlan + nested-macvlan + https_kubernetes diff --git a/doc/source/installation/manual.rst b/doc/source/installation/manual.rst new file mode 100644 index 000000000..f62729a49 --- /dev/null +++ b/doc/source/installation/manual.rst @@ -0,0 +1,114 @@ +Installing kuryr-kubernetes manually +==================================== + +Configure kuryr-k8s-controller +------------------------------ + +Install ``kuryr-k8s-controller`` in a virtualenv:: + + $ mkdir kuryr-k8s-controller + $ cd kuryr-k8s-controller + $ virtualenv env + $ git clone http://git.openstack.org/openstack/kuryr-kubernetes + $ . env/bin/activate + $ pip install -e kuryr-kubernetes + + +In neutron or in horizon create subnet for pods, subnet for services and a +security-group for pods. You may use existing if you like. + +.. todo:: + Add reference neutron cli commands + +Create ``/etc/kuryr/kuryr.conf``:: + + $ cd kuryr-kubernetes + $ ./tools/generate_config_file_samples.sh + $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf + +Edit ``kuryr.conf``:: + + [DEFAULT] + use_stderr = true + bindir = {path_to_env}/libexec/kuryr + + [kubernetes] + api_root = http://{ip_of_kubernetes_apiserver}:8080 + + [neutron] + auth_url = http://127.0.0.1:35357/v3/ + username = admin + user_domain_name = Default + password = ADMIN_PASSWORD + project_name = service + project_domain_name = Default + auth_type = password + + [neutron_defaults] + ovs_bridge = br-int + pod_security_groups = {id_of_secuirity_group_for_pods} + pod_subnet = {id_of_subnet_for_pods} + project = {id_of_project} + service_subnet = {id_of_subnet_for_k8s_services} + +Run kuryr-k8s-controller:: + + $ kuryr-k8s-controller --config-file /etc/kuryr/kuryr.conf -d + +Alternatively you may run it in screen:: + + $ screen -dm kuryr-k8s-controller --config-file /etc/kuryr/kuryr.conf -d + +Configure kuryr-cni +------------------- + +On every kubernetes minion node (and on master if you intend to run containers +there) you need to configure kuryr-cni. + +Install ``kuryr-cni`` a virtualenv:: + + $ mkdir kuryr-k8s-cni + $ cd kuryr-k8s-cni + $ virtualenv env + $ . env/bin/activate + $ git clone http://git.openstack.org/openstack/kuryr-kubernetes + $ pip install -e kuryr-kubernetes + +Create ``/etc/kuryr/kuryr.conf``:: + + $ cd kuryr-kubernetes + $ ./tools/generate_config_file_samples.sh + $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf + +Edit ``kuryr.conf``:: + + [DEFAULT] + use_stderr = true + bindir = /path/to/env/libexec/kuryr + [kubernetes] + api_root = http://{ip_of_kubernetes_apiserver}:8080 + +Link the CNI binary to CNI directory, where kubelet would find it:: + + $ mkdir -p /opt/cni/bin + $ ln -s $(which kuryr-cni) /opt/cni/bin/ + +Create the CNI config file for kuryr-cni: ``/etc/cni/net.d/10-kuryr.conf``. +Kubelet would only use the lexicographically first file in that direcotory, so +make sure that it is kuryr's config file:: + + { + "cniVersion": "0.3.0", + "name": "kuryr", + "type": "kuryr-cni", + "kuryr_conf": "/etc/kuryr/kuryr.conf", + "debug": true + } + +Install ``os-vif`` and ``oslo.privsep`` libraries globally. These modules +are used to plug interfaces and would be run with raised privileges. ``os-vif`` +uses ``sudo`` to raise privileges, and they would need to be installed globally +to work correctly:: + + deactivate + sudo pip install 'oslo.privsep>=1.20.0' 'os-vif>=1.5.0' diff --git a/doc/source/installation/nested-macvlan.rst b/doc/source/installation/nested-macvlan.rst new file mode 100644 index 000000000..65cbd66fa --- /dev/null +++ b/doc/source/installation/nested-macvlan.rst @@ -0,0 +1,51 @@ +How to try out nested-pods locally (MACVLAN) +============================================ + +Following are the instructions for an all-in-one setup, using the +nested MACVLAN driver rather than VLAN and trunk ports. + +1. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``. +2. Launch a Nova VM with MACVLAN support + +.. todo:: + Add a list of neutron commands, required to launch a such a VM + +3. Log into the VM and set up Kubernetes along with Kuryr using devstack: + - Since undercloud Neutron will be used by pods, Neutron services should be + disabled in localrc. + - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``. + With this config devstack will not configure Neutron resources for the + local cloud. These variables have to be added manually + to ``/etc/kuryr/kuryr.conf``. + +4. Once devstack is done and all services are up inside VM: + - Configure ``/etc/kuryr/kuryr.conf`` with the following content, replacing + the values with correct UUIDs of Neutron resources from the undercloud:: + + [neutron_defaults] + pod_security_groups = + pod_subnet = + project = + service_subnet = + + - Configure worker VMs subnet:: + + [pod_vif_nested] + worker_nodes_subnet = + + - Configure "pod_vif_driver" as "nested-macvlan":: + + [kubernetes] + pod_vif_driver = nested-macvlan + + - Configure binding section:: + + [binding] + link_iface = + + - Restart kuryr-k8s-controller:: + + sudo systemctl restart devstack@kuryr-kubernetes.service + +Now launch pods using kubectl, Undercloud Neutron will serve the networking. + diff --git a/doc/source/installation/nested-vlan.rst b/doc/source/installation/nested-vlan.rst new file mode 100644 index 000000000..5623ab73b --- /dev/null +++ b/doc/source/installation/nested-vlan.rst @@ -0,0 +1,62 @@ +How to try out nested-pods locally (VLAN + trunk) +================================================= + +Following are the instructions for an all-in-one setup where K8s will also be +running inside the same Nova VM in which Kuryr-controller and Kuryr-cni will be +running. 4GB memory and 2 vCPUs, is the minimum resource requirement for the VM: + +1. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``. + Ensure that "trunk" service plugin is enabled in ``/etc/neutron/neutron.conf``:: + + [DEFAULT] + service_plugins = neutron.services.l3_router.l3_router_plugin.L3RouterPlugin,neutron.services.trunk.plugin.TrunkPlugin + +2. Launch a VM with `Neutron trunk port. `_ + +.. todo:: + Add a list of neutron commands, required to launch a trunk port + +3. Inside VM, install and setup Kubernetes along with Kuryr using devstack: + - Since undercloud Neutron will be used by pods, Neutron services should be + disabled in localrc. + - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``. + With this config devstack will not configure Neutron resources for the + local cloud. These variables have to be added manually + to ``/etc/kuryr/kuryr.conf``. + +4. Once devstack is done and all services are up inside VM: + - Configure ``/etc/kuryr/kuryr.conf`` to set UUID of Neutron resources from undercloud Neutron:: + + [neutron_defaults] + ovs_bridge = br-int + pod_security_groups = + pod_subnet = + project = + service_subnet = + + - Configure worker VMs subnet:: + + [pod_vif_nested] + worker_nodes_subnet = + + - Configure "pod_vif_driver" as "nested-vlan":: + + [kubernetes] + pod_vif_driver = nested-vlan + + - Configure binding section:: + + [binding] + driver = kuryr.lib.binding.drivers.vlan + link_iface = + + - Restart kuryr-k8s-controller:: + + sudo systemctl restart devstack@kuryr-kubernetes.service + +Now launch pods using kubectl, Undercloud Neutron will serve the networking. + + + + +