Improve README

README.md

@@ -3,39 +3,43 @@
 
 # NGINX Ingress Controller
 
-This repo provides an implementation of an Ingress controller for NGINX and NGINX Plus. This implementation is different from the NGINX Ingress controller in [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx) repo. See [this doc](docs/nginx-ingress-controllers.md) to find out about the key differences.
+This repo provides an implementation of an Ingress controller for NGINX and NGINX Plus. 
 
-## What is Ingress?
+**Note**: this project is different from the NGINX Ingress controller in [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx) repo. See [this doc](docs/nginx-ingress-controllers.md) to find out about the key differences.
 
-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 for each exposed host name.
+## What is the Ingress?
 
-See the [Ingress User Guide](http://kubernetes.io/docs/user-guide/ingress/) to learn more.
+The Ingress is a Kubernetes resource that lets you configure an HTTP load balancer for applications running on Kubernetes, represented by one or more [Services](https://kubernetes.io/docs/concepts/services-networking/service/). Such a load balancer is necessary to deliver those applications to clients outside of the Kubernetes cluster.
 
-## What is an Ingress Controller?
+The Ingress resource supports the following features:
+* **Content-based routing**:
+    * *Host-based routing*. For example, routing requests with the host header `foo.example.com` to one group of services and the host header `bar.example.com` to another group.
+    * *Path-based routing*. For example, routing requests with the URI that starts with `/serviceA` to service A and requests with the URI that starts with `/serviceB` to service B.
+* **TLS/SSL termination** for each hostname, such as `foo.example.com`.
 
-An Ingress controller is an application that monitors Ingress resources via the Kubernetes API and updates the configuration of a load balancer in case of any changes. Different load balancers require different Ingress controller implementations. Typically, an Ingress controller is deployed as a pod in a cluster. In the case of software load balancers, such as NGINX, an Ingress controller is deployed in a pod along with a load balancer.
+See the [Ingress User Guide](http://kubernetes.io/docs/user-guide/ingress/) to learn more about the Ingress resource.
 
-See https://github.com/kubernetes/contrib/tree/master/ingress/controllers/ to learn more about Ingress controllers and find out about different implementations.
+## What is the Ingress Controller?
+
+The Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer runnning externally. Different load balancers require different Ingress controller implementations. 
+
+In the case of NGINX, the Ingress controller is deployed in a pod along with the load balancer.
 
 ## NGINX Ingress Controller
 
-We provide an Ingress controller for NGINX and NGINX Plus that supports the following Ingress features:
-* SSL termination
-* Path-based rules
-* Multiple host names
+NGINX Ingress controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination.
+
+Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap and Annotations doc](docs/configmap-and-annotations.md) to learn more about the supported features and customization options.
+
+Read [this doc](docs/nginx-plus.md) to learn more about NGINX Ingress controller with NGINX Plus.
+
+## Getting Started
 
-We provide the following extensions to our Ingress controller:
-* [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.
-* [Support for JWTs](examples/jwt) (NGINX Plus only), which allows NGINX Plus to authenticate requests by validating JSON Web Tokens (JWTs).
+1. Install the NGINX Ingress controller using the Kubernetes [manifests](deployments) or the [helm chart](deployments/helm-chart).
+1. Run through the [Cafe example](examples/complete-example) to deploy and configure load balancing for a simple web application.
+1. See additional configuration [examples](examples).
+1. Learn more about all available configuration and customization in the [docs](docs).
 
-Additional extensions as well as a mechanism to customize NGINX configuration are available. See [ConfigMap and Annotations doc](docs/configmap-and-annotations.md).
 
 ## NGINX Ingress Controller Releases
 
@@ -57,34 +61,16 @@ The table below summarizes the options regarding the images, manifests, helm cha
 | Latest stable release | For production use | `nginx/nginx-ingress:1.3.2`, `nginx/nginx-ingress:1.3.2-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/nginx-controller). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/nginx-controller). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/install). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/docs). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/v1.3.2/examples). |
 | Edge | For testing and experimenting | `nginx/nginx-ingress:edge`, `nginx/nginx-ingress:edge-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/build). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/build). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/master/docs). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples). |
 
-## Benefits of Using the Ingress Controller with NGINX Plus
-
-[NGINX Plus](https://www.nginx.com/products/) is a commercial version of NGINX that comes with advanced features and support.
-
-The Ingress controller leverages the advanced features of NGINX Plus, which gives you the following additional benefits:
-
-* **Improved system resources utilization for large-scale deployments**
-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 increase of memory usage during reloads, especially with a high volume of client requests, as well as increased memory usage when load balancing applications with long-lived connections (WebSocket, applications with file uploading/downloading or streaming). As a result, NGINX Plus Ingress controller is better suited for production-ready deployments.
-* **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.
-* **JWTs** NGINX Plus can validate JSON Web Tokens (JWTs), providing a flexible authentication mechanism.
-* **Support** Support from NGINX Inc is available for NGINX Plus Ingress controller.
-
-**Note**: Deployment of the Ingress controller for NGINX Plus requires you to do one extra step: build your own [Docker image](build) using the certificate and key for your subscription.
-The Docker image of the Ingress controller for NGINX is [available on Docker Hub](https://hub.docker.com/r/nginx/nginx-ingress/).
-
-## 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.
+## Contacts
 
-## Advanced Load Balancing/An Alternative Method of Configuration
+We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress controller, please create an issue or send a pull request on Github.
+You can contact us directly via [kubernetes@nginx.com](mailto:kubernetes@nginx.com).
 
-When your requirements go beyond what Ingress and Ingress extensions offer or if you are looking for an alternative method of configuring NGINX, it is possible to use NGINX or NGINX Plus without the Ingress Controller.
+## Contributing
 
-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/).
+If you'd like to contribute to the project, please read our [Contributing guide](CONTRIBUTING.md).
 
-## Contacts
+## Support 
 
-We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress controller, please create an issue or send a pull request on Github.
-You can contact us directly via [kubernetes@nginx.com](mailto:kubernetes@nginx.com).
+For NGINX Plus customers NGINX Ingress controller (when used with NGINX Plus) is covered 
+by the support contract.

docs/nginx-ingress-controllers.md

@@ -8,7 +8,7 @@ If you are unsure about which implementation you are using, check the container
 
 ## The Key Differences
 
-The table below summarizes the key difference between nginxinc/kubernetes-ingress and kubernetes/ingress-nginx Ingress controllers. Note that the table has two columns for the nginxinc/kubernetes-ingress Ingress controller, as it can be used both with NGINX and NGINX Plus
+The table below summarizes the key difference between nginxinc/kubernetes-ingress and kubernetes/ingress-nginx Ingress controllers. Note that the table has two columns for the nginxinc/kubernetes-ingress Ingress controller, as it can be used both with NGINX and NGINX Plus. For more information about nginxinc/kubernetes-ingress with NGINX Plus, read [here](nginx-plus.md). 
 
 | Aspect or Feature | kubernetes/ingress-nginx | nginxinc/kubernetes-ingress with NGINX | nginxinc/kubernetes-ingress with NGINX Plus |
 | --- | --- | --- | --- |

docs/nginx-plus.md

@@ -0,0 +1,15 @@
+# NGINX Ingress Controller with NGINX Plus
+
+NGINX Ingress controller works with both [NGINX](https://nginx.org/) and [NGINX Plus](https://www.nginx.com/products/nginx/) -- a commercial closed source version of NGINX that comes with additional features and support. 
+
+Below are the key characteristics that NGINX Plus brings on top of NGINX into the NGINX Ingress controller:
+* **Additional features**
+    * *Real-time metrics* A number metrics about how NGINX Plus and applications are performing are available through the API or a [built-in dashboard](installation.md#5-access-the-live-activity-monitoring-dashboard--stub_status-page). Optionally, the metrics can be exported to [Prometheus](installation.md#support-for-prometheus-monitoring).
+    * *Additional load balancing methods*. The following additional methods are available: `least_time` and `random two least_time` and their derivatives. See the [documentation](https://nginx.org/en/docs/http/ngx_http_upstream_module.html) for the complete list of load balancing methods.
+    * *Session persistence* The *sticky cookie* method is available. See the [Session Persistence](../examples/session-persistence) example.
+    * *Active health checks*. See the [Support for Active Health Checks](../examples/health-checks) example.
+    * *JWT validation*. See the [Support for JSON Web Tokens (JWTs)](../examples/jwt) example.
+
+    See [ConfigMap and Annotations](configmap-and-annotations.md) doc for the complete list of available NGINX Plus features. Note that such features are configured through annotations that start with `nginx.com`, for example, `nginx.com/health-checks`.
+* **Dynamic reconfiguration** Every time the number of pods of services you expose via an Ingress resource changes, the Ingress controller updates the configuration of the load balancer to reflect those changes. For NGINX, the configuration file must be changed and the configuration subsequently reloaded. For NGINX Plus, the dynamic reconfiguration is utilized, which allows NGINX Plus to be updated on-the-fly without reloading the configuration. This prevents increase of memory usage during reloads, especially with a high volume of client requests, as well as increased memory usage when load balancing applications with long-lived connections (WebSocket, applications with file uploading/downloading or streaming).
+* **Commercial support** Support from NGINX Inc is available for NGINX Plus Ingress controller.