Consul

Consul is a distributed, highly available, datacenter-aware system for service discovery, service mesh, dynamic application configuration, and key/value storage. This wiki documents the source code in hashicorp/consul — the Go implementation of the consul agent, server, and CLI.

What this codebase does

A single consul binary runs in two main modes:

• Agent (client) — a process that runs on every node in the cluster. Local applications register services and health checks with it, query it for service discovery, and use it as the local entry point to the KV store and service mesh.
• Server — a special agent mode that participates in a Raft consensus group. Servers hold the canonical state, run the leader election, replicate the FSM (catalog, KV, ACLs, config entries, intentions, prepared queries, sessions, peerings, etc.) via Raft logs and snapshots, and serve RPC and gRPC requests.

The same binary is also the operator CLI (consul members, consul kv put, consul intention create, consul snapshot save, ...).

High-level capabilities

Capability	Where it lives
Service discovery	agent/dns.go, agent/catalog_endpoint.go, agent/consul/catalog_endpoint.go
Health checks	agent/checks/, agent/check.go
Service mesh (Connect)	agent/connect/, agent/proxycfg/, agent/xds/, connect/
API gateway	agent/consul/gateways/, agent/xds/listeners_apigateway.go, agent/structs/config_entry_gateways.go
KV store	agent/kvs_endpoint.go, agent/consul/kvs_endpoint.go, agent/consul/state/kvs.go
ACL system	acl/, agent/consul/acl_endpoint.go, agent/consul/state/acl.go
Cluster peering	agent/consul/peering_backend.go, agent/consul/leader_peering.go, agent/consul/state/peering.go
Multi-datacenter (WAN)	agent/consul/server_serf.go, agent/consul/wanfed/, agent/consul/leader_federation_state_ae.go
Coordinates / network RTT	agent/consul/coordinate_endpoint.go, coordinate/ (in lib/)
Snapshots	agent/consul/fsm/snapshot.go, snapshot/

Repository at a glance

• Language: Go 1.26 (see .go-version)
• License: Business Source License 1.1 (LICENSE)
• Module: github.com/hashicorp/consul with sub-modules api/, sdk/, envoyextensions/, proto-public/, troubleshoot/
• Entry point: main.go → command.RegisteredCommands → individual commands under command/
• Build: make dev produces a consul binary in bin/ and $GOPATH/bin

Where to start reading

Goal	Start here
Understand the runtime architecture	Architecture
Build and run Consul locally	Getting started
Look up an unfamiliar term	Glossary
Explore the agent and server	Systems → Agent, Server and Raft
Understand the service mesh	Features → Service mesh
Add or change a config entry	Features → Config entries
Use the Go HTTP client	Packages → api

Related external docs

• Operator-facing documentation: https://developer.hashicorp.com/consul/docs
• Architecture and protocol design: https://developer.hashicorp.com/consul/docs/architecture
• Tutorials: https://learn.hashicorp.com/consul