Official Consul Docker Image

We are pleased to announce the release of our official Docker image for Consul. Consul is a modern datacenter runtime that provides service discovery, configuration, and orchestration capabilities.

The official Docker image makes a development or production cluster just one command away for any Docker-powered clusters. Through the review process, we've worked closely with the folks at Docker to iterate and make an image that's safe, intuitive, and easy to use.

Consul is our first tool to have an official Docker image. We’ll be updating the Docker image alongside all new releases of Consul. More HashiCorp tooling will be distributed as Docker images going forward.

Development and Production

We spent a lot of time and effort to ensure that the single Docker image can be used for both development and production. With just a few different command-line flags, you’re a single docker run consul away from a cluster at home or in a production datacenter.

Consul and Docker for Development

At HashiCorp, we strive for a great out-of-box experience for all our tooling. Our Docker image is no different: we knew that docker run consul would be the first thing people did to try Consul with Docker, so we optimized the defaults for development.

When you run docker run consul, you get a working development Consul server running instantly:

$ docker run consul
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!

This configures Consul to be completely in-memory with default Docker networking and no services exposed to the host. This is perfect for development where you want to test or use the API without having to configure a cluster.

Development mode also starts the Consul web UI on port 8500, giving users a graphical interface to interact with their Consul cluster.

Consul and Docker for Production

To run Consul in production, you just have to docker run consul agent. This will directly run the consul agent command, disable all the development defaults, and enable all the production defaults.

To ensure the Docker image is practical for production, we included a number of features:

• The entry point script automatically sets Consul’s persistent data directory to a location on a volume for easy state management.

• Consul can be configured to bind to an interface or set its client interface by setting CONSUL_BIND_INTERFACE and/or CONSUL_CLIENT_INTERFACE environment variables. Production Docker clusters often have many networking interfaces and this makes it easy to bind to the correct one.

• The CONSUL_LOCAL_CONFIG environment variable allows configuration JSON to be included in the image on the fly without having to compose a new container or mount a volume.

The full documentation covers detailed production topics such as the use of -net=host, techniques for mapping DNS to port 53 on the host, configuring DNS in other containers, and more.

In addition to the Docker Hub documentation, we are working on documentation on Consul’s website which will include many more detailed examples for the various container service discovery tools, so look for that in the coming weeks!

Image Internals

Docker image anatomy is a sensitive subject for many Docker users. We worked closely with Docker and the community to ensure that we built an image using Docker best practices that everyone can be happy with.

The Consul official image is built on top of an Alpine Linux base image to provide a relatively small surface area to secure while still providing a rich enough environment for interactive development use, health check scripts, and watch scripts. The image also includes a base set of CA certificates to make it easy to enable features like Atlas integration out of the box.

The image uses dumb-init to handle reaping child subprocesses and gosu to run as a dedicated consul user. The image’s entry point script configures Consul by default with these two tools so you get a best practices running environment without any additional work.

More to Come

We're excited to have released an official Consul Docker image. We want HashiCorp Docker images to not just be a packaging format, but a full-featured ready-to-run system in and of itself. This, plus the added look and feel requirements for any HashiCorp release caused this to take a bit longer than we had hoped.

The end result is a Docker image that we think is extremely high quality for both development and production. We're also very proud of the quality of documentation for this image, covering in detail both the development and production usage of it.

We've already begun creating images for other HashiCorp products at the HashiCorp Docker Hub repository, including Packer and Terraform. We hope to release official images for more products in the coming months. Please stay tuned as we continue to expand our library of Docker images.