Merge pull request #109 from nginxinc/doc-updates

Add documentation for new features

Author: pleshakov

examples/customization/README.md

@@ -13,13 +13,22 @@ The table below summarizes some of the options. More options (extensions) are av
 | `nginx.org/proxy-buffers` | `proxy-buffers` | Sets the value of the [proxy_buffers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. |
 | `nginx.org/proxy-buffer-size` | `proxy-buffer-size` | Sets the value of the [proxy_buffer_size](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive | Depends on the platform. |
 | `nginx.org/proxy-max-temp-file-size` | `proxy-max-temp-file-size` | Sets the value of the  [proxy_max_temp_file_size](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | `1024m` |
+| `nginx.org/proxy-hide-headers` | `proxy-hide-headers` | Sets the value of one or more  [proxy_hide_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directives. Example: `"nginx.org/proxy-hide-headers": "header-a,header-b"` | N/A |
+| `nginx.org/proxy-pass-headers` | `proxy-pass-headers` | Sets the value of one or more   [proxy_pass_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directives. Example: `"nginx.org/proxy-pass-headers": "header-a,header-b"` | N/A |
 | N/A | `server-names-hash-bucket-size` | Sets the value of the [server_names_hash_max_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | Depends on the size of the processor’s cache line. |
 | N/A | `server-names-hash-max-size` | Sets the value of the [server_names_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | `512` |
 | `nginx.org/http2` | `http2` | Enables HTTP/2 in servers with SSL enabled. To support HTTP/2 for Chrome users, use the provided controller image based on the alpine Linux. It includes OpenSSL with ALPN support, [necessary for Chrome users](https://www.nginx.com/blog/supporting-http2-google-chrome-users/). | `False` |
 | N/A | `log-format` | Sets the custom [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format).  | See the [template file](../../nginx-controller/nginx/nginx.conf.tmpl). |  
 | `nginx.org/hsts` | `hsts` | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/): the HSTS header is added to the responses from backends. The `preload` directive is included in the header. | `False` |
 | `nginx.org/hsts-max-age` | `hsts-max-age` | Sets the value of the `max-age` directive of the HSTS header. | `2592000` (1 month) |
 | `nginx.org/hsts-include-subdomains` | `hsts-include-subdomains` | Adds the `includeSubDomains` directive to the HSTS header. | `False`|
+| N/A | `ssl-protocols` | Sets the value of the [ssl_protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | `TLSv1 TLSv1.1 TLSv1.2`|
+| N/A | `ssl-prefer-server-cipher` | Enables or disables the [ssl_prefer_server_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | `False`|
+| N/A | `ssl-ciphers` | Sets the value of the [ssl_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | `HIGH:!aNULL:!MD5`|
+| N/A | `ssl-dhparam-file` | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file.  | N/A|
+| N/A | `set-real-ip-from` | Sets the value of the [set_real_ip_from](http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A |
+| N/A | `real-ip-header` | Sets the value of the [real_ip_header](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | `X-Real-IP`|
+| N/A | `real-ip-recursive` | Enables or disables the [real_ip_recursive](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | `False`|
 
 ## Using ConfigMaps
 

examples/customization/nginx-config.yaml

@@ -5,6 +5,8 @@ metadata:
 data:
   proxy-connect-timeout: "10s" # default is "60s". See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout
   proxy-read-timeout: "10s" # default is "60s". See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout
+  proxy-hide-headers: "header-a,header-b" # No default. Sets the value of one or more proxy_hide_header directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header
+  proxy-pass-headers: "header-a,header-b" # No default. Sets the value of one or more proxy_pass_header directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header
   client-max-body-size: "2m" # default is "1m". See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
   server-names-hash-bucket-size: "64" # default value depends on the size of the processor’s cache line. See http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size
   server-names-hash-max-size: "1024" # default is "512". See http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size
@@ -18,3 +20,14 @@ data:
   hsts: "True" # default is "False". Enables HTTP Strict Transport Security (HSTS): the HSTS header is added to the responses from backends. See https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
   hsts-max-age: "31536000" # default is 2592000 (1 month).
   hsts-include-subdomains: "True" # default is "False".
+  ssl-protocols: "TLSv1.2" # default is "TLSv1 TLSv1.1 TLSv1.2". See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols
+  ssl-prefer-server-cipher: "True" # default is "False". Enables or disables the ssl_prefer_server_ciphers directive. See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers
+  ssl-ciphers: "HIGH:!aNULL:!MD5" # default is "HIGH:!aNULL:!MD5". See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers
+  ssl-dhparam-file: |
+    -----BEGIN DH PARAMETERS-----
+    ...
+    -----END DH PARAMETERS-----
+  # Sets the content of the dhparam file. The controller will create the file and set the value of the ssl_dhparam directive with the path of the file. Also see http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam
+  set-real-ip-from: "192.168.192.168" # No default. Sets the value of the set_real_ip_from directive. See http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from
+  real-ip-header: "proxy_protocol" # default is X-Real-IP. Sets the value of the real_ip_header directive. http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header
+  real-ip-recursive: "True" # default is "False". Enables or disables the real_ip_recursive directive. See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive

examples/proxy-protocol/README.md

@@ -0,0 +1,30 @@
+# PROXY Protocol
+
+Proxies and load balancers, such as HAProxy or ELB, can pass the client's information (the IP address and the port) to the next proxy or load balancer via the PROXY Protocol. To enable NGINX Ingress controller to receive that information, use the `proxy-protocol` ConfigMaps configuration key as well as the `real-ip-header` and the `set-real-ip-from` keys. Once you enable the PROXY Protocol, it is enabled for every Ingress resource.
+
+## Syntax
+
+The `proxy-protocol` key syntax is as follows:
+```
+proxy-protocol: "True | False"
+```
+
+Additionally, you must configure the following keys:
+* **real-ip-header**: Set its value to `proxy_protocol`.
+* **set-real-ip-from**: Set its value to the IP address or the subnet of the proxy or the load balancer. See http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from
+
+## Example
+
+In the example below we configure the PROXY Protocol via a ConfigMaps resource. The IP address of the proxy which is in front of the Ingress controller is `192.168.192.168`.
+
+```yaml
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: nginx-config
+data:
+  proxy-protocol: "True"
+  real-ip-header: "proxy_protocol"
+  set-real-ip-from: "192.168.192.168"
+```
+After we create the ConfigMaps resource, in the NGINX configuration the client's IP address is available via the `$remote_addr` variable. By default, NGINX Ingress controller logs the value of this variable and also passes the value to the backend service in the `X-Real-IP` header.