HashiCorp Consul Installation Guide

Consul is a service networking platform that provides service discovery, configuration, and segmentation functionality. It enables you to connect and secure services across any runtime platform and public or private cloud.

Prerequisites

• A 64-bit operating system
• Minimum 2GB RAM
• Administrative/sudo privileges
• Network connectivity between nodes (if running in cluster mode)

Installation Instructions

# Add HashiCorp GPG key
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
 
# Add HashiCorp repository
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
 
# Update and install Consul
sudo apt update
sudo apt install consul

Basic Configuration

1. Create Configuration Directory

sudo mkdir -p /etc/consul.d
sudo chown -R consul:consul /etc/consul.d

2. Basic Server Configuration

Create /etc/consul.d/server.hcl:

datacenter = "dc1"
data_dir = "/opt/consul"
client_addr = "0.0.0.0"
ui_config{
  enabled = true
}
 
server = true
bootstrap_expect = 1  # For development only
bind_addr = "{{GetPrivateIP}}"

3. Basic Client Configuration

Create /etc/consul.d/client.hcl:

datacenter = "dc1"
data_dir = "/opt/consul"
server = false
bind_addr = "{{GetPrivateIP}}"
retry_join = ["CONSUL_SERVER_IP"]

Starting Consul

Development Mode

# Start Consul in development mode
consul agent -dev
 
# Access UI
# Visit http://localhost:8500

Production Mode

# Start Consul server
sudo systemctl start consul
 
# Enable Consul to start at boot
sudo systemctl enable consul
 
# Check status
sudo systemctl status consul

Security Configuration

1. Enable ACLs

Add to server configuration:

acl = {
  enabled = true
  default_policy = "deny"
  enable_token_persistence = true
}

2. Initialize ACL System

# Bootstrap ACL system
consul acl bootstrap
 
# Save the generated master token securely

3. Configure TLS

# Generate certificates
consul tls ca create
consul tls cert create -server
 
# Add TLS configuration
verify_incoming = true
verify_outgoing = true
verify_server_hostname = true
ca_file = "consul-agent-ca.pem"
cert_file = "dc1-server-consul-0.pem"
key_file = "dc1-server-consul-0-key.pem"

Service Registration

1. Service Definition

Create /etc/consul.d/web-service.hcl:

service {
  name = "web"
  port = 80
  check {
    http = "http://localhost:80/health"
    interval = "10s"
  }
}

2. Register Service

# Reload Consul configuration
consul reload

Troubleshooting

Common Issues

1. Cluster Formation Issues

   • Check network connectivity
   • Verify server addresses in retry_join
   • Ensure consistent datacenter names

2. Permission Issues

   # Fix data directory permissions
   sudo chown -R consul:consul /opt/consul
   sudo chmod 750 /opt/consul

   Copy

3. Service Discovery Problems

   • Verify service definitions
   • Check DNS configuration
   • Validate health check endpoints

Logging

# Enable debug logging
consul agent -log-level=DEBUG
 
# View logs
sudo journalctl -u consul

Best Practices

1. Production Deployment

   • Use at least 3 servers for high availability
   • Enable ACLs and TLS
   • Implement proper backup strategy

2. Security

   • Use minimal privilege tokens
   • Rotate ACL tokens regularly
   • Secure gossip encryption

3. Monitoring

   • Set up metrics collection
   • Monitor cluster health
   • Configure alerting

Additional Resources

• Official Consul Documentation
• Consul API Reference
• HashiCorp Learn - Consul
• Consul Security Guide