Merge pull request DataDog#789 from DataDog/haissam/service-discovery-new-features

hkaj · web-flow · commit e24ba70af6a3 · 2016-07-08T11:30:25.000+02:00
Update service discovery doc w/ new features
diff --git a/content/guides/servicediscovery.md b/content/guides/servicediscovery.md
@@ -21,7 +21,7 @@ If no configuration template is defined in the store for an image, the Agent wil
 
 ## How to set it up
 
-To use Service Discovery, the only thing you need to do is to define the configuration templates for the images you want to monitor, in a key-value store on top of the Agent.
+To use Service Discovery, you simply need to define the configuration templates for the images you want to monitor, in a key-value store on top of the Agent.
 
 Here is the structure of a configuration template:
 
@@ -42,10 +42,54 @@ Here is the structure of a configuration template:
         ...
 
 
+You also need to configure the Datadog Agents of the environment to enable service discovery using this store as a backend. To do so, edit the datadog.conf file to modify these options as needed:
 
-### Setup NGINX
+    # For now only docker is supported so you just need to un-comment this line.
+    # service_discovery_backend: docker
+    #
+    # Define which key/value store must be used to look for configuration templates.
+    # Default is etcd. Consul is also supported.
+    # sd_config_backend: etcd
+
+    # Settings for connecting to the backend. These are the default, edit them if you run a different config.
+    # sd_backend_host: 127.0.0.1
+    # sd_backend_port: 4001
+
+    # By default, the agent will look for the configuration templates under the
+    # `/datadog/check_configs` key in the back-end.
+    # If you wish otherwise, uncomment this option and modify its value.
+    # sd_template_dir: /datadog/check_configs
+
+
+### Running and configuring the Agent in a container
+
+The above settings can be passed to the dd-agent container through the following environment variables:
+
+    SD_BACKEND <-> service_discovery_backend
+    SD_CONFIG_BACKEND <-> sd_config_backend
+    SD_BACKEND_HOST <-> sd_backend_host
+    SD_BACKEND_PORT <-> sd_backend_port
+    SD_TEMPLATE_DIR <-> sd_template_dir
 
-The default NGINX image doesn't have the stub_status_module enabled, so we first need to build an image named that configures the /nginx_status endpoint.
+Available tags:
+
+    datadog/docker-dd-agent:latest (has the Docker check preconfigured)
+    datadog/docker-dd-agent:kubernetes (has the Docker and Kubernetes checks preconfigured)
+
+example:
+
+    docker run -d --name dd-agent \
+     -v /var/run/docker.sock:/var/run/docker.sock \
+     -v /proc/:/host/proc/:ro -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
+     -e API_KEY=[YOUR_API_KEY] -e SD_CONFIG_BACKEND=etcd \
+     -e SD_BACKEND=docker -e SD_BACKEND_HOST=[YOUR_ETCD_IP] \
+     -e SD_BACKEND_PORT=[YOUR_ETCD_PORT] \
+     datadog/docker-dd-agent:kubernetes
+
+
+### Example: setting up NGINX monitoring
+
+The default NGINX image doesn't have the stub_status_module enabled, so we first need to build an image (named `custom-nginx` here) that configures the /nginx_status endpoint.
 
 Setup a configuration template in the form of a few keys in a key/value store the Agent can reach. Here is an example using etcd:
 
@@ -69,26 +113,9 @@ If the Agent is configured to use consul instead:
 
 *Notice the format of template variables: `%%host%%`. For now host and port are supported on every platform. Kubernetes users can also use the `tags` variable that collects relevant tags like the pod name and node name from the Kubernetes API. Support for more variables and platforms is planned, and feature requests are welcome.*
 
-Finally you need to configure all the Agents of the environment to enable service discovery using this store as a backend. To do so, simply edit the datadog.conf file to modify these options:
-
-    # For now only docker is supported so you just need to un-comment this line.
-    # service_discovery_backend: docker
-    #
-    # Define which key/value store must be used to look for configuration templates.
-    # Default is etcd. Consul is also supported.
-    # sd_config_backend: etcd
-
-    # Settings for connecting to the backend. These are the default, edit them if you run a different config.
-    # sd_backend_host: 127.0.0.1
-    # sd_backend_port: 4001
-
-    # By default, the agent will look for the configuration templates under the
-    # `/datadog/check_configs` key in the back-end.
-    # If you wish otherwise, uncomment this option and modify its value.
-    # sd_template_dir: /datadog/check_configs
-
 Now every Agent will be able to detect an nginx instance running on its host and setup a check for it automatically. No need to restart the Agent every time the container starts or stops, and no other configuration file to modify.
 
+
 ### Template variables
 
 To automate the resolution of parameters like the host IP address or its port, the agent uses template variables in this format: `%%variable%%`.
@@ -99,6 +126,13 @@ Let's take the example of the port variable: a rabbitmq container with the manag
 
 The default management port for the rabbitmq image is `15672` with index 4 in the list (starting from 0), so the template variable needs to look like `%%port_4%%`.
 
+It is also possible starting from version `5.8.3` of the agent to use keys as a suffix in case a dictionary is expected. This is particularly useful to select an IP address for a container that has several networks attached.
+The format is the same: `%%variable_key%%`.
+
+As an example if the rabbitmq container mentioned above is available over two networks `bridge` and `swarm`, using `%%host_swarm%%` will pick the IP address from the swarm network.
+Note that for the `host` variable if several networks are found and no key is passed the agent attempts to use the default `bridge` network.
+
+
 ### Configuring multiple checks for the same image
 
 Sometimes enabling several checks on a single container is needed. For instance if you run a Java service that provides an HTTP API, using the HTTP check and the JMX integration at the same time makes perfect sense. To declare that in templates, simply add elements to the `check_names`, `init_configs`, and `instances lists`. These elements will be matched together based on their index in their respective lists.
@@ -119,29 +153,25 @@ In the previous example of the custom nginx image, adding http_check would look
         {"nginx_status_url": "http://%25%25host%25%25/nginx_status/", "tags": ["env:production"]}, \
         {"name": "Test service", "url": "http://%25%25host%25%25/test_endpoint", "timeout": 1}]'
 
-### Running and configuring the Agent in a container
 
-The above settings can be passed to the dd-agent container through the following environment variables:
+### Monitoring your custom container
 
-    SD_BACKEND <-> service_discovery_backend
-    SD_CONFIG_BACKEND <-> sd_config_backend
-    SD_BACKEND_HOST <-> sd_backend_host
-    SD_BACKEND_PORT <-> sd_backend_port
-    SD_TEMPLATE_DIR <-> sd_template_dir
+Service discovery works with any image—one important note though is that for the `%%port%%` variable to be interpolated, the current version needs the container to expose the targeted port. See the NGINX Dockerfile for reference.
 
-Available tags:
 
-    datadog/docker-dd-agent:latest (has the Docker check preconfigured)
-    datadog/docker-dd-agent:kubernetes (has the Docker and Kubernetes checks preconfigured)
+### Image name format in the configuration store
 
-example:
+Before version `5.8.3` of the agent it was required to truncate the image name to its minimum. i.e. for the image `quay.io/coreos/etcd:latest` the key in the configuration store needed to be `datadog/check_configs/etcd/...`
 
-    docker run -d --name dd-agent -h `hostname` -v /var/run/docker.sock:/var/run/docker.sock -v /proc/:/host/proc/:ro -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro -e API_KEY=[YOUR_API_KEY] -e SD_CONFIG_BACKEND=etcd -e SD_BACKEND=docker -e SD_BACKEND_HOST=[YOUR_ETCD_IP] -e SD_BACKEND_PORT=[YOUR_ETCD_PORT] datadog/docker-dd-agent:kubernetes
+To make configuration more precise we now use the complete image identifier in the key. So the agent will look in `datadog/check_configs/quay.io/coreos/etcd:latest/...`, and fallback to the old format if no template was found to ensure backward compatibility.
 
 
-### Monitoring your custom container
+#### Using Docker label to specify the template path
+
+In case you need to match different templates with containers running the same image, it is also possible starting with `5.8.3` to define explicitly which path the agent should look for in the configuration store to find a template using the `com.datadoghq.sd.check.id` label.
+
+For example, if a container has this label configured as `com.datadoghq.sd.check.id: foobar`, it will look for a configuration template in the store under the key `datadog/check_configs/foobar/...`.
 
-Service discovery works with any image—one important note though is that for the `%%port%%` variable to be interpolated, the current version needs the container to expose the targeted port. See the NGINX Dockerfile for reference.
 
 ### Kubernetes users
 
@@ -153,9 +183,10 @@ Once the cluster is running, simply use the K/V store service IP address and por
 
 Then write your configuration templates, and let the Agent detect your running pods and take care of re-configuring checks.
 
+
 #### Examples
 
-Following is an example of how to setup templates for an NGINX, PostgreSQL stack. The example will use etcd as the configuration store and suppose that the etcd cluster is deployed as a service in kubernetes with the IP address 10.0.65.98.
+Following is an example of how to setup templates for an NGINX, PostgreSQL stack. The example will use etcd as the configuration store.
 
 #### NGINX
 
