Introducing the Rancher Metadata Service for Docker

Gray Calendar Icon Published: October 5, 2015
Gray Calendar Icon Updated: September 11, 2019

Rancher has come a long way since its early versions, and is becoming quite good at managing Docker applications and deploying complex services. That said, as your stacks move from simple demos to production applications you quickly realize that you need to know more about your Docker environment when you configure and upgrade container services. To address that problem, we recently introduced a container metadata service with Rancher v0.38.0, similar to Amazon’s Instance Metadata service.

How do you interact the Rancher Metadata service?

It is pretty simple, any container that is launched on the Rancher network or with `io.rancher.container.dns: true` in host networking mode has access to the service. Just use curl or any HTTP client to call the metadata url http://rancher-metadata/2015-07-25/ and you will see keys that are available in a command line like interfaces with your next choices. Here is an example of retrieving a containers name with cURL. metadata-demo-toplevel metadata-demo-self metadata-demo-container-info metadata-demo-container-name If you are processing the data in a programming language, you can pass the ‘Accept: application/json’ header to get the response in a JSON document. For those of you that are Confd users, we have developed a Rancher Metadata backend to Confd. We’ve submitted it upstream, but a binary is available from Rancher in the rancher/confd fork in the meantime.

What does the Metadata service provide?

A lot really, within a container the most useful information is found under the /self link, but the API can provide information about other services, stacks, and containers in an environment. The best way to understand how to use the service is through an example. Zookeeper, is always a challenging service to tackle because it requires unique IDs to be tied to IP addresses across the cluster. Though the next version of Zookeeper will allow dynamic configuration of nodes, which confd and metadata will be a great solution. In the current stable release 3.4.6 however, we can use confd to generate the following. I’ll also give the equivalent curl commands for those using scripts or other languages. The example assumes the zookeeper servers will be launched in a single service and use Rancher networking. If you would like to use the compose files in your own environment, you can find them in the rancher/compose-templates repo. For those unfamiliar with confd, it is a powerful light weight configuration management tool created by Kelsey Hightower. It watches key value stores such as etcd, consul and now Rancher Metadata. When things change confd updates templates with the new values. Note, Metadata is a versioned API. When using confd we recommend using the --prefix /, in this case we will use 2015-07-25, on the command line. You can use `latest` as the version, but it is best to use a specific version. First setup the myid confd toml file. This will define how we create the myid file for Zookeeper which contains the unique server id.

prefix = "/self/container"
src = "myid.tmpl"
dest = "/var/lib/zookeeper/myid"
owner = "root"
mode = "0644"
keys = [

Here we are telling confd to query the metadata service at the following path:


The prefixes defined on the command line and in this file make it so the keys used in the template file are shorter. The create_index is the order number of which the container was launched in the service, i.e. 2 means it was the second container launched in the service. They are always increasing and non-repeating within a service. The equivalent curl command for the value above is:

curl -H ‘Accept: application/json’ http://rancher-metadata/2015-07-25/self/container/create_index

Now we create the template file for the myid file for Zookeeper.

## zk myid file
{{getv "/create_index"}}

Confd just uses golang text templates, and all this is saying is to put the value of key /create_index in the file. Note we only needed to use the shortened key value because of our use of prefixes. That part was simple, now let’s look at the more complex zoo.cfg file. First, we create the zoo.cfg.toml file like so:

src = "zoo.cfg.tmpl"
dest = "/opt/zookeeper/conf/zoo.cfg"
owner = "root"
mode = "0644"
keys = [

Here we are getting the following values:

  • /2015-07-25/self/service/containers
  • /2015-07-25/containers

The /self/service/containers key is all of the containers in “my” service. In this case the Zookeeper service. The /2015-07-25/containers path gets all containers in the environment. Now lets see how we use those values in the template file, the tricky part is to get the entries for the servers in the format:


To accomplish this with Rancher Metadata you can use the following confd template file:

{{range ls "/self/service/containers"}}{{ $containerName := getv (printf "/self/service/containers/%s" .)}}
server.{{getv (printf "/containers/%s/create_index" $containerName)}}={{getv (printf "/containers/%s/primary_ip" $containerName)}}:2888:3888{{end}}

The interesting parts are in the {{}} braces. What we are doing is looping through all of the containers in the service. Then we look up the the primary IP addresses and create_indexes of each container. To retrieve the data using the equivalent curl commands use: curl -H ‘Accept: application/json’ http://rancher-metadata/2015-07-25/self/service/containers curl -H ‘Accept: application/json’ http://rancher-metadata/2015-07-25/containers/ This is just the tip of the iceberg of what you can accomplish around Docker application management with Rancher Metadata. Soon, support will be added for user defined key value pairs. Giving users a single endpoint to get configuration data to bootstrap containers. In this month’s online meetup we’ll be demonstrating the new Meta Data service along with best practices for container monitoring. You can register below.

Get started with Rancher