You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2017/12/08 12:06:08 UTC
[GitHub] csantanapr closed pull request #115: Update install and setup documentation.
csantanapr closed pull request #115: Update install and setup documentation.
URL: https://github.com/apache/incubator-openwhisk-deploy-kube/pull/115
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/README.md b/README.md
index 3c996f5..56323fa 100644
--- a/README.md
+++ b/README.md
@@ -3,111 +3,107 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://travis-ci.org/apache/incubator-openwhisk-deploy-kube)
-This repo can be used to deploy OpenWhisk to a Kubernetes cluster.
+This repository can be used to deploy OpenWhisk to a Kubernetes cluster.
# Table of Contents
* [Requirements](#requirements)
-* [Setting up Kuberentes](#setting-up-kubernetes)
-* [Configuring OpenWhisk](#configure-openwhisk)
+* [Setting up Kubernetes](#setting-up-kubernetes)
+* [Configuring OpenWhisk](#configuring-openwhisk)
* [Cleanup](#cleanup)
-* [Limitations](#limitations)
* [Issues](#issues)
# Requirements
-A number of requirements must be met for OpenWhisk to deploy on Kubernetes.
+Several requirements must be met for OpenWhisk to deploy on Kubernetes.
**Kubernetes**
-* [Kubernetes](https://github.com/kubernetes/kubernetes) version 1.5+
-* Kubernetes has [KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) deployed
-* (Optional) Kubernetes Pods can receive public addresses.
- This will be required if you wish to reach Nginx from outside
- of the Kubernetes cluster network.
+* [Kubernetes](https://github.com/kubernetes/kubernetes) version 1.6+. However, avoid Kubernetes 1.6.3 due to an [issue with volume mount subpaths](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.6.md#known-issues-for-v163). Our Travis CI testing uses Kubernetes version 1.7.4.
+* The ability to create Ingresses to expose a Kubernetes service to the outside of a cluster so you can actually use OpenWhisk.
+* Endpoints of Kubernetes services must be able to loopback to themselves ("hairpin mode").
**OpenWhisk**
* Docker version 1.12+
-**NOTE:** If you do not have an environment that meets these requirements then you can
-set one up following the [Setting up Kubernetes](#setting-up-kubernetes) section.
-
# Setting up Kubernetes
-If you are deploying Kubernetes from scratch to try out OpenWhisk, there are a number of
-ways to setup a Dev/Test environmnet depending on your host OS. To mitigate that, we are using
-VirtualBox with a Ubuntu VM. For the full instructions on setting an environment up,
-take a look at these [instructions](/docs/setting_up_kube/README.md).
+## Using Minikube
+
+For local development and testing, we recommend using Minikube version 0.23+
+with the docker network in promiscuous mode. Our Travis CI testing using Minikube 0.23.0.
+Take a look at these [instructions](/docs/setting_up_minikube/README.md).
+
+## Using a Kubernetes cluster from a cloud provider
+
+You can also provision a Kubernetes cluster from a cloud provider, subject to the cluster meeting the requirements above.
-# Configure OpenWhisk
+# Configuring OpenWhisk
-To deploy OpenWhisk on Kubernetes, you first need to setup CouchDB.
-In this repo, there is a CouchDB instance that can be used to standup
-a small OpenWhisk test environment. We would not support using this
-deployment strategy for production environments, but to test OpenWhisk
-on Kube check out the CouchDB README.
+## Initial Configuration
-* [CouchDB](kubernetes/couchdb/README.md)
+* Create the openwhisk namespace: `kubectl apply -f configure/openwhisk_kube_namespace.yml`
-For a production level CouchDB instance, take a look at the main
-OpenWhisk [Docs](https://github.com/apache/incubator-openwhisk/blob/master/tools/db/README.md)
-for CouchDB.
+## Deploy Components
-Once CouchDB has been successfully deployed, you will need
-manually deploy the rest of the OpenWhisk components.
+To deploy OpenWhisk on Kubernetes, you must deploy its components in
+the proper order. Detailed instructions and the supporting .yml files
+can be found in the kubernetes directory tree. You will need to follow
+the instructions for each step in order.
-* [Redis](kubernetes/redis/README.md)
-* [ApiGateway](kubernetes/apigateway/README.md)
-* [Zookeeper](kubernetes/zookeeper/README.md)
-* [Kafka](kubernetes/kafka/README.md)
-* [Controller](kubernetes/controller/README.md)
-* [Invoker](kubernetes/invoker/README.md)
-* [Nginx](kubernetes/nginx/README.md)
-* [Ingress](kubernetes/ingress/README.md)
+* Configure or deploy CouchDB.
+ * For development and testing purposes, this repo includes a configuration
+ for deploying a [simple non-persistent CouchDB instance](kubernetes/couchdb/README.md)
+ within the Kubernetes cluster.
+ * For a production level CouchDB instance, take a look at the main
+ OpenWhisk [documentation for configuring CouchDB](https://github.com/apache/incubator-openwhisk/blob/master/tools/db/README.md).
+* Deploy [Redis](kubernetes/redis/README.md)
+* Deploy [ApiGateway](kubernetes/apigateway/README.md)
+* Deploy [Zookeeper](kubernetes/zookeeper/README.md)
+* Deploy [Kafka](kubernetes/kafka/README.md)
+* Deploy [Controller](kubernetes/controller/README.md)
+* Deploy [Invoker](kubernetes/invoker/README.md)
+* Deploy [Nginx](kubernetes/nginx/README.md)
+* Deploy [Ingress](kubernetes/ingress/README.md)
-In the commands below, replace API_HOST with the URL appropriate for the Ingress you deployed.
+## Configure the OpenWhisk CLI
-Configure the wsk cli by setting the auth and apihost properties.
+If you don't already have the wsk cli, follow the instructions [here](https://github.com/apache/incubator-openwhisk-cli) to get it.
+
+Configure the wsk cli by setting the auth and apihost properties (replace API_HOST with the URL appropriate for the Ingress you deployed).
```
wsk property set --auth 23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP --apihost https://API_HOST
```
-Install the initial catalog. To do this, you will need to set
-the `OPENWHISK_HOME` environment variable:
+## Install the initial catalog
-```
-export OPENWHISK_HOME [location of the openwhisk repo]
-```
+To do this, you will need to set the `OPENWHISK_HOME` environment variable to a git clone of the main OpenWhisk repository and
+replace API_HOST with the URL appropriate for the Ingress you deployed:
```
- pushd /tmp
- git clone https://github.com/apache/incubator-openwhisk-catalog
- cd incubator-openwhisk-catalog/packages
- ./installCatalog.sh 789c46b1-71f6-4ed5-8c54-816aa4f8c502:abczO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP https://API_HOST
- popd
+export OPENWHISK_HOME [location of your OpenWhisk clone]
+
+pushd /tmp
+ git clone https://github.com/apache/incubator-openwhisk-catalog
+ cd incubator-openwhisk-catalog/packages
+ ./installCatalog.sh 789c46b1-71f6-4ed5-8c54-816aa4f8c502:abczO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP https://API_HOST
+popd
```
+## Verify
+
+Your OpenWhisk installation should now be usable. You can test it by following
+[these instructions](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions.md)
+to define and invoke a sample OpenWhisk action in your favorite programming language.
+
# Cleanup
At some point there might be a need to cleanup the Kubernetes environment.
For this, we want to delete all the OpenWhisk deployments, services, jobs
-and whatever else might be there. For this, you can run the following script:
+and whatever else might be there. We provide a script to do this:
```
./configure/cleanup.sh
```
-# Limitations
-
-A couple of components for OpenWhisk on Kube deployment strategy requires custom
-built Docker images. One such component is Nginx and currently resides at
-[danlavine/whisk_nginx](https://hub.docker.com/r/danlavine/whisk_nginx/). There
-is currently and open [issue](https://github.com/openwhisk/openwhisk/issues/2152)
-to make a public image and once it is resolved, then we can switch to the public image.
-
-
-**Bad Kube versions**
-* Kube 1.6.3 has an issue with volume mount subpaths. See
- [here](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#v163)
- for more information.
# Issues
diff --git a/docs/setting_up_kube/README.md b/docs/setting_up_kube/README.md
deleted file mode 100644
index 6345264..0000000
--- a/docs/setting_up_kube/README.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Setting Up Kubernetes
-
-## Dev and Test Environment
-
-For Dev/Test environments, it is always easiest to have a reproducible setup. The
-current setup used for developing OpenWhisk on Kube solution is as follows.
-
-VM Requirments:
-
-* [VirtualBox](https://www.virtualbox.org/)
-* [Ubuntu-14.04](https://www.ubuntu.com/download/alternative-downloads)
- Desktop or server should be fine. (We use desktop since it doubles as a Dev/Test env).
-
-When creating the VM in virtualbox, it is always nice to give it more than enough
-resource:
-
-* 8GB Memory
-* 100GB of Disk
-* 4 Virtual Processors
-
-Once the VM has been created, you will need to make sure that a number of tools
-and packages have been installed:
-
-* `sudo apt-get install git`
-* Install the [Docker](https://docs.docker.com/engine/installation/linux/ubuntu/#install-using-the-repository)
- repository, but do not install Docker itself. You will need version 1.12.6
- specifically which can be installed with:
- ```
- sudo apt-get install docker-engine=1.12.6~ubuntu-trusty
- ```
- once the repository has been set up
-* [Golang 1.7.4](https://golang.org/dl/). Find the 1.7.4 version (same version to build Kubernetes
- so might as well go with it) and it will give details on setting up Golang.
-* Download this repo
-* (optional, reqired for dev) Download [openwhisk](https://github.com/apache/incubator-openwhisk)
-
-Next, you will need to do some extra configurations since you are on a
-VM. You will need to edit the `/etc/resolv.conf` file to point to a publicly
-available DNS. Say:
-
-```
-nameserver 8.8.8.8
-nameserver 8.8.4.4
-```
-
-The reason for this, is that Pods in Kubernetes mounts the hosts `resolv.conf`
-file into the Pod as the `resolv.conf`. By default, Ubuntu has `nameserver 127.0.1.1`
-which points to a loopback device. But in a Kube Pod that loopback
-device is unreachable and makes no sense. There is a way to configure this in
-Kubernetes, but the option is not exposed in the `local-up-cluster.sh` script
-we will be using in just a minute.
-
-Lastly, you will actually need to stand up the Kubernetes instance.
-Luckily you should be able to run the travis setup script and have everything
-be configured for you.
-
-```
-cd $THIS_REPO_LOCATION/tools/travis
-TRAVIS_KUBE_VERSION=v1.6.2 TRAVIS_ETCD_VERSION=v3.0.17 ./setup
-```
-
-This script should download and install a correct version of `etcd`, `kubectl`, and the
-[Kubernetes](https://github.com/kubernetes/kubernetes) repo. Then it will call
-out to the `local-up-cluster.sh` script with extra configuration settings for
-KubeDNS support inside of the Kube repo. That script then goes through
-the process of install all of the binaries (If this fails recheck the Golang docs for setup)
-and running them.
-
-Once finished, you should be able to talk to the Kube repo using `kubectl`.
-
-## Other Kube Configurations
-
-[Kubeadm](https://kubernetes.io/docs/getting-started-guides/kubeadm/)
-can be deployed with [Callico](https://www.projectcalico.org/) for the
-[network](http://docs.projectcalico.org/v2.1/getting-started/kubernetes/installation/hosted/kubeadm/).
-By default kubeadm runs with KubeDNS already enabled, but please make sure
-to install Kubeadm for Kube version 1.5.
-
-[Minikube](https://github.com/kubernetes/minikube) support is
-experimental, see the
-[Minikube-specific install instructions](/minikube/README.md) for more
-details.
diff --git a/docs/setting_up_minikube/README.md b/docs/setting_up_minikube/README.md
new file mode 100644
index 0000000..b1b5904
--- /dev/null
+++ b/docs/setting_up_minikube/README.md
@@ -0,0 +1,19 @@
+# Setting Up Minikube for OpenWhisk
+
+First, download and install Minikube following these [instructions](https://github.com/kubernetes/minikube).
+
+You will want at least 4GB of memory and 2 CPUs for Minikube to run OpenWhisk.
+If you have a larger machine, you may want to provision more (especially more memory).
+
+Start Minikube with:
+```
+minikube start --cpus 2 --memory 4096 --kubernetes-version v1.7.4
+```
+
+Put the docker network in promiscuous mode.
+```
+minikube ssh
+(%) sudo ip link set docker0 promisc on
+```
+
+Your Minikube cluster should now be ready to deploy OpenWhisk.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services