summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJenkins <jenkins@review.openstack.org>2017-06-16 18:42:53 +0000
committerGerrit Code Review <review@openstack.org>2017-06-16 18:42:53 +0000
commit8317fa2a64660678ff9eb46011b4e86a5bb4dff8 (patch)
tree2a8b40c30c83d5b48d0677a30af64993a6909063
parent976d7af0a8655850baa1d21336dcf60aad11288b (diff)
parentf50e2140f9b1e067d7efd50977ff0e9e7769fdc8 (diff)
Merge "Update installation documentation"
-rw-r--r--README.rst165
-rwxr-xr-xdoc/source/conf.py1
-rw-r--r--doc/source/index.rst2
-rw-r--r--doc/source/installation.rst12
-rw-r--r--doc/source/installation/https_kubernetes.rst23
-rw-r--r--doc/source/installation/index.rst34
-rw-r--r--doc/source/installation/manual.rst114
-rw-r--r--doc/source/installation/nested-macvlan.rst51
-rw-r--r--doc/source/installation/nested-vlan.rst62
9 files changed, 288 insertions, 176 deletions
diff --git a/README.rst b/README.rst
index 3013937..f7ecf7a 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,3 @@
1========================
2Team and repository tags 1Team and repository tags
3======================== 2========================
4 3
@@ -7,9 +6,8 @@ Team and repository tags
7 6
8.. Change things from this point on 7.. Change things from this point on
9 8
10=============================== 9Project description
11kuryr-kubernetes 10===================
12===============================
13 11
14Kubernetes integration with OpenStack networking 12Kubernetes integration with OpenStack networking
15 13
@@ -25,165 +23,6 @@ require it or to use different segments and, for example, route between them.
25* Overview and demo: http://superuser.openstack.org/articles/networking-kubernetes-kuryr 23* Overview and demo: http://superuser.openstack.org/articles/networking-kubernetes-kuryr
26 24
27 25
28Configuring Kuryr
29~~~~~~~~~~~~~~~~~
30
31Generate sample config, `etc/kuryr.conf.sample`, running the following::
32
33 $ ./tools/generate_config_file_samples.sh
34
35
36Rename and copy config file at required path::
37
38 $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf
39
40
41Edit Neutron section in `/etc/kuryr/kuryr.conf`, replace ADMIN_PASSWORD::
42
43 [neutron]
44 auth_url = http://127.0.0.1:35357/v3/
45 username = admin
46 user_domain_name = Default
47 password = ADMIN_PASSWORD
48 project_name = service
49 project_domain_name = Default
50 auth_type = password
51
52
53In the same file uncomment the `bindir` parameter with the path to the Kuryr
54vif binding executables. For example, if you installed it on Debian or Ubuntu::
55
56 [DEFAULT]
57 bindir = /usr/local/libexec/kuryr
58
59
60How to try out nested-pods locally (VLAN + trunk)
61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63Following are the instructions for an all-in-one setup where K8s will also be
64running inside the same Nova VM in which Kuryr-controller and Kuryr-cni will be
65running. 4GB memory and 2 vCPUs, is the minimum resource requirement for the VM:
66
671. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``.
68 Ensure that "trunk" service plugin is enabled in ``/etc/neutron/neutron.conf``::
69
70 [DEFAULT]
71 service_plugins = neutron.services.l3_router.l3_router_plugin.L3RouterPlugin,neutron.services.trunk.plugin.TrunkPlugin
72
732. Launch a VM with `Neutron trunk port. <https://wiki.openstack.org/wiki/Neutron/TrunkPort>`_
743. Inside VM, install and setup Kubernetes along with Kuryr using devstack:
75 - Since undercloud Neutron will be used by pods, Neutron services should be
76 disabled in localrc.
77 - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``.
78 With this config devstack will not configure Neutron resources for the
79 local cloud. These variables have to be added manually
80 to ``/etc/kuryr/kuryr.conf``.
814. Once devstack is done and all services are up inside VM:
82 - Configure ``/etc/kuryr/kuryr.conf`` to set UUID of Neutron resources from undercloud Neutron::
83
84 [neutron_defaults]
85 ovs_bridge = br-int
86 pod_security_groups = <UNDERCLOUD_DEFAULT_SG_UUID>
87 pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
88 project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
89 service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
90
91 - Configure worker VMs subnet::
92
93 [pod_vif_nested]
94 worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
95
96 - Configure “pod_vif_driver” as “nested-vlan”::
97
98 [kubernetes]
99 pod_vif_driver = nested-vlan
100
101 - Configure binding section::
102
103 [binding]
104 driver = kuryr.lib.binding.drivers.vlan
105 link_iface = <VM interface name eg. eth0>
106
107 - Restart kuryr-k8s-controller::
108
109 sudo systemctl restart devstack@kuryr-kubernetes.service
110
111Now launch pods using kubectl, Undercloud Neutron will serve the networking.
112
113How to try out nested-pods locally (MACVLAN)
114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116Following are the instructions for an all-in-one setup, as above, but using the
117nested MACVLAN driver rather than VLAN and trunk ports.
118
1191. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``.
1202. Launch a Nova VM with MACVLAN support
1213. Log into the VM and set up Kubernetes along with Kuryr using devstack:
122 - Since undercloud Neutron will be used by pods, Neutron services should be
123 disabled in localrc.
124 - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``.
125 With this config devstack will not configure Neutron resources for the
126 local cloud. These variables have to be added manually
127 to ``/etc/kuryr/kuryr.conf``.
128
1294. Once devstack is done and all services are up inside VM:
130 - Configure ``/etc/kuryr/kuryr.conf`` with the following content, replacing
131 the values with correct UUIDs of Neutron resources from the undercloud::
132
133 [neutron_defaults]
134 pod_security_groups = <UNDERCLOUD_DEFAULT_SG_UUID>
135 pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
136 project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
137 service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
138
139 - Configure worker VMs subnet::
140
141 [pod_vif_nested]
142 worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
143
144 - Configure “pod_vif_driver” as “nested-macvlan”::
145
146 [kubernetes]
147 pod_vif_driver = nested-macvlan
148
149 - Configure binding section::
150
151 [binding]
152 link_iface = <VM interface name eg. eth0>
153
154 - Restart kuryr-k8s-controller::
155
156 sudo systemctl restart devstack@kuryr-kubernetes.service
157
158Now launch pods using kubectl, Undercloud Neutron will serve the networking.
159
160How to watch K8S api-server over HTTPS
161~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162
163Add absolute path of client side cert file and key file for K8S server in kuryr.conf::
164
165 [kubernetes]
166 api_root = https://your_server_address:server_ssl_port
167 ssl_client_crt_file = <absolute file path eg. /etc/kubernetes/admin.crt>
168 ssl_client_key_file = <absolute file path eg. /etc/kubernetes/admin.key>
169
170If server ssl certification verification is also to be enabled, add absolute path to the ca cert::
171
172 [kubernetes]
173 ssl_ca_crt_file = <absolute file path eg. /etc/kubernetes/ca.crt>
174 ssl_verify_server_crt = True
175
176If want to query HTTPS K8S api server with "--insecure" mode::
177
178 [kubernetes]
179 ssl_verify_server_crt = False
180
181
182Features
183--------
184
185* TODO
186
187Contribution guidelines 26Contribution guidelines
188----------------------- 27-----------------------
189For the process of new feature addition, refer to the `Kuryr Policy <https://wiki.openstack.org/wiki/Kuryr#Kuryr_Policies>`_ 28For the process of new feature addition, refer to the `Kuryr Policy <https://wiki.openstack.org/wiki/Kuryr#Kuryr_Policies>`_
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f483aa0..4b34ec4 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
22# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 22# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
23extensions = [ 23extensions = [
24 'sphinx.ext.autodoc', 24 'sphinx.ext.autodoc',
25 'sphinx.ext.todo',
25 #'sphinx.ext.intersphinx', 26 #'sphinx.ext.intersphinx',
26 'oslosphinx' 27 'oslosphinx'
27] 28]
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2b201d1..bc62709 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,7 +12,7 @@ Contents:
12 :maxdepth: 2 12 :maxdepth: 2
13 13
14 readme 14 readme
15 installation 15 installation/index
16 usage 16 usage
17 contributing 17 contributing
18 18
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
deleted file mode 100644
index e8e65eb..0000000
--- a/doc/source/installation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
1============
2Installation
3============
4
5At the command line::
6
7 $ pip install kuryr-kubernetes
8
9Or, if you have virtualenvwrapper installed::
10
11 $ mkvirtualenv kuryr-kubernetes
12 $ 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 0000000..4c484b6
--- /dev/null
+++ b/doc/source/installation/https_kubernetes.rst
@@ -0,0 +1,23 @@
1Watching K8S api-server over HTTPS
2==================================
3
4Add absolute path of client side cert file and key file for K8S server
5in ``kuryr.conf``::
6
7 [kubernetes]
8 api_root = https://your_server_address:server_ssl_port
9 ssl_client_crt_file = <absolute file path eg. /etc/kubernetes/admin.crt>
10 ssl_client_key_file = <absolute file path eg. /etc/kubernetes/admin.key>
11
12If server ssl certification verification is also to be enabled, add absolute
13path to the ca cert::
14
15 [kubernetes]
16 ssl_ca_crt_file = <absolute file path eg. /etc/kubernetes/ca.crt>
17 ssl_verify_server_crt = True
18
19If want to query HTTPS K8S api server with ``--insecure`` mode::
20
21 [kubernetes]
22 ssl_verify_server_crt = False
23
diff --git a/doc/source/installation/index.rst b/doc/source/installation/index.rst
new file mode 100644
index 0000000..7f2a15c
--- /dev/null
+++ b/doc/source/installation/index.rst
@@ -0,0 +1,34 @@
1..
2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
5
6 http://www.apache.org/licenses/LICENSE-2.0
7
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
12 under the License.
13
14 Convention for heading levels in Neutron devref:
15 ======= Heading 0 (reserved for the title in a document)
16 ------- Heading 1
17 ~~~~~~~ Heading 2
18 +++++++ Heading 3
19 ''''''' Heading 4
20 (Avoid deeper levels because they do not render well.)
21
22
23Installation
24============
25
26This section describes how you can install and configure kuryr-kubernetes
27
28.. toctree::
29 :maxdepth: 2
30
31 manual
32 nested-vlan
33 nested-macvlan
34 https_kubernetes
diff --git a/doc/source/installation/manual.rst b/doc/source/installation/manual.rst
new file mode 100644
index 0000000..f62729a
--- /dev/null
+++ b/doc/source/installation/manual.rst
@@ -0,0 +1,114 @@
1Installing kuryr-kubernetes manually
2====================================
3
4Configure kuryr-k8s-controller
5------------------------------
6
7Install ``kuryr-k8s-controller`` in a virtualenv::
8
9 $ mkdir kuryr-k8s-controller
10 $ cd kuryr-k8s-controller
11 $ virtualenv env
12 $ git clone http://git.openstack.org/openstack/kuryr-kubernetes
13 $ . env/bin/activate
14 $ pip install -e kuryr-kubernetes
15
16
17In neutron or in horizon create subnet for pods, subnet for services and a
18security-group for pods. You may use existing if you like.
19
20.. todo::
21 Add reference neutron cli commands
22
23Create ``/etc/kuryr/kuryr.conf``::
24
25 $ cd kuryr-kubernetes
26 $ ./tools/generate_config_file_samples.sh
27 $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf
28
29Edit ``kuryr.conf``::
30
31 [DEFAULT]
32 use_stderr = true
33 bindir = {path_to_env}/libexec/kuryr
34
35 [kubernetes]
36 api_root = http://{ip_of_kubernetes_apiserver}:8080
37
38 [neutron]
39 auth_url = http://127.0.0.1:35357/v3/
40 username = admin
41 user_domain_name = Default
42 password = ADMIN_PASSWORD
43 project_name = service
44 project_domain_name = Default
45 auth_type = password
46
47 [neutron_defaults]
48 ovs_bridge = br-int
49 pod_security_groups = {id_of_secuirity_group_for_pods}
50 pod_subnet = {id_of_subnet_for_pods}
51 project = {id_of_project}
52 service_subnet = {id_of_subnet_for_k8s_services}
53
54Run kuryr-k8s-controller::
55
56 $ kuryr-k8s-controller --config-file /etc/kuryr/kuryr.conf -d
57
58Alternatively you may run it in screen::
59
60 $ screen -dm kuryr-k8s-controller --config-file /etc/kuryr/kuryr.conf -d
61
62Configure kuryr-cni
63-------------------
64
65On every kubernetes minion node (and on master if you intend to run containers
66there) you need to configure kuryr-cni.
67
68Install ``kuryr-cni`` a virtualenv::
69
70 $ mkdir kuryr-k8s-cni
71 $ cd kuryr-k8s-cni
72 $ virtualenv env
73 $ . env/bin/activate
74 $ git clone http://git.openstack.org/openstack/kuryr-kubernetes
75 $ pip install -e kuryr-kubernetes
76
77Create ``/etc/kuryr/kuryr.conf``::
78
79 $ cd kuryr-kubernetes
80 $ ./tools/generate_config_file_samples.sh
81 $ cp etc/kuryr.conf.sample /etc/kuryr/kuryr.conf
82
83Edit ``kuryr.conf``::
84
85 [DEFAULT]
86 use_stderr = true
87 bindir = /path/to/env/libexec/kuryr
88 [kubernetes]
89 api_root = http://{ip_of_kubernetes_apiserver}:8080
90
91Link the CNI binary to CNI directory, where kubelet would find it::
92
93 $ mkdir -p /opt/cni/bin
94 $ ln -s $(which kuryr-cni) /opt/cni/bin/
95
96Create the CNI config file for kuryr-cni: ``/etc/cni/net.d/10-kuryr.conf``.
97Kubelet would only use the lexicographically first file in that direcotory, so
98make sure that it is kuryr's config file::
99
100 {
101 "cniVersion": "0.3.0",
102 "name": "kuryr",
103 "type": "kuryr-cni",
104 "kuryr_conf": "/etc/kuryr/kuryr.conf",
105 "debug": true
106 }
107
108Install ``os-vif`` and ``oslo.privsep`` libraries globally. These modules
109are used to plug interfaces and would be run with raised privileges. ``os-vif``
110uses ``sudo`` to raise privileges, and they would need to be installed globally
111to work correctly::
112
113 deactivate
114 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 0000000..65cbd66
--- /dev/null
+++ b/doc/source/installation/nested-macvlan.rst
@@ -0,0 +1,51 @@
1How to try out nested-pods locally (MACVLAN)
2============================================
3
4Following are the instructions for an all-in-one setup, using the
5nested MACVLAN driver rather than VLAN and trunk ports.
6
71. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``.
82. Launch a Nova VM with MACVLAN support
9
10.. todo::
11 Add a list of neutron commands, required to launch a such a VM
12
133. Log into the VM and set up Kubernetes along with Kuryr using devstack:
14 - Since undercloud Neutron will be used by pods, Neutron services should be
15 disabled in localrc.
16 - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``.
17 With this config devstack will not configure Neutron resources for the
18 local cloud. These variables have to be added manually
19 to ``/etc/kuryr/kuryr.conf``.
20
214. Once devstack is done and all services are up inside VM:
22 - Configure ``/etc/kuryr/kuryr.conf`` with the following content, replacing
23 the values with correct UUIDs of Neutron resources from the undercloud::
24
25 [neutron_defaults]
26 pod_security_groups = <UNDERCLOUD_DEFAULT_SG_UUID>
27 pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
28 project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
29 service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
30
31 - Configure worker VMs subnet::
32
33 [pod_vif_nested]
34 worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
35
36 - Configure "pod_vif_driver" as "nested-macvlan"::
37
38 [kubernetes]
39 pod_vif_driver = nested-macvlan
40
41 - Configure binding section::
42
43 [binding]
44 link_iface = <VM interface name eg. eth0>
45
46 - Restart kuryr-k8s-controller::
47
48 sudo systemctl restart devstack@kuryr-kubernetes.service
49
50Now launch pods using kubectl, Undercloud Neutron will serve the networking.
51
diff --git a/doc/source/installation/nested-vlan.rst b/doc/source/installation/nested-vlan.rst
new file mode 100644
index 0000000..5623ab7
--- /dev/null
+++ b/doc/source/installation/nested-vlan.rst
@@ -0,0 +1,62 @@
1How to try out nested-pods locally (VLAN + trunk)
2=================================================
3
4Following are the instructions for an all-in-one setup where K8s will also be
5running inside the same Nova VM in which Kuryr-controller and Kuryr-cni will be
6running. 4GB memory and 2 vCPUs, is the minimum resource requirement for the VM:
7
81. To install OpenStack services run devstack with ``devstack/local.conf.pod-in-vm.undercloud.sample``.
9 Ensure that "trunk" service plugin is enabled in ``/etc/neutron/neutron.conf``::
10
11 [DEFAULT]
12 service_plugins = neutron.services.l3_router.l3_router_plugin.L3RouterPlugin,neutron.services.trunk.plugin.TrunkPlugin
13
142. Launch a VM with `Neutron trunk port. <https://wiki.openstack.org/wiki/Neutron/TrunkPort>`_
15
16.. todo::
17 Add a list of neutron commands, required to launch a trunk port
18
193. Inside VM, install and setup Kubernetes along with Kuryr using devstack:
20 - Since undercloud Neutron will be used by pods, Neutron services should be
21 disabled in localrc.
22 - Run devstack with ``devstack/local.conf.pod-in-vm.overcloud.sample``.
23 With this config devstack will not configure Neutron resources for the
24 local cloud. These variables have to be added manually
25 to ``/etc/kuryr/kuryr.conf``.
26
274. Once devstack is done and all services are up inside VM:
28 - Configure ``/etc/kuryr/kuryr.conf`` to set UUID of Neutron resources from undercloud Neutron::
29
30 [neutron_defaults]
31 ovs_bridge = br-int
32 pod_security_groups = <UNDERCLOUD_DEFAULT_SG_UUID>
33 pod_subnet = <UNDERCLOUD_SUBNET_FOR_PODS_UUID>
34 project = <UNDERCLOUD_DEFAULT_PROJECT_UUID>
35 service_subnet = <UNDERCLOUD_SUBNET_FOR_SERVICES_UUID>
36
37 - Configure worker VMs subnet::
38
39 [pod_vif_nested]
40 worker_nodes_subnet = <UNDERCLOUD_SUBNET_WORKER_NODES_UUID>
41
42 - Configure "pod_vif_driver" as "nested-vlan"::
43
44 [kubernetes]
45 pod_vif_driver = nested-vlan
46
47 - Configure binding section::
48
49 [binding]
50 driver = kuryr.lib.binding.drivers.vlan
51 link_iface = <VM interface name eg. eth0>
52
53 - Restart kuryr-k8s-controller::
54
55 sudo systemctl restart devstack@kuryr-kubernetes.service
56
57Now launch pods using kubectl, Undercloud Neutron will serve the networking.
58
59
60
61
62