Update docs

Author: pleshakov

README.md

@@ -21,7 +21,7 @@ See the [Ingress User Guide](http://kubernetes.io/docs/user-guide/ingress/) to l
 
 ## 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. 
+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 running 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.
 
@@ -31,12 +31,16 @@ NGINX Ingress controller works with both NGINX and NGINX Plus and supports the s
 
 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.
 
+As an alternative to the Ingress, NGINX Ingress controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute Resources doc](docs/virtualserver-and-virtualserverroute.md).
+
 Read [this doc](docs/nginx-plus.md) to learn more about NGINX Ingress controller with NGINX Plus.
 
 ## Getting Started
 
 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. Configure load balancing for a simple web application:
+    * Use the Ingress resource. See the [Cafe example](examples/complete-example).
+    * Or the VirtualServer resource. See the [Basic configuration](examples-of-custom-resources/basic-configuration) example.
 1. See additional configuration [examples](examples).
 1. Learn more about all available configuration and customization in the [docs](docs).
 

docs/custom-annotations.md

@@ -1,10 +1,10 @@
 # Custom Annotations
 
-Custom annotations enable you to quickly extend the Ingress Controller to support many advanced features of NGINX, such as rate limiting, caching, etc.
+Custom annotations enable you to quickly extend the Ingress resource to support many advanced features of NGINX, such as rate limiting, caching, etc.
 
 ## What are Custom Annotations
 
-NGINX Ingress Controller supports a number of annotations that fine tune NGINX configuration (for example, connection timeouts) or enable additional features (for example, JWT validation). The complete list of annotations is available [here](configmap-and-annotations.md).
+NGINX Ingress Controller supports a number of annotations for the Ingress resource that fine tune NGINX configuration (for example, connection timeouts) or enable additional features (for example, JWT validation). The complete list of annotations is available [here](configmap-and-annotations.md).
 
 The annotations are provided only for the most common features and use cases, meaning that not every NGINX feature or a customization option is available through the annotations. Additionally, even if an annotation is available, it might not give you the satisfactory level of control of a particular NGINX feature. 
 

docs/nginx-ingress-controllers.md

@@ -16,16 +16,19 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres
 | Authors | Kubernetes community | NGINX Inc and community |  NGINX Inc and community |
 | NGINX version | [Custom](https://github.com/kubernetes/ingress-nginx/tree/master/images/nginx) NGINX build that includes several third-party modules | NGINX official mainline [build](https://github.com/nginxinc/docker-nginx) | NGINX Plus |
 | Commercial support | N/A | N/A | Included |
-| **Load balancing configuration** |
-| Merging Ingress rules with the same host | Supported | Supported | Supported |
+| **Load balancing configuration via the Ingress resource** |
+| Merging Ingress rules with the same host | Supported | Supported via [Mergeable Ingresses](../examples/mergeable-ingress-types) | Supported via [Mergeable Ingresses](../examples/mergeable-ingress-types) |
 | HTTP load balancing extensions - Annotations | See the [supported annotations](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md) | See the [supported annotations](configmap-and-annotations.md) | See the [supported annotations](configmap-and-annotations.md)|
 | HTTP load balancing extensions -- ConfigMap | See the [supported ConfigMap keys](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md) | See the [supported ConfigMap keys](configmap-and-annotations.md) | See the [supported ConfigMap keys](configmap-and-annotations.md) |
 | TCP/UDP | Supported via a ConfigMap | Supported via a ConfigMap with native NGINX configuration | Supported via a ConfigMap with native NGINX configuration |
 | Websocket  | Supported | Supported via an [annotation](../examples/websocket) | Supported via an [annotation](../examples/websocket) |
 | TCP SSL Passthrough | Supported via a ConfigMap | Not supported | Not supported |
 | JWT validation | Not supported | Not supported | Supported |
 | Session persistence | Supported via a third-party module | Not supported | Supported |
+| Canary testing (by header, cookie, weight) | Supported via annotations | Supported via custom resources | Supported via custom resources |
 | Configuration templates *1 | See the [template](https://github.com/kubernetes/ingress-nginx/blob/master/rootfs/etc/nginx/template/nginx.tmpl) | See the [templates](../internal/configs/version1) | See the [templates](../internal/configs/version1) |
+| **Load balancing configuration via Custom Resources** |
+| HTTP load balancing | Not supported | See [VirtualServer and VirtualServerRoute](virtualserver-and-virtualserverroute.md) resources. | See [VirtualServer and VirtualServerRoute](virtualserver-and-virtualserverroute.md) resources. |
 | **Deployment** |
 | Command-line arguments *2 | See the [arguments](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/cli-arguments.md) | See the [arguments](cli-arguments.md) | See the [arguments](cli-arguments.md) |
 | TLS certificate and key for the default server | Required as a command-line argument/ auto-generated | Required as a command-line argument | Required as a command-line argument |

docs/troubleshooting.md

@@ -10,6 +10,7 @@ The table below categories some potential problems with the Ingress Controller y
 | ------------ | ----------- | ------- | -------------- |
 | Start | The Ingress Controller fails to start. | Check the logs. | Misconfigured RBAC, a missing default server TLS Secret. |
 | Ingress Resource and Annotations | The configuration is not applied. | Check the events of the Ingress resource, check the logs, check the generated config. | Invalid values of annotations. |
+| VirtualServer and VirtualServerRoute Resources | The configuration is not applied. | Check the events of the VirtualServer and VirtualServerRoutes, check the logs, check the generated config. | VirtualServer and VirtualServerRoute weren't enabled during the installation. |
 ConfigMap Keys | The configuration is not applied. | Check the events of the ConfigMap, check the logs, check the generated config. | Invalid values of ConfigMap keys. |
 | NGINX | NGINX responds with unexpected responses. | Check the logs, check the generated config, check the live activity dashboard (NGINX Plus only), run NGINX in the debug mode. | Unhealthy backend pods, a misconfigured backend service. |
 
@@ -46,6 +47,29 @@ Events:
 ```
 Note how in the events section we have a Normal event with the AddedOrUpdated reason informing us that the configuration was successfully applied.
 
+### Checking the Events of a VirtualServer and VirtualServerRoute Resources
+
+After you create or update a VirtualServer resource, you can immediately check if the NGINX configuration for that  resource was successfully applied by NGINX:
+```
+$ kubectl describe vs cafe
+. . .
+Events:
+  Type    Reason          Age   From                      Message
+  ----    ------          ----  ----                      -------
+  Normal  AddedOrUpdated  16s   nginx-ingress-controller  Configuration for default/cafe was added or updated
+```
+Note how in the events section we have a Normal event with the AddedOrUpdated reason informing us that the configuration was successfully applied.
+
+Checking the events of a VirtualServerRoute is similar:
+```
+$ kubectl describe vsr coffee 
+. . .
+Events:
+  Type     Reason                 Age   From                      Message
+  ----     ------                 ----  ----                      -------
+  Normal   AddedOrUpdated         1m    nginx-ingress-controller  Configuration for default/coffee was added or updated
+```
+
 ### Checking the Events of the ConfigMap Resource
 
 After you update the [ConfigMap](configmap-and-annotations.md) resource, you can immediately check if the configuration was successfully applied by NGINX:
@@ -64,7 +88,7 @@ Note how in the events section we have a Normal event with the Updated reason in
 
 ### Checking the Generated Config
 
-For each Ingress resource, the Ingress Controller generates a corresponding NGINX configuration file in the `/etc/nginx/conf.d` folder. Additionally, the Ingress Controller generates the main configuration file `/etc/nginx/nginx.conf`, which includes all the configurations files from `/etc/nginx/conf.d`.
+For each Ingress/VirtualServer resource, the Ingress Controller generates a corresponding NGINX configuration file in the `/etc/nginx/conf.d` folder. Additionally, the Ingress Controller generates the main configuration file `/etc/nginx/nginx.conf`, which includes all the configurations files from `/etc/nginx/conf.d`. The config of a VirtualServerRoute resource is located in the configuration file of the VirtualServer that references the resource.
 
 You can view the content of the main configuration file by running:
 ```

examples/custom-annotations/README.md

@@ -1,6 +1,6 @@
 # Custom Annotations
 
-Custom annotations enable you to quickly extend the Ingress Controller to support many advanced features of NGINX, such as rate limiting, caching, etc.
+Custom annotations enable you to quickly extend the Ingress resource to support many advanced features of NGINX, such as rate limiting, caching, etc.
 
 Let's create a set of custom annotations to support [rate-limiting](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html):
 * `custom.nginx.org/rate-limiting` - enables rate-limiting.