Merge "Update installation documentation"

This commit is contained in:
Jenkins 2017-06-16 18:42:53 +00:00 committed by Gerrit Code Review
commit 8317fa2a64
9 changed files with 288 additions and 176 deletions

View File

@ -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. <https://wiki.openstack.org/wiki/Neutron/TrunkPort>`_
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 = <UNDERCLOUD_DEFAULT_SG_UUID>
pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
- Configure worker VMs subnet::
[pod_vif_nested]
worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
- 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 = <VM interface name eg. eth0>
- 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 = <UNDERCLOUD_DEFAULT_SG_UUID>
pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
- Configure worker VMs subnet::
[pod_vif_nested]
worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
- Configure “pod_vif_driver” as “nested-macvlan”::
[kubernetes]
pod_vif_driver = nested-macvlan
- Configure binding section::
[binding]
link_iface = <VM interface name eg. eth0>
- 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 = <absolute file path eg. /etc/kubernetes/admin.crt>
ssl_client_key_file = <absolute file path eg. /etc/kubernetes/admin.key>
If server ssl certification verification is also to be enabled, add absolute path to the ca cert::
[kubernetes]
ssl_ca_crt_file = <absolute file path eg. /etc/kubernetes/ca.crt>
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 <https://wiki.openstack.org/wiki/Kuryr#Kuryr_Policies>`_

View File

@ -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'
]

View File

@ -12,7 +12,7 @@ Contents:
:maxdepth: 2
readme
installation
installation/index
usage
contributing

View File

@ -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

View File

@ -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 = <absolute file path eg. /etc/kubernetes/admin.crt>
ssl_client_key_file = <absolute file path eg. /etc/kubernetes/admin.key>
If server ssl certification verification is also to be enabled, add absolute
path to the ca cert::
[kubernetes]
ssl_ca_crt_file = <absolute file path eg. /etc/kubernetes/ca.crt>
ssl_verify_server_crt = True
If want to query HTTPS K8S api server with ``--insecure`` mode::
[kubernetes]
ssl_verify_server_crt = False

View File

@ -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

View File

@ -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'

View File

@ -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 = <UNDERCLOUD_DEFAULT_SG_UUID>
pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
- Configure worker VMs subnet::
[pod_vif_nested]
worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
- Configure "pod_vif_driver" as "nested-macvlan"::
[kubernetes]
pod_vif_driver = nested-macvlan
- Configure binding section::
[binding]
link_iface = <VM interface name eg. eth0>
- Restart kuryr-k8s-controller::
sudo systemctl restart devstack@kuryr-kubernetes.service
Now launch pods using kubectl, Undercloud Neutron will serve the networking.

View File

@ -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. <https://wiki.openstack.org/wiki/Neutron/TrunkPort>`_
.. 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 = <UNDERCLOUD_DEFAULT_SG_UUID>
pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
- Configure worker VMs subnet::
[pod_vif_nested]
worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
- 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 = <VM interface name eg. eth0>
- Restart kuryr-k8s-controller::
sudo systemctl restart devstack@kuryr-kubernetes.service
Now launch pods using kubectl, Undercloud Neutron will serve the networking.