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 2018/06/07 14:15:26 UTC
[GitHub] dgrove-oss closed pull request #212: Reorganize docs to steer users
to Helm
dgrove-oss closed pull request #212: Reorganize docs to steer users to Helm
URL: https://github.com/apache/incubator-openwhisk-deploy-kube/pull/212
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 3657811..aee96b6 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@
#
-->
-# OpenWhisk Deployment for Kubernetes
+# OpenWhisk Deployment on Kubernetes
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://travis-ci.org/apache/incubator-openwhisk-deploy-kube)
@@ -26,23 +26,23 @@ This repository can be used to deploy OpenWhisk to a Kubernetes cluster.
# Table of Contents
-* [Requirements](#requirements)
-* [Setting up Kubernetes](#setting-up-kubernetes)
-* [Configuring OpenWhisk](#configuring-openwhisk)
+* [Setting up Kubernetes and Helm](#setting-up-kubernetes-and-helm)
+* [Deploying OpenWhisk](#deploying-openwhisk)
* [Cleanup](#cleanup)
* [Issues](#issues)
-# Requirements
-Several requirements must be met for OpenWhisk to deploy on Kubernetes.
+# Setting up Kubernetes and Helm
+
+## Kubernetes
+
+### Requirements
-**Kubernetes**
-* [Kubernetes](https://github.com/kubernetes/kubernetes) version 1.6+. However, multiple minor releases of Kubernetes, including 1.6.3, 1.7.14, 1.8.9 and 1.9.4 will not work for OpenWhisk due to bugs with volume mount subpaths (see[[1](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.6.md#known-issues-for-v163), [2](https://github.com/kubernetes/kubernetes/issues/61076)]. This bug will surface as a failure when deploying the nginx container.
+Several requirements must be met for OpenWhisk to deploy on Kubernetes.
+* [Kubernetes](https://github.com/kubernetes/kubernetes) version 1.8+. However, multiple minor releases of Kubernetes, including 1.8.9 and 1.9.4 will not work for OpenWhisk due to bugs with volume mount subpaths (see[[1](https://github.com/kubernetes/kubernetes/issues/61076)]. This bug will surface as a failure when deploying the nginx container.
* The ability to create Ingresses to make a Kubernetes service available outside of the cluster so you can actually use OpenWhisk.
* Endpoints of Kubernetes services must be able to loopback to themselves (the kubelet's `hairpin-mode` must not be `none`).
-# Setting up Kubernetes
-
-## Using Minikube
+### Using Minikube
For local development and testing, we recommend using Minikube with
the docker network in promiscuous mode. Not all combinations of
@@ -56,88 +56,145 @@ Travis CI testing.
1.8.0 | 0.25.2 |
1.9.0 | 0.25.2 |
-For details on setting up Minikube, see these [instructions](/docs/setting_up_minikube/README.md).
+For details on setting up Minikube, see these [instructions](docs/minikube.md).
-## Using a Kubernetes cluster from a cloud provider
+### 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.
-# Configuring OpenWhisk
-
-The first time you deploy OpenWhisk on Kubernetes, we recommend
-following the steps below manually so you can inspect the results and
-debug your setup. After you are confident that OpenWhisk deploys
-smoothly on your cluster, you might find it useful to drive your
-deployments using the script [build.sh](tools/travis/build.sh) that we
-use to deploy OpenWhisk on Kubernetes for our Travis CI testing.
+## Helm
+
+[Helm](https://github.com/kubernetes/helm) is a tool to simplify the
+deployment and management of applications on Kubernetes clusters. Helm
+consists of the `helm` command line tool that you install on your
+development machine and the `tiller` runtime that you install on your
+Kubernetes cluster.
+
+For details on installing Helm, see these [instructions](docs/helm.md).
+
+# Deploying OpenWhisk
+
+## Overview
+
+You will use Helm to deploy OpenWhisk to your Kubernetes cluster.
+There are four deployment steps that are described in more
+detail below in the rest of this section.
+1. [Initial cluster setup](#initial-setup). You will create a
+Kubernetes namespace into which to deploy OpenWhisk and label the
+Kubernetes worker nodes to be used to execute user actions.
+2. [Customize the deployment](#customize-the-deployment). You will
+create a `mycluster.yaml` that specifies key facts about your
+Kubernetes cluster and the OpenWhisk configuration you wish to
+deploy.
+3. [Deploy with Helm](#deploy-with-helm). You will use Helm and
+`mycluster.yaml` to deploy OpenWhisk to your Kubernetes cluster.
+4. [Configure the `wsk` CLI](#configure-the-wsk-cli). You need to
+tell the `wsk` CLI how to connect to your OpenWhisk deployment.
+
+## Initial setup
+
+1. Resources in Kubernetes are organized into namespaces. You can use
+any name for the namespace you want, but we suggest using
+`openwhisk`. Create one by issuing the command:
+```shell
+kubectl create namespace openwhisk
+```
-## Initial Cluster Configuration
+2. Identify the Kubernetes worker nodes that should be used to execute
+user containers. Do this by labeling each node with
+`openwhisk-role=invoker`. For a single node cluster, simply do
+```shell
+kubectl label nodes --all openwhisk-role=invoker
+```
+If you have a multi-node cluster, for each node <INVOKER_NODE_NAME>
+you want to be an invoker, execute
+```shell
+$ kubectl label nodes <INVOKER_NODE_NAME> openwhisk-role=invoker
+```
-* Follow the steps for initial [Cluster Setup](kubernetes/cluster-setup)
-* Configure your [Ingresses](kubernetes/ingress), including configuring the wsk CLI.
+## Customize the Deployment
-## Configure or Deploy CouchDB
+You will need to create a mycluster.yaml file that records how the
+OpenWhisk deployment on your cluster will be accessed by clients. See
+the [ingress discussion](./docs/ingress.md) for details. Below is a sample
+file appropriate for a Minikube cluster where `minikube ip` returns
+`192.168.99.100` and port 31001 is available to be used.
-Do one of the following:
-* For development and testing purposes, this repo includes a configuration
- for deploying a [non-replicated CouchDB instance](kubernetes/couchdb)
- 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).
- You will need to define the db.auth secret and db.config configmap as described in the [CouchDB README.md](kubernetes/couchdb/README.md)
- to match your database deployment and create a CouchDB service instance
- that forwards connections to your external database.
+```yaml
+whisk:
+ ingress:
+ type: NodePort
+ api_host_name: 192.168.99.100
+ api_host_port: 31001
-## Deploy Remaining Components
+nginx:
+ httpsNodePort: 31001
+```
-To deploy OpenWhisk on Kubernetes, you must deploy its components in
-an order that respects their dependencies. Detailed instructions and
-the supporting configuration files can be found in the kubernetes
-directory tree. Follow the instructions for each step in order.
+Beyond specifying the ingress, the `mycluster.yaml` file is also used
+to customize your OpenWhisk deployment by enabling optional features
+and controlling the replication factor of the various micro-services
+that make up the OpenWhisk implementation. See the [configuration
+choices documentation](./docs/configurationChoices.md) for a
+discussion of the primary options.
-* Deploy [ApiGateway](kubernetes/apigateway)
-* Deploy [Zookeeper](kubernetes/zookeeper)
-* Deploy [Kafka](kubernetes/kafka)
-* Deploy [Controller](kubernetes/controller)
-* Deploy [Invoker](kubernetes/invoker)
-* Deploy [Nginx](kubernetes/nginx)
+## Deploy With Helm
-## Install system actions and the openwhisk catalog
+Deployment can be done by using the following single command:
+```shell
+helm install . --namespace=openwhisk -f mycluster.yaml
+```
-* Install [RouteMgmt](kubernetes/routemgmt)
-* Install [Package Catalog](kubernetes/openwhisk-catalog)
+You can use the command `helm status <release_name>` to get a summary
+of the various Kubernetes artifacts that make up your OpenWhisk
+deployment. Once all the pods shown by the status command are in
+either the `Running` or `Completed` state, your OpenWhisk deployment
+is ready to be used.
+
+## Configure the wsk CLI
+
+Configure the OpenWhisk CLI, wsk, 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). Replace `whisk.ingress.api_host_name` and `whisk.ingress.api_host_port`
+with the actual values from your mycluster.yaml.
+```shell
+wsk property set --apihost whisk.ingress.api_host_name:whisk.ingress.api_host_port
+wsk property set --auth 23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP
+```
-## Verify
+## Verify your OpenWhisk Deployment
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.
-Note: if you installed self-signed certificates when you configured Nginx, you will need to use `wsk -i` to suppress certificate checking. This works around `cannot validate certificate` errors from the `wsk` CLI.
+Note: if you installed self-signed certificates, which is the default
+for the OpenWhisk Helm chart, you will need to use `wsk -i` to
+suppress certificate checking. This works around `cannot validate
+certificate` errors from the `wsk` CLI.
-# Cleanup
+If your deployment is not working, check our
+[troubleshooting guide](./docs/troubleshooting.md) for ideas.
-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. This is easily accomplished by
-deleting the `openwhisk` namespace and all persistent volumes labeled with
-pv-owner=openwhisk:
+# Cleanup
+Use the following command to remove all the deployed OpenWhisk components:
+```shell
+helm delete <release_name>
```
-kubectl delete namespace openwhisk
-kubectl delete persistentvolume -lpv-owner=openwhisk
+Helm does keep a history of previous deployments. If you want to
+completely remove the deployment from helm, for example so you can
+reuse <release_name> to deploy OpenWhisk again, use the command:
+```shell
+helm delete <release_name> --purge
```
-# Deploying OpenWhisk using Helm
-
-We are also working on developing Helm charts to deploy OpenWhisk on
-Kubernetes. Currently, the Helm charts do not support all of the
-configuration options of the more manual deployment process described
-above. However, they are sufficient for deploying the core OpenWhisk
-system on Minikube. Please see [helm/README.md](helm/README.md) for more details.
-
# Issues
+If your OpenWhisk deployment is not working, check our
+[troubleshooting guide](./docs/troubleshooting.md) for ideas.
+
Report bugs, ask questions and request features [here on GitHub](../../issues).
You can also join our slack channel and chat with developers. To get access to our slack channel, request an invite [here](http://slack.openwhisk.org).
diff --git a/docs/configurationChoices.md b/docs/configurationChoices.md
new file mode 100644
index 0000000..e62bc38
--- /dev/null
+++ b/docs/configurationChoices.md
@@ -0,0 +1,97 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+-->
+
+This document outlines some of the configuration options that are
+supported by the OpenWhisk Helm chart. In general, you customize your
+deployment by adding stanzas to `mycluster.yaml` that override default
+values in the `helm/values.yaml` file.
+
+### Replication factor
+
+By default the OpenWhisk Helm Chart will deploy a single replica of each
+of the micro-services that make up the OpenWhisk control plane. By
+changing the `replicaCount` value for a service, you can instead deploy
+multiple instances. This can support both increased scalability and
+fault tolerance. For example, to deploy two controller instances, add
+the following to your `mycluster.yaml`
+
+```yaml
+controller:
+ replicaCount: 2
+```
+
+### Invoker Container Factory
+
+The Invoker is responsible for creating and managing the containers
+that OpenWhisk creates to execute the user defined functions. A key
+function of the Invoker is to manage a cache of available warm
+containers to minimize cold starts of user functions.
+Architecturally, we support two options for deploying the Invoker
+component on Kubernetes (selected by picking a
+`ContainerFactoryProviderSPI` for your deployment).
+ 1. `DockerContainerFactory` matches the architecture used by the
+ non-Kubernetes deployments of OpenWhisk. In this approach, an
+ Invoker instance runs on every Kubernetes worker node that is
+ being used to execute user functions. The Invoker directly
+ communicates with the docker daemon running on the worker node
+ to create and manage the user function containers. The primary
+ advantages of this configuration are lower latency on container
+ management operations and robustness of the code paths being
+ used (since they are the same as in the default system). The
+ primary disadvantage is that it does not leverage Kubernetes to
+ simplify resource management, security configuration, etc. for
+ user containers.
+ 2. `KubernetesContainerFactory` is a truly Kubernetes-native design
+ where although the Invoker is still responsible for managing the
+ cache of available user containers, the Invoker relies on Kubernetes to
+ create, schedule, and manage the Pods that contain the user function
+ containers. The pros and cons of this design are roughly the
+ inverse of `DockerContainerFactory`. Kubernetes pod management
+ operations have higher latency and exercise newer code paths in
+ the Invoker. However, this design fully leverages Kubernetes to
+ manage the execution resources for user functions.
+
+You can control the selection of the ContainerFactory by adding either
+```yaml
+invoker:
+ containerFactory:
+ impl: "docker"
+```
+or
+```yaml
+invoker:
+ containerFactory:
+ impl: "kubernetes"
+```
+to your `mycluster.yaml`
+
+The KubernetesContainerFactory can be deployed with an additional
+invokerAgent that implements container suspend/resume operations on
+behalf of a remote Invoker. To enable this, add
+```yaml
+invoker:
+ containerFactory:
+ impl: "kubernetes"
+ agent:
+ enabled: true
+```
+to your `mycluster.yaml`
+
+For scalability, you will probably want to use `replicaCount` to
+deploy more than one Invoker when using the KubernetesContainerFactory.
diff --git a/docs/helm.md b/docs/helm.md
new file mode 100644
index 0000000..f43158d
--- /dev/null
+++ b/docs/helm.md
@@ -0,0 +1,52 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+-->
+
+## Installing Helm
+
+[Helm](https://github.com/kubernetes/helm) is a tool to simplify the
+deployment and management of applications on Kubernetes clusters. We
+will use Helm to deploy OpenWhisk on Kubernetes.
+
+Before you can use Helm, you need to do a small amount of one-time
+setup on your Kubernetes cluster.
+
+1. Make sure that you have a running Kubernetes cluster and a
+`kubectl` client connected to this cluster as described in the
+[Requirements section](../README.md#requirements) of the main
+README.md.
+
+2. Follow the Helm [install instructions](https://github.com/kubernetes/helm)
+for your platform.
+
+3. Run the following command to init `Helm Tiller`:
+```shell
+helm init
+```
+
+4. To see if Helm is ready, use the command below and make sure the
+`tiller-deploy` pod is in the `Running` state.
+```shell
+kubectl get pods -n kube-system
+```
+
+5. Grant the necessary privileges to the `Helm` user:
+```shell
+kubectl create clusterrolebinding tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default
+```
+
diff --git a/helm/ingress.md b/docs/ingress.md
similarity index 100%
rename from helm/ingress.md
rename to docs/ingress.md
diff --git a/docs/setting_up_minikube/README.md b/docs/minikube.md
similarity index 75%
rename from docs/setting_up_minikube/README.md
rename to docs/minikube.md
index 00779e3..3d9ad6e 100644
--- a/docs/setting_up_minikube/README.md
+++ b/docs/minikube.md
@@ -19,28 +19,39 @@
# Setting Up Minikube for OpenWhisk
-First, download and install Minikube following these [instructions](https://github.com/kubernetes/minikube).
+New versions of Minikube and Kubernetes are released fairly
+frequently. Over time, you will probably end up needing to have
+multiple versions installed on your development machine. We recommend
+using the asdf package manager to make it very easy to switch between
+versions and manage installation.
-## Setup MacOS for local minikube
-We recommend using the same versions we use in Travis, using asdf makes it very easy to select the version of minikube and kubectl
+## Install and configure asdf
-### Install asdf
+### MacOS
```
brew install asdf
```
-### Setup asdf in terminal
+
Edit your `~/.profile` or equivalent
```
[ -s "/usr/local/opt/asdf/asdf.sh" ] && . /usr/local/opt/asdf/asdf.sh
```
-### Add minikune and kubectl plugins
+### Other Platforms
+
+Follow the asdf installation instructions at https://github.com/asdf-vm/asdf
+
+## Add minikube and kubectl plugins
```
asdf plugin-add kubectl
asdf plugin-add minikube
```
-### Install asdf plugin minikube@0.25.2 and kubectl@1.9.0
+## Install minikube and kubectl using asdf.
+We recommend starting with versions of minikube and kubectl that match
+what we test in TravisCI. After you have experience with OpenWhisk on
+Minikube, feel free to experiment with additional versions.
+
```
asdf install kubectl 1.9.0
asdf global kubectl 1.9.0
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..ff5be89
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,55 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+-->
+
+This file documents some of the common things that can go wrong when
+deploying OpenWhisk on Kubernetes and how to correct them.
+
+### No invokers are deployed with DockerContainerFactory
+
+Verify that you actually have at least one node with the label openwhisk-role=invoker.
+
+### Invokers containers fail to start with volume mounting problems
+
+To execute the containers for user actions, OpenWhisk relies on part
+of the underlying infrastructure that Kubernetes is running on. When
+deploying the Invoker for OpenWhisk, it mounts the host's Docker
+socket and several other system-specific directories related to
+Docker. This enables efficient container management, but it also also
+means that the default volume hostPath values assume that the Kubernetes worker
+node image is Ubuntu. If containers fail to start with errors related
+mounting`/sys/fs/cgroup`, `/run/runc`,`/var/lib/docker/containers`, or
+`/var/run/docker.sock`, then you will need to change the corresponding
+value in `helm/templates/invoker.yaml` to match the host operating system
+running on your Kubernetes worker node.
+
+### Controller and Invoker cannot connect to Kafka
+
+If services are having trouble connecting to Kafka, it may be that the
+Kafka service didn't actually come up successfully. One reason Kafka
+can fail to come up is that it cannot connect to itself. On minikube,
+fix this by saying `minikube ssh -- sudo ip link set docker0 promisc
+on`. On full scale Kubernetes clusters, make sure that your kubelet's
+`hairpin-mode` is not `none`).
+
+### wsk `cannot validate certificates` error
+
+If you installed self-signed certificates, which is the default
+for the OpenWhisk Helm chart, you will need to use `wsk -i` to
+suppress certificate checking. This works around `cannot validate
+certificate` errors from the `wsk` CLI.
diff --git a/helm/README.md b/helm/README.md
deleted file mode 100644
index 5aac4bb..0000000
--- a/helm/README.md
+++ /dev/null
@@ -1,162 +0,0 @@
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You 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.
-#
--->
-
-## Overview
-
-This directory contains a Helm chart can be used to deploy Apache OpenWhisk to a Kubernetes cluster.
-
-It currently does not support all of the options available in the more
-manual deployment process described in the top-level README.md,
-however we are actively working on closing the gaps.
-
-The default values used in the chart are designed to deploy a minimal
-OpenWhisk deployment suitable for local development or testing on
-minikube or a single node Kubernetes cluster. We will soon provide a
-second set of default values suitable for larger-scale deployments.
-
-## Deployment Steps
-
-Please follow the following steps in this section to use [Helm](https://github.com/kubernetes/helm) to deploy this chart.
-
-### Step 1. Prepare Kubernetes and Helm
-
-Make sure that you have a running Kubernetes cluster and a `kubectl`
-client connected to this cluster as described in the [Requriements section](../README.md#requirements) of the main README.md.
-
-### Step 2. Install and configure Helm
-
-Then please install [Helm](https://github.com/kubernetes/helm) and run the following command to init `Helm Tiller`:
-```shell
-helm init
-
-```
-
-Please check with the following command to make sure `Helm` is up and running:
-```shell
-kubectl get pods -n kube-system
-
-```
-
-Then grant corresponding cluster role to `Helm` user:
-```shell
-kubectl create clusterrolebinding tiller-cluster-admin --clusterrole=cluster-admin --serviceaccount=kube-system:default
-```
-
-### Step 3. Prepare your cluster for OpenWhisk
-
-1. Create a new namespace named `openwhisk`:
-```shell
-kubectl create namespace openwhisk
-```
-
-2. Identify the Kubernetes worker nodes that should be used to execute
-user containers. Do this by labeling each node with
-`openwhisk-role=invoker`. For a single node cluster, simply do
-```shell
-kubectl label nodes --all openwhisk-role=invoker
-```
-If you have a multi-node cluster, for each node <INVOKER_NODE_NAME>
-you want to be an invoker, execute
-```shell
-$ kubectl label nodes <INVOKER_NODE_NAME> openwhisk-role=invoker
-```
-
-### Step 4. Define `mycluster.yaml`
-
-You will need to create a mycluster.yaml file that records how the
-OpenWhisk deployment on your cluster will be accessed by clients. See
-the [ingress discussion](./ingress.md) for details. Below is a sample
-file appropriate for a minikube cluster where `minikube ip` returns
-`192.168.99.100` and port 31001 is available to be used.
-
-```yaml
-whisk:
- ingress:
- type: NodePort
- api_host_name: 192.168.99.100
- api_host_port: 31001
-
-nginx:
- httpsNodePort: 31001
-```
-
-### Step 5. Deploy Charts
-
-Deployment can be done by using the following single command:
-```shell
-helm install . --namespace=openwhisk --name=your_release_name -f mycluster.yaml
-```
-
-After a while, if you can see all the pods listed by the following command are in `Running` state, congratulations, you have finished OpenWhisk deployment:
-```shell
-kubectl get pods -n openwhisk
-```
-
-### Step 6. Configure the `wsk` CLI
-
-Configure the OpenWhisk CLI, wsk, 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). Replace `whisk.ingress.api_host_name` and `whisk.ingress.api_host_port`
-with the actual values from your mycluster.yaml.
-```shell
-wsk property set --apihost whisk.ingress.api_host_name:whisk.ingress.api_host_port
-wsk property set --auth 23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP
-```
-
-### Step 7. Test your Deployment
-
-Prepare a small js function like the following and save it to `greeting.js`:
-```js
-/**
- * Return a simple greeting message for someone.
- *
- * @param name A person's name.
- * @param place Where the person is from.
- */
-function main(params) {
- var name = params.name || params.payload || 'stranger';
- var place = params.place || 'somewhere';
- return {payload: 'Hello, ' + name + ' from ' + place + '!'};
-}
-```
-
-Create an OpenWhisk action by:
-```shell
-wsk action create hello ./greeting.js
-```
-
-And try this action:
-```shell
-wsk action invoke hello -b
-```
-
-If the action is invoked and message is returned without error, congratulations, you have a running OpenWhisk cluster on Kubernetes, enjoy it!
-
-## Cleanup
-
-Use the following command to remove the deployment:
-```shell
-helm delete <release_name>
-```
-or with a `--purge` option if you want to completely remove the deployment from helm:
-```shell
-helm delete <release_name> --purge
-```
-
diff --git a/kubernetes/README.md b/kubernetes/README.md
new file mode 100644
index 0000000..4b5b355
--- /dev/null
+++ b/kubernetes/README.md
@@ -0,0 +1,82 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+-->
+
+# Manual deployment of OpenWhisk on Kubernetes
+
+This file documents the pre-Helm procedures for deploying OpenWhisk on
+Kubernetes. We no longer recommend using this process, but there are
+still a few configuration wrinkles that have not yet been ported to the
+Helm chart.
+
+## Initial Cluster Configuration
+
+* Follow the steps for initial [Cluster Setup](cluster-setup)
+* Configure your [Ingresses](ingress), including configuring the wsk CLI.
+
+## Configure or Deploy CouchDB
+
+Do one of the following:
+* For development and testing purposes, this repo includes a configuration
+ for deploying a [non-replicated CouchDB instance](couchdb)
+ 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).
+ You will need to define the db.auth secret and db.config configmap as described in the [CouchDB README.md](couchdb/README.md)
+ to match your database deployment and create a CouchDB service instance
+ that forwards connections to your external database.
+
+## Deploy Remaining Components
+
+To deploy OpenWhisk on Kubernetes, you must deploy its components in
+an order that respects their dependencies. Detailed instructions and
+the supporting configuration files can be found in the kubernetes
+directory tree. Follow the instructions for each step in order.
+
+* Deploy [ApiGateway](apigateway)
+* Deploy [Zookeeper](zookeeper)
+* Deploy [Kafka](kafka)
+* Deploy [Controller](controller)
+* Deploy [Invoker](invoker)
+* Deploy [Nginx](nginx)
+
+## Install system actions and the openwhisk catalog
+
+* Install [RouteMgmt](routemgmt)
+* Install [Package Catalog](openwhisk-catalog)
+
+## 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.
+
+Note: if you installed self-signed certificates when you configured Nginx, you will need to use `wsk -i` to suppress certificate checking. This works around `cannot validate certificate` errors from the `wsk` CLI.
+
+# 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. This is easily accomplished by
+deleting the `openwhisk` namespace and all persistent volumes labeled with
+pv-owner=openwhisk:
+
+```
+kubectl delete namespace openwhisk
+kubectl delete persistentvolume -lpv-owner=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