> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HashiCorp Consul

> Ready-to-run HashiCorp Consul container template you can run directly or inherit to integrate service discovery and configuration management into your infrastructure.

## 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

```bash theme={null}
monk load MANIFEST
```

2. Run Consul with defaults

```bash theme={null}
monk run consul/node
```

3. 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:

```yaml theme={null}
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)

## Use by inheritance (recommended for infrastructure)

Inherit the Consul runnable in your service mesh or microservices infrastructure. Example:

```yaml theme={null}
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:

```bash theme={null}
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

## Related templates

* 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:

```bash theme={null}
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:

```bash theme={null}
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)