Skip to main content

​
Overview

This template provides a production‑ready HashiCorp Consul instance as a Monk runnable. You can:
  • Run it directly to get a managed Consul container with sensible defaults
  • Inherit it in your own runnable to seamlessly add service discovery and configuration management to your infrastructure
Consul is a service networking solution to automate network configurations, discover services, and enable secure connectivity across any cloud or runtime. It provides service discovery, health checking, key/value storage, and multi-datacenter support.

​
What this template manages

  • Consul container (consul image, configurable tag)
  • Web UI and HTTP API on port 8500
  • Service discovery and health checking
  • Key/value store
  • DNS interface on port 8600
  • Optional persistent volumes for data

​
Quick start (run directly)

  1. Load templates
monk load MANIFEST
  1. Run Consul with defaults
monk run consul/node
  1. Access the web interface
Once started, access the Consul web UI at http://localhost:8500.

​
Configuration

The template provides both base and node configurations. You can extend the template with your own variables or environment settings when inheriting. The base template uses sensible defaults and can be customized via inheritance: 
namespace: myapp
service-discovery:
  defines: runnable
  inherits: consul/node
  containers:
    consul:
      image-tag: "1.15"              # specify Consul version
      environment:
        - CONSUL_BIND_INTERFACE=eth0
        - CONSUL_CLIENT_INTERFACE=eth0
Data is persisted under ${monk-volume-path}/consul/node on the host.

​
Available templates

  • consul/base - Base Consul configuration
  • consul/node - Consul node (inherits from base)
Inherit the Consul runnable in your service mesh or microservices infrastructure. Example: 
namespace: myapp
service-discovery:
  defines: runnable
  inherits: consul/node
  variables:
    consul-datacenter:
      value: "production"
    consul-node-name:
      value: <- `${monk-id}-consul`

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    consul:
      runnable: service-discovery
      service: consul
  variables:
    consul-address:
      value: <- connection-hostname("consul")
Then run your application group: 
monk load MANIFEST
monk run myapp/api

​
Ports and connectivity

  • Service: consul on TCP port 8500 (HTTP API and Web UI)
  • DNS interface: UDP/TCP port 8600
  • Serf LAN: TCP/UDP port 8301
  • Serf WAN: TCP/UDP port 8302
  • Server RPC: TCP port 8300
  • From other runnables in the same process group, use connection-hostname("\<connection-name>") to resolve the Consul host.

​
Features

  • Service Discovery: Consul clients can register services and other clients can discover them via DNS or HTTP API
  • Health Checking: Consul monitors service health and only routes to healthy instances
  • Key/Value Store: Flexible key/value store for dynamic configuration and feature flags
  • Multi-Datacenter: Consul supports multiple datacenters out of the box
  • Service Mesh: Connect services securely with automatic TLS encryption and identity-based authorization

​
Persistence

  • Data path: ${monk-volume-path}/consul/node:/consul/data
  • Consul stores service registry, health checks, key/value data, and cluster state in this directory
  • This volume ensures data persists across container restarts
  • See other templates in this repository for complementary services
  • Combine with monitoring tools (prometheus-grafana/) for observability
  • Integrate with your application stack as needed

​
Troubleshooting

  • Ensure all required ports (8500, 8600, 8301, 8302, 8300) are available and not blocked by firewall
  • If Consul fails to start, check that the datacenter configuration matches across all nodes in a cluster
  • For cluster setups, verify that consul-bootstrap-expect matches the actual number of server nodes
  • Check logs:
monk logs -l 500 -f consul/node
  • Access the web UI to monitor cluster health: http://localhost:8500
  • Verify Consul agent status inside the container:
monk shell consul/node
consul members
consul info
  • If services aren’t registering, ensure the Consul agent is running in the correct mode (server vs client)