Merge pull request #181 from nginxinc/update-doc

Update docs and examples

Author: pleshakov

README.md

@@ -30,20 +30,23 @@ We provide the following extensions to our Ingress controller:
 * [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).
 
-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) the Ingress controller and [customize](examples/customization) the NGINX configuration.
+Additional extensions as well as a mechanism to customize NGINX configuration are available. See [examples/customization](examples/customization).
 
 ## 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:
 
-* **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.
+* **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](nginx-controller) 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/nginxdemos/nginx-ingress/).
@@ -52,21 +55,12 @@ The Docker image of the Ingress controller for NGINX is [available on Docker Hub
 
 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/An Alternative Method of Configuration 
 
-When your requirements go beyond what Ingress offers, you can use NGINX and
-NGINX Plus without the Ingress Controller.
+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.
 
 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
-
-This is the preview version of the Ingress controller.
-
-## 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 controller, please create an issue or send a pull request on Github.

examples/customization/README.md

@@ -35,6 +35,8 @@ The table below summarizes some of the options. More options (extensions) are av
 | `nginx.org/location-snippets` | `location-snippets` | Sets a custom snippet in location context. | N/A |
 | `nginx.org/server-snippets` | `server-snippets` | Sets a custom snippet in server context. | N/A |
 | `nginx.org/lb-method` | `lb-method` | Sets the [load balancing method](https://www.nginx.com/resources/admin-guide/load-balancer/#method). The default `""` specifies the round-robin method. | `""` |
+| `nginx.org/listen-ports` | N/A | Configures HTTP ports that NGINX will listen on. | `[80]` |
+| `nginx.org/listen-ports-ssl` | N/A | Configures HTTPS ports that NGINX will listen on. | `[443]` |
 
 ## Using ConfigMaps
 

examples/daemon-set/README.md

@@ -2,25 +2,29 @@
 
 You can deploy the NGINX or NGINX Plus controller as a [Daemon Set](http://kubernetes.io/docs/admin/daemons/). This allows you to deploy the controller on all or select nodes of your cluster.
 
-To deploy the NGINX controller, run:
-```
-  $ kubectl create -f nginx-ingress.yaml
-```
+1. Create a Secret with an SSL certificate and key for the default server of NGINX/NGINX Plus. It is recommended that you use your own certificate and key. 
+    ```
+    $ kubectl create -f default-server-secret.yaml
+    ```
 
-To deploy the NGINX Plus controller, run:
-```
-  $ kubectl create -f nginx-plus-ingress.yaml
-```
+1. To deploy the NGINX controller, run:
+    ```
+      $ kubectl create -f nginx-ingress.yaml
+    ```
+    To deploy the NGINX Plus controller, run:
+    ```
+      $ kubectl create -f nginx-plus-ingress.yaml
+    ```
 
 Once deployed, by default, a controller pod is running on every node of the cluster. The pods are accessible through ports 80 and 443 of each node they get scheduled on.
 
 Optionally, you can choose to run the controller pods on only select nodes. To accomplish this:
 1. Add a label to each node on which you want to run a controller pod. For example:
-  ```
-  kubectl label node node-1 role=nginx-ingress
-  kubectl label node node-2 role=nginx-ingress
-  ```
-  where *node-1* and *node-2* are some nodes of your cluster.
+    ```
+    kubectl label node node-1 role=nginx-ingress
+    kubectl label node node-2 role=nginx-ingress
+    ```
+    where *node-1* and *node-2* are some nodes of your cluster.
 
 1. Uncomment the **nodeSelector** related lines (11-12) in the corresponding daemon set yaml file and specify a label to use to select nodes (`role=nginx-ingress` in this example).
 

examples/daemon-set/default-server-secret.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: default-server-secret
+type: Opaque
+data:
+  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURTVENDQWpHZ0F3SUJBZ0lKQUs5L2NDNWZocDJHTUEwR0NTcUdTSWIzRFFFQkJRVUFNQ0V4SHpBZEJnTlYKQkFNVEZrNUhTVTVZU1c1bmNtVnpjME52Ym5SeWIyeHNaWEl3SGhjTk1UY3dPRE14TVRBeE16UTRXaGNOTVRndwpPRE14TVRBeE16UTRXakFoTVI4d0hRWURWUVFERXhaT1IwbE9XRWx1WjNKbGMzTkRiMjUwY205c2JHVnlNSUlCCklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF0bXhhMDhadExIaWxleWhOUWN5OUl4ankKWTBYdy9CRmZvM3duMDRsSXRoaGRxbkZ3NTZIVG1RVjIvbnEyRUxMdTNoejNjc3Urc3M5WFEzL3BrbXVwTEE5TApuaVVRZFVNcER4VlE1VFFKRW5CanJ5aXc4RWFlcEp4NUNCYVB5V3ZSZkpPb0pFSW56ZmNaYnE4OEVmQklYOHdtClFCa0xlcnFTVmRYWjBXR3FINVVQVlVZMVBqZXBqSXAyZ0NvbDRMUjM1aHRlSk9OMmZVTEF6cmRGMDBDT092WGsKUzgwRGw5eHdoUkVwVWVySGNuNXZod3BJazNkY3FNS3BxWTY2elF3dStMcFJEM3ZVWjR0eC9VYnlUdStkMkdhVwpWaG1RLy85RmtzUzVBS1d2ZXkrK3pPUTFDZTAxNzhDU0hRYXRDaWFuU2lTT3lwakZtTUZ0N1Mra25pbm9Xd0lECkFRQUJvNEdETUlHQU1CMEdBMVVkRGdRV0JCUlFUODVHRzV6a0QxV3FNSzZvOW8xWWFqUVBXVEJSQmdOVkhTTUUKU2pCSWdCUlFUODVHRzV6a0QxV3FNSzZvOW8xWWFqUVBXYUVscENNd0lURWZNQjBHQTFVRUF4TVdUa2RKVGxoSgpibWR5WlhOelEyOXVkSEp2Ykd4bGNvSUpBSzkvY0M1ZmhwMkdNQXdHQTFVZEV3UUZNQU1CQWY4d0RRWUpLb1pJCmh2Y05BUUVGQlFBRGdnRUJBSTIxcXpDN0lIYTEzblNvRkMxVFdtSUZydjQ2L2hRSFRjSFhxazRXZW16Z3VwVW8Kdmp0R05DVFlaR1VtL3RZY1FobDZvOXVJZlV5N3NlVS9OeWVCWHpOdGFiQUczQUIzanREVUJySy9xeVJ5cDZjRApIL0MzNmd5VFh3OGJxYVdOSzg0VGhYOVg2MFVFNVE2NzFUQUJMbk9paEhKUVVxTHdRc1VkdEkxRHBQb1BOOFlWCm5YQVl1RXJKWTVRckhzdHZoOFNZM2xoV3BSOWJ0eTVySldweUhIM3NDL1lHN2lFam5TUXp2LzdhK3cxTW1RQ0EKTk1wQnFvdzJKZkdveklyV2JvcFBVR2lmZ2szSjBKT24rcnA4RDRVc1lvNEo4Y3RvVk5qUFdmeU9zczB6ZWZ2aQpyUmVEUDdJOXc5THF1eERIRUhzeUpMUXN0MzNlQWlna1FBQU9zMUU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
+  tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdG14YTA4WnRMSGlsZXloTlFjeTlJeGp5WTBYdy9CRmZvM3duMDRsSXRoaGRxbkZ3CjU2SFRtUVYyL25xMkVMTHUzaHozY3N1K3NzOVhRMy9wa211cExBOUxuaVVRZFVNcER4VlE1VFFKRW5CanJ5aXcKOEVhZXBKeDVDQmFQeVd2UmZKT29KRUluemZjWmJxODhFZkJJWDh3bVFCa0xlcnFTVmRYWjBXR3FINVVQVlVZMQpQamVwaklwMmdDb2w0TFIzNWh0ZUpPTjJmVUxBenJkRjAwQ09PdlhrUzgwRGw5eHdoUkVwVWVySGNuNXZod3BJCmszZGNxTUtwcVk2NnpRd3UrTHBSRDN2VVo0dHgvVWJ5VHUrZDJHYVdWaG1RLy85RmtzUzVBS1d2ZXkrK3pPUTEKQ2UwMTc4Q1NIUWF0Q2lhblNpU095cGpGbU1GdDdTK2tuaW5vV3dJREFRQUJBb0lCQVFDQ002UkFNd2dKRGJOTwp5OTBZY2NFdEk4a2RBZmFXY3ZBSUI3MkZSaDhYbVJ5QllxWnJMUjJSd2t6RUpXRjlXYmtUM3lqZVRuMjFzamRlCmZoVi81RWZDb3NnZC8rWlhTN0FxaTlSSlEzS1dMcEYzbTF0dW8zam5sS2J1RnV4Wm54TE9EN1dhNjN6dGpNZ2kKTUFCMzdVQTYzOE1OVE5MY3JmMTBOa1paSTVRQkpYWWNPRk1ueDJ4MXVLRkU5RHQzWUEzbE9nOWNGdmFJTFpEQQo3WTVHVDlmUXdJQS92OGRWRU1DTkNiSzI1b1dnRG90WUdZaUhiYm1hUk9DTkRpNzVQZFpkM2daQ3IxUHFPWEZHCkJaVEh1L3Q4OXMwV1QyUkpNV2ljVW5XV0oyVHhmRWU1YUQ4R0JjRzEyN0pkamxLSitWZCtHWmxvODVYYVBvdnUKTVFxek1nbUJBb0dCQU9IS1pGbzVnSVkzL0J3aElCZ2RGUytnOG1GK21JTWpxSGVMN1NFSTNYL0UzWjhJd0syUgpmTTVFRUpTZnlETFpDVkNlSS8veWhBOUF6dG9Dam12TzdjMUxJT3kwR3k5dFlJVHlYY0xQNWNBWitBTkJCRExFCitYZkx5SE9KVXBDM2o4RFRZWDF0RENiUGJ5UFZTZENUNHNKT2JrNDVZVXQ3a3pEYTVHSFpsL3hqQW9HQkFNN1UKayt6TE5zbFQ2azJaakJaZW81YUdoMUNCSVV4bzNFNVpGYUZWR2lyMSs4NVlkVDdXVEpublJ6K0l6QXBMMmRqZApPZjVlQS9wa3JVNExMeGMzVVNEYjJwczJuT1hQd1p1OWdqRTM3aml0SUFRd3BHL3FiamQ3Y1ZaR2hlUkQyK3l4ClptTWU3c1BCZEVmcldmK1REYU9lT3B4L2RRcnFyTEc2UXo1ZHlQbXBBb0dBVmsyZ0VnU01wY0RjY253TzRtaXIKWW1zb2VpK0RhQXpISmZxc0JzWjJzNUd5REVteUxDWENDSzFua1FlSjVEV2xJOVZ1ZVRSZldkMHhzNDdxbFRhaApHcWt1eW9zRklSbXpuTjF2RFRtZDNkR1BSTjhqRmF6SWxndWtjTlQ2WkNwbG5oU3QzTjFEbWNvTDl5eGRiSVk2ClZIN2FGcmhFQWpBWDBNSzZMTlNaRFhVQ2dZQlRYc3JWeTBBbFBTY1g2b25XUm9Xb1drZlhBb1lhbDdZZCtyakcKVkZoODhyUnlnNk9YRmFqQTdNSUNjVERXQWFjcFRGdGhGaUtDWHV5Z3BjOXdpMEt2ZlErTU95SlpYRHBOZmNFcAo5OEtWbyt0ZzVQNlRnaXExUUpQNTArbUtqblBxMzhOR3R5UkZVZ2grS1BjWkZ2eUxkRzlwdjlLOCtNVnR5b2ZxCmJzRmhLUUtCZ0NvcEg5Wm95MjJBNStLcnJYZmQ0VXRBcndjN0dVanFUT1hhTzgyd3FpU0hZMndPTGdkWWw0L3kKSDJEYy9EMWxmWS9GL09sckNMZDNpL0lLc0wxNG13R2dxODZRdDhxeTIwcWw4RFNyWG91TmhsQTJmL1ZUTk1SMAp2OXAwU1JrQjI2UVYyUitndnNVYk9xb1lhMlVQVkNuQW9QeTYwTXlBaVJUR3cyeTExbm9lCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

examples/daemon-set/nginx-ingress.yaml

@@ -19,8 +19,14 @@ spec:
           hostPort: 80
         - containerPort: 443
           hostPort: 443
+        env:
+        - name: POD_NAMESPACE
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.namespace
         # Uncomment the lines below to enable extensive logging and/or customization of
         # NGINX configuration with configmaps
-        #args:
+        args:
          #- -v=3
-         #- -nginx-configmaps=default/nginx-config
+         #- -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
+          - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret

examples/daemon-set/nginx-plus-ingress.yaml

@@ -19,9 +19,15 @@ spec:
           hostPort: 80
         - containerPort: 443
           hostPort: 443
+      env:
+        - name: POD_NAMESPACE
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.namespace
         # Uncomment the lines below to enable extensive logging and/or customization of
         # NGINX configuration with configmaps
         args:
           - -nginx-plus
          #- -v=3
-         #- -nginx-configmaps=default/nginx-config
+         #- -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
+          - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret

examples/jwt/README.md

@@ -0,0 +1,46 @@
+# Support for JSON Web Tokens (JWTs)
+
+NGINX Plus supports validating JWTs with [ngx_http_auth_jwt_module](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). 
+
+The Ingress controller provides the following 4 annotations for configuring JWT validation:
+
+* Required: ```nginx.com/jwt-key: "secret"``` -- specifies a Secret resource with keys for validating JWTs. The keys must be stored in the `jwk` data field.
+* Optional: ```nginx.com/jwt-realm: "realm"``` -- specifies a realm.
+* Optional: ```nginx.com/jwt-token: "token"``` -- specifies a variable that contains JSON Web Token. By default, a JWT is expected in the `Authorization` header as a Bearer Token. 
+* Optional: ```nginx.com/jwt-login-url: "url"``` -- specifies a URL to which a client is redirected in case of an invalid or missing JWT.
+
+## Example
+
+In the following example we enable JWT validation for the cafe-ingress Ingress:
+```yaml
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: cafe-ingress
+  annotations:
+    nginx.com/jwt-key: "cafe-jwk" 
+    nginx.com/jwt-realm: "Cafe App"  
+    nginx.com/jwt-token: "$cookie_auth_token"
+    nginx.com/jwt-login-url: "https://login.example.com"
+spec:
+  tls:
+  - hosts:
+    - cafe.example.com
+    secretName: cafe-secret
+  rules:
+  - host: cafe.example.com
+    http:
+      paths:
+      - path: /tea
+        backend:
+          serviceName: tea-svc
+          servicePort: 80
+      - path: /coffee
+        backend:
+          serviceName: coffee-svc
+          servicePort: 80
+```
+* The keys must be deployed separately in the Secret `cafe-jwk`.
+* The realm is  `Cafe App`.
+* The token is extracted from the `auth_token` cookie.
+* The login URL is `https://login.example.com`. 

nginx-controller/README.md

@@ -15,6 +15,7 @@ There are other cases when you need to build your own image. For example if you
 Before you can build the image, make sure that the following software is installed on your machine:
 * [Docker](https://www.docker.com/products/docker)
 * [GNU Make](https://www.gnu.org/software/make/)
+* [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server.
 
 Additionally, for NGINX Plus, you must have the NGINX Plus license. If you don't have one, you can sign up for a [free 30-day trial](https://www.nginx.com/free-trial-request/).  Put the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) of your license inside this folder.