Merge "Update installation documentation"
This commit is contained in:
commit
8317fa2a64
165
README.rst
165
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. <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>`_
|
||||
|
@ -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'
|
||||
]
|
||||
|
@ -12,7 +12,7 @@ Contents:
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
installation
|
||||
installation/index
|
||||
usage
|
||||
contributing
|
||||
|
||||
|
@ -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
|
23
doc/source/installation/https_kubernetes.rst
Normal file
23
doc/source/installation/https_kubernetes.rst
Normal 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
|
||||
|
34
doc/source/installation/index.rst
Normal file
34
doc/source/installation/index.rst
Normal 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
|
114
doc/source/installation/manual.rst
Normal file
114
doc/source/installation/manual.rst
Normal 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'
|
51
doc/source/installation/nested-macvlan.rst
Normal file
51
doc/source/installation/nested-macvlan.rst
Normal 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.
|
||||
|
62
doc/source/installation/nested-vlan.rst
Normal file
62
doc/source/installation/nested-vlan.rst
Normal 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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user