kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Modifying Openstack kube-up provider documentation.

This commit is contained in:
Elson O Rodriguez 2016-04-14 15:04:01 -07:00 committed by Lukasz Zajaczkowski
parent 9fc334bc22
commit 0d0459c50f
1 changed files with 190 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
docs/getting-started-guides/openstack.md
View File

@ -6,112 +6,225 @@
## Getting started with OpenStack
Running Kubernetes with Openstack is an easy way to create Kubernetes cluster on the top of OpenStack. Heat OpenStack Orchestration
engine describes the infrastructure for Kubernetes cluster. CentoOS images are used for Kubernetes host machines.
This guide will take you through the steps of deploying Kubernetes to Openstack using `kube-up.sh`. The primary mechanisms for this are [OpenStack Heat](https://wiki.openstack.org/wiki/Heat) and the [SaltStack](https://github.com/kubernetes/kubernetes/tree/master/cluster/saltbase) distributed with Kubernetes.
## Prerequisites
The default OS is CentOS 7, this has not been tested on other operating systems.
1. Install latest version OpenStack clients
This guide assumes you have a working OpenStack cluster.
heat >= 0.9.0
## Pre-Requisites
If you already have the OpenStack CLI tools installed and configured, you can move on to the [Starting a cluster](#starting-a-cluster) section.
swift >= 2.7.0
glance >= 1.2.0
nova >= 3.2.0
```
sudo pip install -U --force python-heatclient
sudo pip install -U --force python-swiftclient
sudo pip install -U --force python-glanceclient
sudo pip install -U --force python-novaclient
```
#### Note:
OpenStack CLI clients like python-PROJECTNAMEclient are going to be deprecated soon in favor of universal OpenStack CLI client.
More information you can find here: [deprecate-cli](https://specs.openstack.org/openstack/openstack-specs/specs/deprecate-cli.html)
2. Set proper values in configuration files
Project contains four files with configuration: config-default.sh, config-image.sh, openrc-default.sh and openrc-swift.sh
**config-default.sh** sets all parameters needed for heat template.
Additionally there is a flag CREATE_IMAGE which indicates if new image must be created.
If 'false' then image with IMAGE_ID will be used.
**config-image.sh** sets parameters needed to create new OpenStack image if flag CREATE_IMAGE=true.
Use CentOS 7 image for this purpose. You can get image here: [CentOS images](http://cloud.centos.org/centos/7/images/)
**openrc-default.sh openrs-swift.sh** those files contain credential variables for OpenStack clients.
## Setup
Setting up a cluster:
#### Install OpenStack CLI tools
```sh
export KUBERNETES_PROVIDER=openstack
cd kubernetes
sudo pip install -U --force 'python-heatclient==1.1.0'
sudo pip install -U --force 'python-swiftclient==3.0.0'
sudo pip install -U --force 'python-glanceclient==2.0.0'
sudo pip install -U --force 'python-novaclient==3.4.0'
```
#### Configure Openstack CLI tools
Please talk to your local OpenStack administrator for an `openrc.sh` file.
Once you have that file, source it into your environment by typing
```sh
. ~/path/to/openrc.sh
```
This provider will consume the [correct variables](http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html) to talk to OpenStack and turn-up the Kubernetes cluster.
Otherwise, you must set the following appropriately:
```sh
export OS_USERNAME=username
export OS_PASSWORD=password
export OS_TENANT_NAME=projectName
export OS_AUTH_URL=https://identityHost:portNumber/v2.0
export OS_TENANT_ID=tenantIDString
export OS_REGION_NAME=regionName
```
#### Set additional configuration values
In addition, here are some commonly changed variables specific to this provider, with example values. Under most circumstances you will not have to change these.
```sh
export STACK_NAME=KubernetesStack
export NUMBER_OF_MINIONS=3
export MAX_NUMBER_OF_MINIONS=3
export MASTER_FLAVOR=m1.small
export MINION_FLAVOR=m1.small
export EXTERNAL_NETWORK=public
export DNS_SERVER=8.8.8.8
export IMAGE_URL_PATH=http://cloud.centos.org/centos/7/images
export IMAGE_FILE=CentOS-7-x86_64-GenericCloud-1510.qcow2
export SWIFT_SERVER_URL=http://192.168.123.100:8080
export ENABLE_PROXY=false
```
#### Manually overriding configuration values
If you do not have your environment variables set, or do not want them consumed, modify the variables in the following files under `cluster/openstack`:
- **[config-default.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/openstack-heat/config-default.sh)** Sets all parameters needed for heat template.
- **[config-image.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/openstack-heat/config-image.sh)** Sets parameters needed to download and create new OpenStack image via glance.
- **[openrc-default.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/openstack-heat/openrc-default.sh)** Sets environment variables for communicating to OpenStack. These are consumed by the cli tools (heat, glance, swift, nova).
- **[openrc-swift.sh](http://releases.k8s.io/{{page.githubbranch}}/cluster/openstack-heat/openrc-swift.sh)** Some OpenStack setups require the use of seperate swift credentials. Put those credentials in this file.
Please see the contents of these files for documentation regarding each variable's function.
## Starting a cluster
Once you've installed the OpenStack CLI tools and have set your OpenStack environment variables, issue this command:
```sh
export KUBERNETES_PROVIDER=openstack-heat; curl -sS https://get.k8s.io | bash
```
Alternatively, you can download a [Kubernetes release](https://github.com/kubernetes/kubernetes/releases) and extract the archive. To start your cluster, open a shell and run:
```sh
cd kubernetes # Or whichever path you have extracted the release to
KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
Or, if you are working from a checkout of the Kubernetes code base, and want to build/test from source:
```sh
cd kubernetes # Or whatever your checkout root directory is called
make clean
make quick-release
./cluster/kube-up.sh
KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
## Inspect your cluster
Once kube-up is finished, your cluster should be running:
```console
./cluster/kubectl.sh get cs
NAME STATUS MESSAGE ERROR
controller-manager Healthy ok
scheduler Healthy ok
etcd-1 Healthy {"health": "true"}
etcd-0 Healthy {"health": "true"}
```
Alternatively, you can download [Kubernetes release](https://github.com/kubernetes/kubernetes/releases) and extract the archive. To start your local cluster, open a shell and run:
You can also list the nodes in your cluster:
```console
./cluster/kubectl.sh get nodes
NAME STATUS AGE
kubernetesstack-node-ojszyjtr Ready 42m
kubernetesstack-node-tzotzcbp Ready 46m
kubernetesstack-node-uah8pkju Ready 47m
```
Being a new cluster, there will be no pods or replication controllers in the default namespace:
```console
./cluster/kubectl.sh get pods
./cluster/kubectl.sh get replicationcontrollers
```
You are now ready to create Kubernetes objects.
## Using your cluster
For a simple test, issue the following command:
```sh
cd kubernetes
export KUBERNETES_PROVIDER=openstack
./cluster/kube-up.sh
./cluster/kubectl.sh run nginx --image=nginx --generator=run-pod/v1
```
The `KUBERNETES_PROVIDER` environment variable tells all of the various cluster management scripts which variant to use. If you forget to set this, the assumption is you are running on Google Compute Engine.
## Interacting with your Kubernetes cluster with Openstack
You can manage the nodes in your cluster with the Openstack WEB UI like Horizon or using heat or nova clients.
To get all necessary information about cluster execute commands in main kubernetes directory:
Soon, you should have a running nginx pod:
```console
./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
nginx 1/1 Running 0 5m
```
Once the nginx pod is running, use the port-forward command to set up a proxy from your machine to the pod.
```sh
./cluster/kubectl.sh port-forward nginx 8888:80
```
You should now see nginx on [http://localhost:8888]().
For more complex examples please see the [examples directory](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/).
## Administering your cluster with Openstack
You can manage the nodes in your cluster using the OpenStack CLI Tools.
First, set your environment variables:
```sh
. cluster/openstack/config-default.sh
. cluster/openstack/openrc-default.sh
```
To get all information about your cluster, use heat:
```sh
heat stack-show $STACK_NAME
```
You will get cluster status and IP addresses for your master and minion nodes.
To see a list of nodes, use nova:
## Authenticating with your master
Because you added public key to nodes you can easily ssh to them.
```
$ ssh minion@IP_ADDRESS
```sh
nova list --name=$STACK_NAME
```
## Running containers
See the [OpenStack CLI Reference](http://docs.openstack.org/cli-reference/) for more details.
Your cluster is running, you can list the nodes in your cluster:
## SSHing to your nodes
```console
$ ./cluster/kubectl.sh get nodes
NAME LABELS STATUS AGE
kubernetesstack-node-tc9f2tfr kubernetes.io/hostname=kubernetesstack-node-tc9f2tfr Ready 21h
Your public key was added during the cluster turn-up, so you can easily ssh to them for troubleshooting purposes.
```sh
ssh minion@IP_ADDRESS
```
Before starting a container there will be no pods, services and replication controllers.
## Cluster deployment customization examples
You may find the need to modify environment variables to change the behaviour of kube-up. Here are some common scenarios:
```console
$ ./cluster/kubectl.sh get pods
NAME READY STATUS RESTARTS AGE
#### Proxy configuration
If you are behind a proxy, and have your local environment variables setup, you can use these variables to setup your Kubernetes cluster:
$ ./cluster/kubectl.sh get services
NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE
$ ./cluster/kubectl.sh get replicationcontrollers
CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS
```sh
ENABLE_PROXY=true KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
Now you are ready to create you first service and controller.
#### Setting different Swift URL
Some deployments differ from the default Swift URL:
```sh
SWIFT_SERVER_URL="http://10.100.0.100:8080" KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
#### Public network name.
Sometimes the name of the public network differs from the default `public`:
```sh
EXTERNAL_NETWORK="network_external" KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
#### Spinning up additional clusters.
You may want to spin up another cluster within your OpenStack project. Use the `$STACK_NAME` variable to accomplish this.
```sh
STACK_NAME=k8s-cluster-2 KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-up.sh
```
For more configuration examples, please browse the files mentioned in the [Configuration](#set-additional-configuration-values) section.
## Tearing down your cluster
To bring down your cluster, issue the following command:
```sh
KUBERNETES_PROVIDER=openstack-heat ./cluster/kube-down.sh
```
If you have changed the default `$STACK_NAME`, you must specify the name. Note that this will not remove any Cinder volumes created by Kubernetes.