diff --git a/controllers/nginx/README.md b/controllers/nginx/README.md index 1ad2c1027e..9a1e3a4fb9 100644 --- a/controllers/nginx/README.md +++ b/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 diff --git a/controllers/nginx/configuration.md b/controllers/nginx/configuration.md index d94d31c16a..517cea608e 100644 --- a/controllers/nginx/configuration.md +++ b/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. diff --git a/controllers/nginx/docs/images/zipkin-demo.png b/controllers/nginx/docs/images/zipkin-demo.png new file mode 100644 index 0000000000..c83fcf2360 Binary files /dev/null and b/controllers/nginx/docs/images/zipkin-demo.png differ