Lore

A narrative history of the Consul codebase, derived from git history, tag dates, and observable rewrites in the source tree.

Eras

Genesis (Nov 2013 – Apr 2014)

The first commit (Initial commit) lands on Nov 4, 2013. By Dec 6, 2013 the basic agent skeleton, Raft wrapper, and LAN/WAN distinction (renamed from "Local/Remote") are in place. v0.1.0 is tagged on Apr 16, 2014, formally introducing service discovery, health checks, KV, and gossip-based clustering.

Key infrastructure choices made here are still recognizable today:

• Two-tier client/server agent model.
• Raft for consensus, Serf for membership.
• A MemDB state store fronting Raft.

Building out the core (2014 – 2017)

Tags walk through v0.5.0 (Feb 2015), v0.7.0 (Sep 2016), and finally v1.0.0 on Oct 16, 2017. Commit volume averages ~1,500 per year. Notable additions in this period:

• ACL system rebuilt twice (legacy and "new ACLs" with policies, roles, and tokens).
• Prepared queries (agent/consul/prepared_query_endpoint.go).
• Multi-datacenter WAN federation.
• Snapshots for full FSM backup/restore (agent/consul/fsm/snapshot.go).
• Autopilot for operator-friendly Raft management (agent/consul/autopilot.go).

Service mesh era (2018 – 2020)

Connect — Consul's service mesh — ships in v1.2 (mid-2018) and is iterated heavily through v1.5.0 (May 2019) and v1.7.0 (early 2020). The big architectural additions of this era:

• Connect CA with pluggable providers (Consul, Vault, AWS PCA) under agent/connect/ca/ and agent/consul/leader_connect_ca.go.
• Envoy as the default sidecar, driven by an in-tree xDS server (agent/xds/).
• The proxycfg manager (agent/proxycfg/manager.go) that turns catalog + intentions + config entries into a per-proxy snapshot.
• L7 traffic management via service-router, service-resolver, and service-splitter config entries with the discovery chain abstraction (agent/structs/config_entry_discoverychain.go, agent/consul/discoverychain/).
• Mesh, ingress, and terminating gateways.

Operations and federation (2020 – 2022)

The codebase peaks in commit volume during this stretch (~2,700 commits/year in 2020-2021, 3,177 in 2022). Highlights:

• Streaming subscribe backend for catalog and config-entry events, replacing many polling RPC patterns. agent/consul/stream/, agent/consul/subscribe_backend.go, agent/submatview/.
• Cluster peering as a lighter-weight alternative to WAN federation. agent/consul/peering_backend.go, agent/consul/leader_peering.go. Peering is publicly stable in v1.14.0 (Nov 2022).
• API gateway support and richer ingress gateway features. agent/consul/gateways/, agent/xds/listeners_apigateway.go.
• Anti-entropy hardening for federation state (agent/consul/leader_federation_state_ae.go).
• Rate limiting and admission control on RPC and gRPC (agent/consul/rate/, agent/consul/multilimiter/).

Stabilization and v2 model (2023 – 2026)

Commit volume drops sharply: 1,573 in 2023, 545 in 2024, 278 in 2025, 98 through April 2026. Two strategic shifts explain the slowdown:

1. Consul Dataplane. Sidecar functionality moves out of the agent and into a separate consul-dataplane binary, simplifying Kubernetes deployments. The mesh-related code in this repo continues to evolve, but new mesh features increasingly land in the dataplane repo.
2. The v2 resource framework. A new generic resource/controller machinery is introduced under internal/resource/, internal/controller/, internal/storage/, and proto-public/pbresource/. The v2 catalog, multicluster (cluster peering successor), and other models are built on it. The command/resource/ CLI exposes the new APIs (consul resource read|list|apply|delete).

Tagged releases in this era:

• v1.15.0 — Feb 23, 2023
• v1.20.0 — Oct 14, 2024 (introduces broader v2 resource APIs)
• v1.21.x — 2025
• v1.22.0 — Oct 27, 2025; latest patch on main is v1.22.7

Longest-standing features

Feature	First appears	Notes
Catalog / service discovery	First commits, 2013	agent/consul/catalog_endpoint.go and agent/consul/state/catalog.go continue to dominate
Health checks (agent/checks/)	2013	TTL, HTTP, TCP, script checks all date back to early Consul
KV store	v0.1.0 (Apr 2014)	Hierarchical, locked via sessions; semantics are unchanged
Sessions	2014	agent/consul/session_*.go, agent/consul/state/session.go
Prepared queries	2014–2015	Still served by agent/consul/prepared_query_endpoint.go
WAN federation	2014	Underpins multi-DC even after peering arrived
ACL system (current)	Rewrite around 2018	Tokens, policies, roles, templated policies in acl/

Major rewrites

• ACL v2 (2018). The legacy single-token ACL model was replaced with policies, roles, and tokens. The legacy compatibility shims still exist (agent/consul/acl_endpoint_legacy.go is gone, but legacy filtering logic is preserved in places like agent/consul/state/acl.go).
• Streaming subscribe (~2020). Many polling RPC reads were re-plumbed through gRPC streaming + materialized views, drastically reducing leader load. See agent/consul/stream/ and agent/submatview/.
• Connect data plane externalization (2022–2024). Sidecar lifecycle and xDS proxy logic that used to ship in the same binary were split into consul-dataplane. The agent's xDS server is preserved (agent/xds/) for in-cluster scenarios.
• V2 resource API (2023–present). The new internal/resource/, internal/controller/, internal/storage/, and proto-public/pbresource/ framework introduces a generic resource model that is replacing one-off endpoints for catalog, multicluster, and similar concerns.

Deprecated or moved features

• Auto-encrypt is largely superseded by auto-config (agent/auto-config/) but the older endpoint stays around for compatibility (agent/consul/auto_encrypt_endpoint.go).
• Legacy intentions (separate table) were merged into service-intentions config entries; both code paths still exist for migration. agent/consul/state/intention.go.
• segment (Enterprise network segments) appears as CE stubs (agent/consul/segment_ce.go) — the real implementation lives in HashiCorp's enterprise tree.
• The Ember UI (ui/) remains in the repo but UI-only commits dominate recent history while feature work has slowed in the Go layer.

Growth signals

• The repo went from a single main.go + a few packages in 2013 to 40+ top-level directories today.
• The agent struct (agent/agent.go) has grown to 158 KB. Most refactor attempts have moved peripheral logic into sub-packages (agent/local/, agent/cache/, agent/proxycfg/, agent/auto-config/, ...) rather than splitting Agent itself.
• Three distinct concurrency control libraries have appeared in the agent over time: agent/consul/multilimiter/ (per-key token buckets), agent/consul/rate/ (RPC limiter), and agent/consul/multilimiter/.

Speculation

• The plateau in commit volume from 2023 onward likely reflects both the data plane externalization and an organizational shift toward Kubernetes-native primitives. Without internal context this is inference from public commit patterns.
• The relatively recent appearance of internal/multicluster/ and the v2 resource framework suggests cluster peering is being redesigned as a generic "multi-cluster" resource family, with peering becoming one transport rather than a standalone subsystem.