Consul on Docker

Access containers

You can access a containerized Consul datacenter in several different ways.

Docker exec

You can execute Consul commands directly inside of your Consul containers using docker exec.

$ docker exec <container_id> consul members
Node      Address          Status  Type    Build   Protocol  DC   Partition  Segment
server-1  172.17.0.2:8301  alive   server  1.14.3  2         dc1  default    <all>
client-1  172.17.0.3:8301  alive   client  1.14.3  2         dc1  default    <default>

Docker exec attach

You can also issue commands inside of your container by opening an interactive shell and using the Consul binary included in the container.

$ docker exec -it <container_id> /bin/sh
# consul members
Node      Address          Status  Type    Build   Protocol  DC   Partition  Segment
server-1  172.17.0.2:8301  alive   server  1.14.3  2         dc1  default    <all>
client-1  172.17.0.3:8301  alive   client  1.14.3  2         dc1  default    <default>

Local Consul binary

If you have a local Consul binary in your PATH, you can export the CONSUL_HTTP_ADDR environment variable to point to the HTTP address of a Consul server container.

$ export CONSUL_HTTP_ADDR=<consul_server_container_ip>:8500

This approach runs the Consul binary on your local machine instead of the container, but still communicates with the Consul server running in the container.

$ consul members
Node      Address          Status  Type    Build   Protocol  DC   Partition  Segment
server-1  172.17.0.2:8301  alive   server  1.21.2  2         dc1  default    <all>
client-1  172.17.0.3:8301  alive   client  1.21.2  2         dc1  default    <default>

Reload configuration

To do an in-memory reload, send a SIGHUP to the container.

$ docker kill --signal=HUP <container_id>

Consul Autopilot

As long as there are enough servers in the datacenter to maintain consensus, Consul's autopilot feature removes servers whose containers were stopped.

Autopilot's settings are configurable, and we recommend the following configurations when running Consul on Docker. For more information, check the Autopilot configuration reference.

• cleanup_dead_servers should be set to true to make sure that a stopped container is removed from the datacenter.
• last_contact_threshold should be reasonably small, so that dead servers are removed quickly.
• server_stabilization_time should be sufficiently large (on the order of several seconds) so that unstable servers are not added to the datacenter until they stabilize.

Backup data with snapshots

You can back-up your Consul datacenter using the consul snapshot command.

$ docker exec <container_id> consul snapshot save backup.snap

This will leave the backup.snap snapshot file inside of your container. If you are not saving your snapshot to a persistent volume then you will need to use docker cp to move your snapshot to a location outside of your container.

$ docker cp <container_id>:backup.snap ./

To save backups automatically, use the Consul Enterprise snapshot agent. Consul Enterprise's snapshot agent also can save snapshots to Amazon S3 and Azure Blob Storage.

Environment variables

The Consul Docker image supports passing multiple environment variables with the -e flag.

• CONSUL_CLIENT_INTERFACE specifies the name of the interface on which Consul exposes DNS, gRPC, and HTTP APIs.

• CONSUL_CLIENT_ADDRESS specifies the address Consul binds to for client traffic, such as DNS, gRPC, and HTTP APIs.

• CONSUL_BIND_INTERFACE specifies the interface Consul uses for internal Consul cluster communication.

• CONSUL_BIND_ADDRESS specifies the address Consul binds to for internal Consul cluster communication.

• CONSUL_DATA_DIR specifies the directory where Consul stores data to persist across container restarts. The default value is /consul/data.

• CONSUL_ALLOW_PRIVILEGED_PORTS is a boolean value. When set to true, setcap runs on the Consul binary to allow binding to privileged ports.

• CONSUL_CONFIG_DIR allows you to specify a container directory for additional configuration files that the Consul agent loads. The default location is the /consul/config directory.

• CONSUL_LOCAL_CONFIG passes a JSON string of configuration options to the Consul agent.

The following is an example how to define a multi-line configuration using CONSUL_LOCAL_CONFIG.

$ docker run -d \
  -e CONSUL_LOCAL_CONFIG='{
  "datacenter":"us_west",
  "server":true,
  "enable_debug":true
  }' \
  hashicorp/consul:latest \
  consul agent -server -bootstrap-expect=1 -data-dir=/consul/data