Skip to content

Consul reference#

Consul is an open-source tool for discovering and configuring services in your network architecture. Specifically, Consul provides the following features:

  • Discovery of services
  • Monitoring of the health of services
  • Key/value storage with a simple HTTP API

Consul Agent#

The Consul Agent exposes a DNS API for easy consumption of data generated by Registrator. The Consul Agent can run either in server or client mode.

When run as a Layer0 Service, the Consul Agent runs in server mode. To ensure the integrity of your data, the service in which you run consul should be scaled to size 3 or greater. A group of several consul deployments is known as a "cluster."

Other Layer0 Services that use Consul will run the Consul Agent in client mode, alongside their application containers. The client is a very lightweight process that registers services, runs health checks, and forwards queries to servers.

Registrator#

Registrator is a tool that automatically registers and deregisters services into a Consul Cluster by inspecting Docker containers as they come online. Container registration is based off of environment variables on the container. Layer0 Services that use Consul will run Registrator alongside their application containers.

Service Configuration#

Layer0 Services that use Consul will need to add the Registrator and Consul Agent definitions to the containerDefinitions section of your Deploys. You must also add the Docker Socket definition to the volumes section of your Deploys.


Registrator Container Definition#

{
    "name": "registrator",
    "image": "gliderlabs/registrator:master",
    "essential": true,
    "links": ["consul-agent"],
    "entrypoint": ["/bin/sh", "-c"],
    "command": ["/bin/registrator -retry-attempts=-1 -retry-interval=30000 -ip $(wget http://169.254.169.254/latest/meta-data/local-ipv4 -q -O -) consul://consul-agent:8500"],
    "memory": 128,
    "mountPoints": [
        {
            "sourceVolume": "dockersocket",
            "containerPath": "/tmp/docker.sock"
        }
    ]
},

Consul Agent Container Definition#

Warning

You must replace <url> with your Layer0 Consul Load Balancer's URL.

{
    "name": "consul-agent",
    "image": "progrium/consul",
    "essential": true,
    "entrypoint": ["/bin/bash", "-c"],
    "command": ["/bin/start -advertise $(wget http://169.254.169.254/latest/meta-data/local-ipv4 -q -O -) -retry-join $EXTERNAL_URL -recursor $UPSTREAM_DNS -retry-interval 30s"],
    "memory": 128,
    "portMappings": [
        {
            "hostPort": 8500,
            "containerPort": 8500
        },
        {
            "hostPort": 53,
            "containerPort": 53,
            "protocol": "udp"
        }
    ],
    "environment": [
        {
            "name": "EXTERNAL_URL",
            "value": "<url>"
    },
    {
            "name": "UPSTREAM_DNS",
            "value": "10.100.0.2"
        }
    ]
},

Environment Variables#

  • EXTERNAL_URL - URL of the consul cluster
  • UPSTREAM_DNS - The DNS server consul-agent queries for DNS entries that it cannot resolve internally (e.g. google.com)
    • The default value for UPSTREAM_DNS assumes you're using the default Layer0 configuration, making your internal DNS endpoint 10.100.0.2. If you are a using a non standard configuration (e.g. installing Layer0 in an existing VPC with a CIDR other than 10.100.0.0/16) please modify this variable accordingly.

Docker Socket Volume Definition#

"volumes": [
    {
        "name": "dockersocket",
        "host": {
                "sourcePath": "/var/run/docker.sock"
        }
    }
],