Updated documentation

pleshakov · pleshakov · commit b3d985a1206b · 2016-11-09T19:17:44.000+03:00
diff --git a/README.md b/README.md
@@ -4,11 +4,11 @@ This repo provides implementations of an Ingress controller for NGINX and NGINX
 
 ## What is Ingress?
 
-An Ingress is a Kubernetes resource that lets you configure an HTTP load balancer for your Kubernetes services. Such a load balancer usually exposes your services to the clients outside of your Kubernetes cluster. An Ingress resource supports:
+An Ingress is a Kubernetes resource that lets you configure an HTTP load balancer for your Kubernetes services. Such a load balancer usually exposes your services to clients outside of your Kubernetes cluster. An Ingress resource supports:
 * Exposing services:
     * Via custom URLs (for example, service A at the URL `/serviceA` and service B at the URL `/serviceB`).
     * Via multiple host names (for example, `foo.example.com` for one group of services and `bar.example.com` for another group).
-* Configuring SSL termination per each exposed host name.
+* Configuring SSL termination for each exposed host name.
 
 See the [Ingress User Guide](http://kubernetes.io/docs/user-guide/ingress/) to learn more.
 
@@ -25,41 +25,49 @@ We provide Ingress controllers for NGINX and NGINX Plus that support the followi
 * Path-based rules
 * Multiple host names
 
-Additionally, we provide a mechanism to customize the NGINX configuration.
+We provide the following extensions to our Ingress controllers:
+* [Websocket](examples/websocket), which allows you to load balance Websocket applications.
+* [SSL Services](examples/ssl-services), which allows you to load balance HTTPS applications.
+* [Rewrites](examples/rewrites), which allows you to rewrite the URI of a request before sending it to the application.
+* [Session Persistence](examples/session-persistence) (NGINX Plus only), which guarantees that all the requests from the same client are always passed to the same backend container.
 
-Refer to the [examples folder](examples) to find out how to [deploy](examples/complete-example) NGINX Ingress Controllers and [customize](examples/customization) the NGINX configuration.
+Additionally, we provide a mechanism to customize the NGINX configuration. Refer to the [examples folder](examples) to find out how to [deploy](examples/complete-example) NGINX Ingress controllers and [customize](examples/customization) the NGINX configuration.
 
-## Difference between NGINX and NGINX Plus controllers
+## Difference between NGINX and NGINX Plus Controllers
 
 [NGINX Plus](https://www.nginx.com/products/) is a commercial version of NGINX that comes with advanced features and support.
 
-Deployment of the NGINX Plus Ingress Controller requires you to do one extra step: build your own [Docker image](nginx-plus-controller) using the certificate and key of your license.
+Deployment of the NGINX Plus Ingress controller requires you to do one extra step: build your own [Docker image](nginx-plus-controller) using the certificate and key for your subscription.
 The Docker image of the NGINX Ingress controller is [available on Docker Hub](https://hub.docker.com/r/nginxdemos/nginx-ingress/).
 
-The NGINX Plus Ingress Controller leverages the advanced features of NGINX Plus, which gives you the following additional benefits:
+The NGINX Plus Ingress controller leverages the advanced features of NGINX Plus, which gives you the following additional benefits:
 
-* **Reduced Number of Configuration Reloads**
-Every time the number of pods of services you expose via Ingress changes, the Ingress controller updates the configuration of NGINX to reflect those changes. For open source NGINX software, the configuration file must be changed followed by the configuration reload. For NGINX Plus, we use the [on-the-fly reconfiguration](https://www.nginx.com/products/on-the-fly-reconfiguration/) feature, which allows you to update NGINX Plus on-the-fly without reloading the configuration. This prevents a potential increase of memory usage and overall system overloading, which could occur with frequent configuration reloads.
-* **Real-time Statistics**
+* **Reduced number of configuration reloads**
+Every time the number of pods of services you expose via Ingress changes, the Ingress controller updates the configuration of NGINX to reflect those changes. For the open source NGINX software, the configuration file must be changed and the configuration reloaded. For NGINX Plus, the [on-the-fly reconfiguration](https://www.nginx.com/products/on-the-fly-reconfiguration/) feature is utilized, which allows NGINX Plus to be updated on-the-fly without reloading the configuration. This prevents a potential increase of memory usage and overall system overloading, which could occur with too frequent configuration reloads.
+* **Real-time statistics**
 NGINX Plus provides you with [advanced statistics](https://www.nginx.com/products/live-activity-monitoring/), which you can access either through the API or via the built-in dashboard. This can give you insights into how NGINX Plus and your applications are performing.
-* **Session Persistence** When enabled, NGINX Plus makes sure that all the requests from the same client are always passed to the same backend container using the *sticky cookie* method. Refer to the [session persistence examples](examples/session-persistence) to find out how to configure it.
+* **Session persistence** When enabled, NGINX Plus makes sure that all the requests from the same client are always passed to the same backend container using the *sticky cookie* method. Refer to the [session persistence examples](examples/session-persistence) to find out how to configure it.
 
 ## Using Multiple Ingress Controllers
 
 You can run multiple Ingress controllers at the same time. For example, if your Kubernetes cluster is deployed in cloud, you can run the NGINX controller and the corresponding cloud HTTP load balancing controller. Refer to the [example](examples/multiple-ingress-controllers) to learn more.
 
-## Advanced load balancing (beyond Ingress)
+## Advanced Load Balancing (Beyond Ingress)
 
 When your requirements go beyond what Ingress offers, you can use NGINX and
 NGINX Plus without the Ingress Controller.
 
 NGINX Plus comes with a [DNS-based dynamic reconfiguration feature](https://www.nginx.com/blog/dns-service-discovery-nginx-plus/), which lets you keep the list of the endpoints of your services in sync with NGINX Plus. Read more about how to setup NGINX Plus this way in [Load Balancing Kubernetes Services with NGINX Plus](https://www.nginx.com/blog/load-balancing-kubernetes-services-nginx-plus/).
 
-## Production status
+## Production Status
 
-The status of the NGINX Ingress controllers is currently experimental.
+This is the preview version of the Ingress controllers.
+
+## Support
+
+Support from the [NGINX Professional Services Team](https://www.nginx.com/services/) is available when using the NGINX Plus Ingress controller.
 
 ## Contacts
 
-We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress Controllers, please create an issue or send a pull request on Github.
-You can contact us directly via [kubernetes@nginx.com](mailto:kubernetes@nginx.com). Commercial support is available.
+We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress controllers, please create an issue or send a pull request on Github.
+You can contact us directly via [kubernetes@nginx.com](mailto:kubernetes@nginx.com).
diff --git a/examples/complete-example/README.md b/examples/complete-example/README.md
@@ -2,12 +2,29 @@
 
 ## Prerequisites
 
-* Kubernetes 1.2 (TLS support for Ingress has been added in 1.2)
+* Kubernetes 1.2 and later (TLS support for Ingress has been added in 1.2)
 * For NGINX Plus:
-  * Build and make available in your cluster the [NGINX Plus](../../nginx-plus-controller) Controller image
+  * Build and make available in your cluster the [NGINX Plus](../../nginx-plus-controller) controller image
   * Update the container image field in the ```nginx-plus-ingress-rc.yaml``` file accordingly.
 
-## Running the example
+## Running the Example
+
+## 1. Deploy the Ingress Controller
+
+1. Create either an NGINX or an NGINX Plus Ingress controller:
+  ```
+  $ kubectl create -f nginx-ingress-rc.yaml
+  ```
+  or
+  ```
+  $ kubectl create -f nginx-plus-ingress-rc.yaml
+  ```
+
+1. The controller container exposes ports 80, 443 (and 8080 for NGINX Plus )
+on the host it is running on. Make sure to add a firewall rule to allow incoming traffic
+though these ports.
+
+## 2. Deploy the Cafe Application
 
 1. Create the coffee and the tea services and replication controllers:
 
@@ -17,6 +34,9 @@
   $ kubectl create -f coffee-rc.yaml
   $ kubectl create -f coffee-svc.yaml
   ```
+
+## 3. Configure Load Balancing
+
 1. Create a secret with an SSL certificate and a key:
   ```
   $ kubectl create -f cafe-secret.yaml
@@ -27,18 +47,7 @@
   $ kubectl create -f cafe-ingress.yaml
   ```
 
-1. Create either an NGINX or an NGINX Plus Ingress Controller:
-  ```
-  $ kubectl create -f nginx-ingress-rc.yaml
-  ```
-  or
-  ```
-  $ kubectl create -f nginx-plus-ingress-rc.yaml
-  ```
-
-1. The Controller container exposes ports 80, 443 (and 8080 for NGINX Plus )
-on the host it is running on. Make sure to add a firewall rule to allow incoming traffic
-though these ports.
+## 4. Test the Application
 
 1. Find out the external IP address of the node where the controller is running:
   ```
diff --git a/examples/customization/README.md b/examples/customization/README.md
@@ -10,7 +10,7 @@ NGINX directives:
 
 ## Using ConfigMaps
 
-1. Make sure that you specify the configmaps resource to use when you start an Ingress Controller.
+1. Make sure that you specify the configmaps resource to use when you start an Ingress controller.
 For example, `-nginx-configmaps=default/nginx-config`, where we specify
 the config map to use with the following format: `<namespace>/<name>`. See [nginx-ingress-rc.yaml](../complete-example/nginx-ingress-rc.yaml) or
 [nginx-plus-ingress-rc.yaml](../complete-example/nginx-plus-ingress-rc.yaml) files.
diff --git a/examples/rewrites/README.md b/examples/rewrites/README.md
@@ -1,11 +1,17 @@
 # Rewrites Support
 
-To load balance an application that requires rewrites with NGINX Ingress controllers, you need to add the **nginx.org/rewrites** annotation to your Ingress resource definition. The annotation specifies which services need rewrites. The annotation syntax is as follows:
+You can configure NGINX to rewrite the URI of a request before sending it to the application. For example, `/tea/green` can be rewritten to `/green`.
+
+## Syntax
+
+To configure URI rewriting you need to add the **nginx.org/rewrites** annotation to your Ingress resource definition. The annotation syntax is as follows:
 ```
-nginx.org/rewrites: "serviceName=service1 rewrite=/rewrite1/[;serviceName=service2 rewrite=/rewrite2/;...]"
+nginx.org/rewrites: "serviceName=service1 rewrite=rewrite1[;serviceName=service2 rewrite=rewrite2;...]"
 ```
 
-In the following example we load balance two applications, which require rewrites:
+## Example
+
+In the following example we load balance two applications that require URI rewriting:
 ```yaml
 apiVersion: extensions/v1beta1
 kind: Ingress
@@ -28,14 +34,11 @@ spec:
           servicePort: 80
 ```
 
-Requests to the tea service are rewritten as follows:
-
-* /tea -> gets redirected to /tea/ first
-* /tea/ -> /
-* /tea/abc -> /abc
+Below are the examples of how the URI of requests to the *tea-svc* are rewritten (Note that the `/tea` requests are redirected to `/tea/`).
+* `/tea/` -> `/`
+* `/tea/abc` -> `/abc`
 
-Requests to the coffee service are rewritten as follows:
+Below are the examples of how the URI of requests to the *coffee-svc* are rewritten (Note that the `/coffee` requests are redirected to `/coffee/`).
 
-* /coffee -> gets redirected to /coffee/ first
-* /coffee/ -> /beans/
-* /coffee/abc -> /beans/abc
+* `/coffee/` -> `/beans/`
+* `/coffee/abc` -> `/beans/abc`
diff --git a/nginx-controller/README.md b/nginx-controller/README.md
@@ -27,17 +27,18 @@ We build the image using the make utility. The **Makefile** we provide has the f
 
 The **Makefile** contains the following main variables, which you should customize (either by changing the Makefile or by overriding the variables in the make command):
 * **PREFIX** -- the name of the image. For example, `nginx-ingress`
-* **TAG** -- the tag added to the image. For example, `0.3`
-* **PUSH_TO_GCR** . If you’re running your Kubernetes in GCE and using Google Container Registry, make sure that `PUSH_TO_GCR = 1`. This means using the `gcloud docker push` command to push the image, which is convenient when pushing images to GCR. By default, the variable is unset and the regular `docker push` command is used to push the image to the registry.
+* **VERSION** -- the current version of the controller.
+* **TAG** -- the tag added to the image. It's set to the value of the `VERSION` variable by default.
+* **PUSH_TO_GCR**. If you’re running your Kubernetes in GCE and using Google Container Registry, make sure that `PUSH_TO_GCR = 1`. This means using the `gcloud docker push` command to push the image, which is convenient when pushing images to GCR. By default, the variable is unset and the regular `docker push` command is used to push the image to the registry.
 
 Let’s create the controller binary, build an image and push the image to the private registry. Make sure to run the `docker login` command first to login to the registry. If you’re using Google Container Registry, as we are in our example here, you don’t need to use the docker command to login. However, make sure you’re logged into the gcloud tool (using the `gcloud auth login` command). 
 
 In this folder we run the following commands in the shell:
 ```
 $ make clean
-$ make PREFIX=gcr.io/my-k8s-project/nginx-ingress TAG=0.3 PUSH_TO_GCR=1
+$ make PREFIX=gcr.io/my-k8s-project/nginx-ingress TAG=latest PUSH_TO_GCR=1
 ```
 
-Where **my-k8s-project** is the name of the GCE project where we run our Kubernetes cluster. As the result, the image -- **gcr.io/my-k8s-project/nginx-ingress:0.3** --  is built and pushed to the registry.
+Where **my-k8s-project** is the name of the GCE project where we run our Kubernetes cluster. As the result, the image -- **gcr.io/my-k8s-project/nginx-ingress:latest** --  is built and pushed to the registry.
 
 By default, to compile the controller we use the [golang](https://hub.docker.com/_/golang/) container that we run as part of the building process. If you want to compile the controller using your local golang environment, specify `BUILD_IN_CONTAINER=0` when you run the make command.
diff --git a/nginx-plus-controller/README.md b/nginx-plus-controller/README.md
@@ -25,17 +25,18 @@ We build the image using the make utility. The **Makefile** we provide has the f
 
 The **Makefile** contains the following main variables, which you should customize (either by changing the Makefile or by overriding the variables in the make command):
 * **PREFIX** -- the name of the image. For example, `nginx-plus-ingress`
-* **TAG** -- the tag added to the image. For example, `0.3`
+* **VERSION** -- the current version of the controller.
+* **TAG** -- the tag added to the image. It's set to the value of the `VERSION` variable by default.
 * **PUSH_TO_GCR** . If you’re running your Kubernetes in GCE and using Google Container Registry, make sure that `PUSH_TO_GCR = 1`. This means using the `gcloud docker push` command to push the image, which is convenient when pushing images to GCR. By default, the variable is unset and the regular `docker push` command is used to push the image to the registry.
 
 Let’s create the controller binary, build an image and push the image to the private registry. Make sure to run the `docker login` command first to login to the registry. If you’re using Google Container Registry, as we are in our example here, you don’t need to use the docker command to login. However, make sure you’re logged into the gcloud tool (using the `gcloud auth login` command). 
 
 In this folder we run the following commands in the shell:
 ```
 $ make clean
-$ make PREFIX=gcr.io/my-k8s-project/nginx-plus-ingress TAG=0.3 PUSH_TO_GCR=1
+$ make PREFIX=gcr.io/my-k8s-project/nginx-plus-ingress TAG=latest PUSH_TO_GCR=1
 ```
 
-Where **my-k8s-project** is the name of the GCE project where we run our Kubernetes cluster. As the result, the image -- **gcr.io/my-k8s-project/nginx-plus-ingress:0.3** --  is built and pushed to the registry.
+Where **my-k8s-project** is the name of the GCE project where we run our Kubernetes cluster. As the result, the image -- **gcr.io/my-k8s-project/nginx-plus-ingress:latest** --  is built and pushed to the registry.
 
 By default, to compile the controller we use the [golang](https://hub.docker.com/_/golang/) container that we run as part of the building process. If you want to compile the controller using your local golang environment, specify `BUILD_IN_CONTAINER=0` when you run the make command.
