You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openwhisk.apache.org by ma...@apache.org on 2018/07/18 14:50:10 UTC
[incubator-openwhisk-deploy-kube] branch master updated: reorganize
ingress documentation to group by ingress instead of cloud provider. (#256)
This is an automated email from the ASF dual-hosted git repository.
markusthoemmes pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-deploy-kube.git
The following commit(s) were added to refs/heads/master by this push:
new aed807c reorganize ingress documentation to group by ingress instead of cloud provider. (#256)
aed807c is described below
commit aed807cecebd63de2f6b24988822711170e34ee7
Author: David Grove <dg...@users.noreply.github.com>
AuthorDate: Wed Jul 18 10:50:08 2018 -0400
reorganize ingress documentation to group by ingress instead of cloud provider. (#256)
---
docs/ingress.md | 100 +++++++++++++++++++++++++++++++++++---------------------
1 file changed, 62 insertions(+), 38 deletions(-)
diff --git a/docs/ingress.md b/docs/ingress.md
index c7731a4..73c32d8 100644
--- a/docs/ingress.md
+++ b/docs/ingress.md
@@ -28,38 +28,35 @@ will use in the `helm install` command. You will need to define
values for at least `whisk.ingress.type` and `whisk.ingress.api_host_name`
and `whisk.ingress.api_host_port`.
-Unfortunately, the exact details of configuring an Ingress vary across
-cloud providers. The detailed instructions
-[below](#possible-ingress-types) describe multiple possible Ingress
-configurations. We welcome contributions from the community to
+Unfortunately, the exact details of configuring an Ingress can vary
+across cloud providers. The detailed instructions describe multiple
+possible Ingress configurations with specific details for some public
+cloud providers. We welcome contributions from the community to
describe how to configure Ingress for additional cloud providers.
If you are deploying on minikube, use the NodePort instructions below.
-# Possible Ingress Types
-
-## NodePort
+# NodePort
NodePort is the simplest type of Ingress and is suitable for use with
minikube and single node clusters that do not support more advanced
ingress options. Deploying a NodePort ingress will expose a port on
each Kubernetes worker node for OpenWhisk's nginx service.
+
In this Ingress, TLS termination will be handled by OpenWhisk's
`nginx` service and will use self-signed certificates. You will need
to invoke `wsk` with the `-i` command line argument to bypass
certificate checking.
-First, obtain the IP address of the Kubernetes nodes. If you are
-using minikube, use the command
+## Setting up NodePort on minikube
+
+First, obtain the IP address of the single Kubernetes worker node.
```shell
minikube ip
```
-otherwise use
-```
-kubectl get nodes
-```
+This will return an ip address, for example `192.168.99.100`.
-Next pick an unassigned port (eg 31001) and define mycluster.yaml as
+Next pick an unassigned port (eg 31001) and define `mycluster.yaml` as
```yaml
whisk:
ingress:
@@ -71,18 +68,15 @@ nginx:
httpsNodePort: 31001
```
-## IBM Cloud
-
-### IBM Cloud Lite cluster
+## Setting up NodePort on an IBM Cloud Lite cluster
-The only available ingress method for a Lite cluster is to use a
-NodePort (see above). Obtain the Public IP address of the sole worker
-node by using the command
- ```
+The only available ingress method for an IBM Cloud Lite cluster is to
+use a NodePort. Obtain the Public IP address of the sole worker node
+by using the command
+```shell
bx cs workers <my-cluster>
- ```
-Then define mycluster.yaml as
-
+```
+Then define `mycluster.yaml` as
```yaml
whisk:
ingress:
@@ -94,12 +88,45 @@ nginx:
httpsNodePort: 31001
```
-### IBM Cloud standard cluster
+# Standard
-This type of cluster can support a more advanced ingress style that
-does not use self-signed certificates for TLS termination (you can use
-`wsk` instead of `wsk -i`). You will need to determine the values for
-<domain> and <ibmtlssecret> for your cluster by running the command
+Many cloud providers will support creating a Kubernetes Ingress that
+may offer additional capabilities features such as TLS termination,
+load balancing, and other advanced features. We will call this a
+`standard` ingress and provide a parameterized ingress.yaml as part of
+the Helm chart that will create it using cloud-provider specific
+parameters from your `mycluster.yaml`. Generically, your
+`mycluster.yaml`'s ingress section will look something like:
+```yaml
+whisk:
+ ingress:
+ api_host_name: *<domain>*
+ api_host_port: 443
+ api_host_proto: https
+ type: standard
+ domain: *<domain>*
+ tls:
+ enabled: *<true or false>*
+ secretenabled: *<true or false>*
+ createsecret: *<true or false>*
+ secretname: *<tlssecretname>*
+ *<additional cloud-provider-specific key/value pairs>*
+ annotations:
+ *<optional list of cloud-provider-specific key/value pairs>*
+```
+
+Note that if you can setup an ingress that does not use self-signed
+certificates for TLS termination you will be able to use `wsk` instead
+of `wsk -i` for cli operations.
+
+## IBM Cloud standard cluster
+
+This cluster type does not use self-signed certificates for TLS
+termination and can be configured with additional annotations to
+fine tune ingress performance.
+
+First, determine the values for <domain> and <ibmtlssecret> for
+your cluster by running the command:
```
bx cs cluster-get <mycluster>
```
@@ -118,12 +145,11 @@ Ingress secret: <ibmtlssecret>
Workers: 3
```
-Now define mycluster.yaml as below (substituting the real values for
+Now define `mycluster.yaml` as below (substituting the real values for
`<domain>` and `<ibmtlssecret>`).
```yaml
whisk:
ingress:
- name: ow-ingress
api_host_name: <domain>
api_host_port: 443
api_host_proto: https
@@ -157,9 +183,7 @@ whisk:
```
-## Google Cloud
-
-### Google Cloud with nginx ingress
+## Google Cloud with nginx ingress
This type of installation allows the same benefits as the IBM Cloud standard cluster.
@@ -175,12 +199,11 @@ cat tls.key | base64
cat tls.crt | base64
```
-Now define mycluster.yaml as below:
+Now define `mycluster.yaml` as below:
```yaml
whisk:
ingress:
- name: ow-ingress
api_host_name: <domain>
api_host_port: 443
api_host_proto: https
@@ -200,6 +223,7 @@ whisk:
nginx.ingress.kubernetes.io/proxy-body-size: 0
```
-## Other cloud providers
+## Additional cloud providers
-Please submit Pull Requests with instructions for other cloud providers.
+Please submit Pull Requests with instructions for configuing the
+`standard` ingress for other cloud providers.