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.
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.
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.
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_CLIENT_INTERFACE environment variables. Production Docker clusters often have many networking interfaces and this makes it easy to bind to the correct one.
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!
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.
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.
Learn the installation and verification workflow for any Linux distribution that does not include HashiCorp software in its package repository.
Integrating HCP Consul Central with Backstage can enhance your organization’s infrastructure-management capabilities. Here’s how to do it.
Managing multiple clusters of HashiCorp tools can be complicated. Target CLI eases the burden by using context profiles to easily switch between different clusters and environments.