x/stackube
Code Issues Proposed changes

Update documentation

Browse Source 
Change-Id: Ib135d350d48452fc986ccfcdbfd4f04e4a29b28b
This commit is contained in:
Pengfei Ni 2017-08-03 21:40:31 +08:00
parent 50322401cd
commit 4dd67bf6ab
4 changed files with 224 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/source/architecture.rst
View File

@ -0,0 +1,39 @@
Stackube Architecture
=======================
This page describes the architecture of stackube.
==========
Overview
==========
Stackube is a Kubernetes-centric OpenStack distro. It uses Kubernetes, instead of Nova, as the compute
fabric controller, to provision containers as the compute instance, along with other OpenStack
services (e.g. Cinder, Neutron). It supports multiple container runtime technologies, e.g. Docker,
Hyper, and offers built-in soft/hard multi-tenancy (depending on the container runtime used).
===========
Components
===========
#. Standard OpenStack Compoents
* OpenStack Keytone
* OpenStack Neutron
* OpenStack Cinder
#. Standard Kubernetes Components
* Etcd: the storage of kubernetes.
* Kube-apiserver: the API, authn/authz and admission control of kubernetes.
* Kuber-controller-manager: the brain of kubernetes, ensure the state of kubernetes cluster.
* Kube-scheduler: the scheduler of kubernetes.
* Kubelet: the container lifecycle and volume manager of kubernetes.
* Frakti&HyperContainer: a hypervisor-based container runtime.
* Docker: docker container runtime.
#. Stackube addons
* Stackube-controller: tenant and network manager.
* Stackube-proxy: service discovery and load balancing, replacement of kube-proxy.
* Kubestack: the CNI network plugin, which connects containers to Neutron network.

230
doc/source/developer.rst
View File

@ -1,60 +1,120 @@
Developer Document Deployment Documentation
===================================== =====================================
This page describes how to setup a working development environment that can be used in developing stackube on Ubuntu or CentOS. These instructions assume you're already installed git, golang and python on your host. This page describes how to setup a working development environment that can be used in developing stackube on Ubuntu or
CentOS. These instructions assume you're already installed git, golang and python on your host.
================= =========
Stackube controller
=================
--------
Build Build
-------- =========
Build binary:
:: ::
make build make
The binary will be placed at: The binary will be placed at:
:: ::
_output/kubestack
_output/stackube-controller _output/stackube-controller
_output/stackube-proxy
-------- Build docker images:
Start
--------
:: ::
make docker
Three docker images will be built:
::
stackube/stackube-proxy:v0.1
stackube/stackube-controller:v0.1
stackube/kubestack:v0.1
=========
Start
=========
The following parts suppose you have already deployed an environment of OpenStack and Kubernetes on same baremetal host.
If the cluster is not deployed via devstack, don't forget to setup `--experimental-keystone-url` for kube-apiserver, e.g.
::
kube-apiserver --experimental-keystone-url=https://192.168.128.66:5000/v2.0 ...
Remove kube-dns deployment and kube-proxy daemonset if you have already running them.
::
kubectl -n kube-system delete deployment kube-dns
kubectl -n kube-system delete daemonset kube-proxy
If you have also configured a CNI network plugin, you should also remove it togather with CNI network config.
::
# Remove CNI network components, e.g. deployments or daemonsets first.
# Then remove CNI network config.
rm -f /etc/cni/net.d/*
Then create external network in Neutron if there is no one.
::
# Create an external network if there is no one.
# Please replace 10.123.0.x with your own external network # Please replace 10.123.0.x with your own external network
# and remember the id of your created external network # and remember the id of your created external network
neutron net-create br-ex --router:external=True --shared neutron net-create br-ex --router:external=True --shared
neutron subnet-create --ip_version 4 --gateway 10.123.0.1 br-ex 10.123.0.0/16 --allocation-pool start=10.123.0.2,end=10.123.0.200 --name public-subnet neutron subnet-create --ip_version 4 --gateway 10.123.0.1 br-ex 10.123.0.0/16 --allocation-pool start=10.123.0.2,end=10.123.0.200 --name public-subnet
# Create configure file for Stackube
cat >/etc/stackube.conf <<EOF Now, we are ready to deploy stackube components.
[Global]
auth-url = https://<your-keystone-ip:port>/identity_admin/v2.0 First create configure file for Stackube.
username = admin
password = password ::
tenant-name = admin
region = RegionOne # Remember to replace them with your own ones.
ext-net-id = <id-of-your-external-network> cat >stackube-configmap.yaml <<EOF
kind: ConfigMap
apiVersion: v1
metadata:
name: stackube-config
namespace: kube-system
data:
auth-url: "https://192.168.128.66/identity_admin/v2.0"
username: "admin"
password: "admin"
tenant-name: "admin"
region: "RegionOne"
ext-net-id: "550370a3-4fc2-4494-919d-cae33f5b3de8"
plugin-name: "ovs"
integration-bridge: "br-int"
user-cidr: "10.244.0.0/16"
user-gateway: "10.244.0.1"
kubernetes-host: "192.168.0.33"
kubernetes-port: "6443"
EOF EOF
# Start stackube controller Then deploy stackube components:
./_output/stackube-controller --v=5
::
kubectl create -f stackube-configmap.yaml
kubectl create -f deployment/stackube-proxy.yaml
kubectl create -f deployment/stackube.yaml
=========
--------
Test Test
-------- =========
1. Initialize Neutron 1. Create a new tenant
1. Prepare Tenant and Network
:: ::
@ -68,28 +128,36 @@ Test
username: "test" username: "test"
password: "password" password: "password"
$ kubectl create -f test-tenant.yaml
# for now network should have the same name as namespace (to enforce 1:1 mapping) 2. Check the auto-created namespace and network. Wait a while, the namespace and network for this tenant should be created automatically:
$ cat test-network.yaml
apiVersion: "stackube.kubernetes.io/v1"
kind: Network
metadata:
name: test
namespace: test
spec:
cidr: "192.168.0.0/24"
gateway: "192.168.0.1"
2. Create new Tenant and its Network in Kubernetes
:: ::
$ export KUBECONFIG=/etc/kubernetes/admin.conf $ kubectl get namespace test
$ kubectl create -f ~/test-tenant.yaml NAME STATUS AGE
$ kubectl create -f ~/test-network.yaml test Active 58m
3. Check the Network and Tenant is created in Neutron by Stackube controller $ kubectl -n test get network test -o yaml
apiVersion: stackube.kubernetes.io/v1
kind: Network
metadata:
clusterName: ""
creationTimestamp: 2017-08-03T11:58:31Z
generation: 0
name: test
namespace: test
resourceVersion: "3992023"
selfLink: /apis/stackube.kubernetes.io/v1/namespaces/test/networks/test
uid: 11d452eb-7843-11e7-8319-68b599b7918c
spec:
cidr: 10.244.0.0/16
gateway: 10.244.0.1
networkID: ""
status:
state: Active
3. Check the Network and Tenant created in Neutron by Stackube controller.
:: ::
@ -98,23 +166,77 @@ Test
+--------------------------------------+----------------------+----------------------------------+----------------------------------------------------------+ +--------------------------------------+----------------------+----------------------------------+----------------------------------------------------------+
| id | name | tenant_id | subnets | | id | name | tenant_id | subnets |
+--------------------------------------+----------------------+----------------------------------+----------------------------------------------------------+ +--------------------------------------+----------------------+----------------------------------+----------------------------------------------------------+
| 421d913a-a269-408a-9765-2360e202ad5b | kube_test_test-net | 915b36add7e34018b7241ab63a193530 | bb446a53-de4d-4546-81fc-8736a9a88e3a 192.168.0.0/24 | | 421d913a-a269-408a-9765-2360e202ad5b | kube-test-test | 915b36add7e34018b7241ab63a193530 | bb446a53-de4d-4546-81fc-8736a9a88e3a 10.244.0.0/16 |
4. Check Network object is created in Kubernetes 4. Check the kube-dns pods created in the new namespace.
:: ::
$ kubectl get network test-net --namespace=test # kubectl -n test get pods
NAME KIND NAME READY STATUS RESTARTS AGE
test-net Network.v1.stackube.kubernetes.io kube-dns-1476438210-37jv7 3/3 Running 0 1h
5. Delete the Network from Kubernetes 5. Create pods and services in the new namespace.
:: ::
$ kubectl delete -f test-network.yaml # kubectl -n test run nginx --image=nginx
deployment "nginx" created
# kubectl -n test expose deployment nginx --port=80
service "nginx" exposed
6. Check Network in Neutron is also deleted by Stackube controller # kubectl -n test get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE
kube-dns-1476438210-37jv7 3/3 Running 0 1h 10.244.0.4 stackube
nginx-4217019353-6gjxq 1/1 Running 0 27s 10.244.0.10 stackube
# kubectl -n test run -i -t busybox --image=busybox sh
If you don't see a command prompt, try pressing enter.
/ # nslookup nginx
Server: 10.96.0.10
Address 1: 10.96.0.10
Name: nginx
Address 1: 10.108.57.129 nginx.test.svc.cluster.local
/ # wget -O- nginx
Connecting to nginx (10.108.57.129:80)
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
body {
width: 35em;
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>
<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>
<p><em>Thank you for using nginx.</em></p>
</body>
</html>
- 100% |*********************************************************************| 612 0:00:00 ETA
/ #
6. Finally, remove the tenant.
::
$ kubectl delete tenant test
tenant "test" deleted
7. Check Network in Neutron is also deleted by Stackube controller
:: ::

3
doc/source/index.rst
View File

@ -5,12 +5,13 @@ Welcome to Stackube developer documentation!
Stackube is a multi-tenant and secure Kubernetes deployment enabled by OpenStack Stackube is a multi-tenant and secure Kubernetes deployment enabled by OpenStack
core components. core components.
Stackube Scope Introduction
============== ==============
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
architecture
stackube_scope_clarification stackube_scope_clarification
Developer Guide Developer Guide

8
doc/source/setup.rst
View File

@ -1,7 +1,8 @@
Setting Up a Development Environment Setting Up a Development Environment
===================================== =====================================
This page describes how to setup a working development environment that can be used in developing stackube on Ubuntu or CentOS. These instructions assume you're already installed git, golang and python on your host. This page describes how to setup a working development environment that can be used in developing stackube on Ubuntu or
CentOS. These instructions assume you're already installed git, golang and python on your host.
================= =================
Getting the code Getting the code
@ -61,3 +62,8 @@ And configure local.conf:
- Set `HOST_IP` to local host's IP - Set `HOST_IP` to local host's IP
- Set `SERVICE_HOST` to master's IP - Set `SERVICE_HOST` to master's IP
- Set `KUBEADM_TOKEN` to kubeadm token - Set `KUBEADM_TOKEN` to kubeadm token
Start installation:
::
./stack.sh