HashiCorp Consul

intermediate

Service mesh and service discovery with key-value store.

Overview

HashiCorp Consul is a service networking platform that provides service discovery, health checking, key-value storage, and service mesh capabilities across cloud and on-premises environments. Originally developed by HashiCorp in 2014, Consul has become a cornerstone tool for microservices architectures, enabling applications to discover and connect to services without hardcoded network locations. Its distributed architecture supports multi-datacenter deployments with automatic failover and strong consistency guarantees through the Raft consensus protocol. This single-node Consul deployment creates a complete service discovery and configuration management platform with an integrated web UI and DNS interface. The configuration bootstraps a Consul server in development mode, exposing both HTTP API endpoints for programmatic access and UDP DNS services for traditional service discovery patterns. The setup includes persistent storage for the key-value store and service catalog, making it suitable for development environments and small production workloads. Development teams building microservices, platform engineers implementing service mesh architectures, and infrastructure teams managing distributed applications will find this deployment valuable for centralizing service registration and discovery. The combination of Consul's service catalog, health checking system, and configuration storage eliminates the need for separate service discovery tools while providing a foundation for more advanced service mesh features like traffic routing and security policies.

Key Features

HTTP and DNS service discovery interfaces with automatic health checking
Distributed key-value store with strong consistency using Raft consensus
Web-based UI for service catalog visualization and KV store management
Service health monitoring with configurable check intervals and timeouts
Multi-datacenter federation support with WAN gossip protocol
Service mesh capabilities with Connect for mTLS and traffic policies
ACL system for fine-grained access control and security policies
Service intentions for defining allowed communication patterns

Common Use Cases

1Microservices service discovery replacing hardcoded service endpoints
2Centralized configuration management for application settings and feature flags
3Service mesh implementation with automatic mTLS between services
4Health checking and monitoring for distributed application components
5Multi-region application deployments with cross-datacenter service discovery
6API gateway integration for dynamic upstream service resolution
7Database connection string and secrets management through KV store

Prerequisites

Minimum 512MB RAM available for Consul server operations
Ports 8500 (HTTP) and 8600 (DNS) available and not in use
Basic understanding of service discovery concepts and REST APIs
Familiarity with JSON configuration for service registration
Network access for inter-service communication if using service mesh features

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  consul: 
3    image: hashicorp/consul:latest
4    container_name: consul
5    restart: unless-stopped
6    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
7    ports: 
8      - "8500:8500"
9      - "8600:8600/udp"
10    volumes: 
11      - consul_data:/consul/data
12    environment: 
13      CONSUL_BIND_INTERFACE: eth0
14
15volumes: 
16  consul_data:

.env Template

.env

1# Configure for production with proper ACLs

Usage Notes

1Docs: https://developer.hashicorp.com/consul/docs
2Access UI at http://localhost:8500
3DNS service discovery on UDP port 8600 (dig @localhost -p 8600 myservice.service.consul)
4Register services via HTTP API, config files, or service mesh sidecar
5KV store: consul kv put/get for configuration management
6Enable ACLs for production: consul acl bootstrap

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  consul:
5    image: hashicorp/consul:latest
6    container_name: consul
7    restart: unless-stopped
8    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
9    ports:
10      - "8500:8500"
11      - "8600:8600/udp"
12    volumes:
13      - consul_data:/consul/data
14    environment:
15      CONSUL_BIND_INTERFACE: eth0
16
17volumes:
18  consul_data:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# Configure for production with proper ACLs
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/consul/run | bash

Troubleshooting

Consul agent not starting: Check if ports 8500 or 8600 are already in use by other services
Services not discoverable via DNS: Verify UDP port 8600 is accessible and configure DNS queries with proper service.consul suffix
Web UI showing 'No services' after registration: Ensure service definitions include proper health check configurations and endpoints are reachable
Key-value operations failing: Confirm consul_data volume has proper write permissions and sufficient disk space
High memory usage in development: Reduce log level from default INFO to WARN using CONSUL_LOG_LEVEL environment variable
Connection refused errors: Verify CONSUL_BIND_INTERFACE matches container network interface or use 0.0.0.0 for all interfaces

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

consul

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download