Merge pull request #1442 from aledbf/opentracing-docs

Opentracing docs

controllers/nginx/README.md

@@ -17,6 +17,7 @@ This is an nginx Ingress controller that uses [ConfigMap](https://kubernetes.io/
 * [TCP Services](#exposing-tcp-services)
 * [UDP Services](#exposing-udp-services)
 * [Proxy Protocol](#proxy-protocol)
+* [Opentracing](#opentracing)
 * [NGINX customization](configuration.md)
 * [Custom errors](#custom-errors)
 * [NGINX status page](#nginx-status-page)
@@ -378,6 +379,44 @@ Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/lat
 
 Please check the [proxy-protocol](examples/proxy-protocol/) example
 
+### Opentracing
+
+Using the third party module [rnburn/nginx-opentracing](https://github.com/rnburn/nginx-opentracing) the NGINX ingress controller can configure NGINX to enable [OpenTracing](http://opentracing.io) instrumentation.
+By default this feature is disabled.
+
+To enable the instrumentation we just need to enable the instrumentation in the configuration configmap and set the host where we should send the traces.
+
+In the [aledbf/zipkin-js-example](https://github.com/aledbf/zipkin-js-example) github repository is possible to see a dockerized version of zipkin-js-example with the required Kubernetes descriptors.
+To install the example and the zipkin collector we just need to run:
+
+```
+$ kubectl create -f https://raw.githubusercontent.com/aledbf/zipkin-js-example/kubernetes/kubernetes/zipkin.yaml
+$ kubectl create -f https://raw.githubusercontent.com/aledbf/zipkin-js-example/kubernetes/kubernetes/deployment.yaml
+```
+
+Also we need to configure the NGINX controller configmap with the required values:
+
+```
+apiVersion: v1
+data:
+  enable-opentracing: "true"
+  zipkin-collector-host: zipkin.default.svc.cluster.local
+kind: ConfigMap
+metadata:
+  labels:
+    k8s-app: nginx-ingress-controller
+  name: nginx-custom-configuration
+```
+
+Using curl we can generate some traces:
+```
+$ curl -v http://$(minikube ip)/api -H 'Host: zipkin-js-example'
+$ curl -v http://$(minikube ip)/api -H 'Host: zipkin-js-example'
+```
+
+In the zipkin inteface we can see the details:
+
+![zipkin screenshot](docs/images/zipkin-demo.png "zipkin collector screenshot")
 
 ### Custom errors
 

controllers/nginx/configuration.md

@@ -487,6 +487,17 @@ The default mime type list to compress is: `application/atom+xml application/jav
 
 **bind-address:** Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.
 
+**enable-opentracing:** enables the nginx Opentracing extension https://github.com/rnburn/nginx-opentracing
+Default is "false"
+
+**zipkin-collector-host:** specifies the host to use when uploading traces. It must be a valid URL
+
+**zipkin-collector-port:** specifies the port to use when uploading traces
+Default: 9411
+
+**zipkin-service-name:** specifies the service name to use for any traces created
+Default: nginx
+
 ### Default configuration options
 
 The following table shows the options, the default value and a description.