Consul — Dependencies#

Module info#

  • Module: github.com/hashicorp/consul
  • Go version: go 1.25.8
  • Direct dependencies: 111
  • Indirect dependencies: 162 (in go.mod); ~730 unique modules in go.sum (1460 lines ÷ 2)

Dependency categories#

Core infrastructure#

  • github.com/hashicorp/go-hclog v1.6.3 — Structured, leveled logging using HCL conventions; used pervasively across all Consul packages.
  • github.com/hashicorp/hcl v1.0.1-vault-7 / hcl/v2 v2.14.1 — HashiCorp Configuration Language parser. Both v1 and v2 are required simultaneously (v1 for legacy compatibility, v2 for modern config blocks).
  • github.com/hashicorp/hil — HCL interpolation language; used in older config templating paths.
  • github.com/mitchellh/cli v1.1.5 — CLI framework used instead of cobra; all consul subcommands are registered via mitchellh/cli.
  • github.com/armon/go-metrics v0.4.1 — Metrics sink abstraction; Consul routes all metrics through this before emitting to Prometheus or Circonus.
  • github.com/fsnotify/fsnotify v1.6.0 — Filesystem watching for config file reload.
  • github.com/go-viper/mapstructure/v2 — Maps HCL-parsed maps to config structs.
  • github.com/fatih/color v1.18.0 — Terminal color output for CLI commands.
  • github.com/imdario/mergo v0.3.15 — Deep struct merging; used to overlay partial config updates.
  • github.com/armon/go-radix v1.0.0 / hashicorp/go-immutable-radix v1.3.1 / v2 v2.1.0 — Radix tree implementations used for ACL policy routing and efficient prefix-based lookups.
  • github.com/hashicorp/go-memdb v1.3.4 — In-memory database with transactions; used for the server’s local state store (services, checks, KV, sessions).
  • github.com/hashicorp/golang-lru v1.0.2 — LRU cache used in multiple layers (ACL cache, leaf certificate cache).
  • github.com/patrickmn/go-cache v2.1.0 — TTL-based in-memory cache; used for lighter caching needs.
  • github.com/hashicorp/go-multierror v1.1.1 — Accumulate multiple errors; common in config validation and multi-check health.
  • github.com/hashicorp/go-uuid v1.0.3 — UUID generation for node and service IDs.
  • github.com/hashicorp/go-checkpoint v0.5.0 — Periodic version-check pings to HashiCorp’s checkpoint service.
  • github.com/rboyer/safeio v0.2.3 — Atomic file writes; used when persisting state to disk.
  • github.com/oklog/ulid/v2 v2.1.0 — ULID generation for monotonic IDs (e.g., log entries).
  • github.com/shirou/gopsutil/v3 v3.22.9 — OS/process stats for health checks and telemetry.
  • github.com/deckarep/golang-set/v2 v2.3.1 — Generic set type; used in service mesh intention matching.
  • github.com/pkg/errors v0.9.1 — Legacy error wrapping; most new code uses stdlib fmt.Errorf %w.

Networking / HTTP / gRPC / Service Mesh#

  • google.golang.org/grpc v1.79.3 — gRPC framework; all internal server-to-server and agent-to-server communication uses gRPC alongside the legacy net/rpc protocol.
  • google.golang.org/protobuf v1.36.11 — Protocol Buffers runtime.
  • github.com/envoyproxy/go-control-plane v0.14.0 + /contrib + /envoy + /ratelimit + /xdsmatcher — Envoy xDS API implementation. The five sub-modules cover xDS resources, contrib extensions, Envoy protobuf types, rate limit API, and route matchers. This is the foundation for Consul’s service mesh Envoy integration.
  • github.com/grpc-ecosystem/go-grpc-middleware v1.4.0 — Chained gRPC interceptors for auth, logging, and rate limiting.
  • github.com/hashi-derek/grpc-proxy v0.0.0-20231207191910 — Transparent gRPC proxying; used in xDS server path.
  • github.com/fullstorydev/grpchan v1.1.1 — gRPC channel multiplexing utilities.
  • github.com/miekg/dns v1.1.68 — Full DNS client/server library. Consul implements its own DNS server for service discovery; this is the core dependency.
  • github.com/google/tcpproxy v0.0.0-20180808230851 — TCP connection routing; used for transparent proxy mode.
  • github.com/NYTimes/gziphandler v1.0.1 — gzip middleware for the HTTP API.
  • github.com/prometheus/client_golang v1.14.0 — Prometheus metrics exposition; Consul exposes /v1/agent/metrics in Prometheus format.
  • go.opentelemetry.io/proto/otlp v1.7.1 — OpenTelemetry OTLP protobuf types for distributed tracing integration.
  • github.com/hashicorp/go-connlimit v0.3.0 — Per-IP and total connection limiting for the gRPC and HTTP listeners.
  • github.com/hashicorp/consul-net-rpc v0.0.0-20221205195236 — Consul’s fork of Go’s net/rpc package; maintained for backward-compatible RPC wire format.
  • github.com/hashicorp/yamux v0.0.0-20211028200310 — Multiplexed TCP sessions; used for agent-to-server connection pooling.
  • github.com/natefinch/npipe v0.0.0-20160621034901 — Windows named pipe support for the agent socket.
  • github.com/docker/go-connections v0.4.0 — Docker networking utilities; used in testing.
  • github.com/hashicorp/go-sockaddr v1.0.5 — Socket address parsing including CIDR matching; used for bind/advertise address configuration.
  • github.com/hashicorp/go-retryablehttp v0.7.8 — Retrying HTTP client used for upstream health check calls.

Consensus / Clustering#

  • github.com/hashicorp/raft v1.7.3 — Raft consensus algorithm; the foundation of Consul’s server cluster consistency.
  • github.com/hashicorp/raft-autopilot v0.1.6 — Automated Raft cluster management (dead server cleanup, upgrade migrations).
  • github.com/hashicorp/raft-boltdb/v2 v2.2.2 — BoltDB-backed Raft log and stable storage.
  • github.com/hashicorp/raft-wal v0.4.1 — Write-ahead log storage backend for Raft, an alternative to BoltDB.
  • github.com/hashicorp/go-raftchunking v0.7.0 — Splits large Raft log entries into chunks to avoid log size limits.
  • github.com/hashicorp/memberlist v0.5.2 — SWIM gossip protocol for cluster membership and failure detection. Used indirectly via Serf.
  • github.com/hashicorp/serf v0.10.2 — Gossip-based cluster membership and event propagation built on memberlist. Used by Consul agents for LAN/WAN pool management.
  • go.etcd.io/bbolt v1.3.7 — BoltDB embedded key-value store; primary persistent storage for Raft logs.

Security / Auth / PKI#

  • github.com/hashicorp/cap v0.10.0 — HashiCorp auth plugins: OIDC, JWT, and LDAP.
  • github.com/coreos/go-oidc/v3 v3.11.0 — OIDC identity provider integration (used by cap).
  • github.com/golang-jwt/jwt/v5 v5.2.2 — JWT token parsing and validation.
  • github.com/go-jose/go-jose/v3 v3.0.4 — JWS/JWE (JSON Web Signature/Encryption); used for OIDC/JWT workflows.
  • github.com/hashicorp/vault/api v1.12.2 + vault/sdk v0.7.0 + vault-plugin-auth-alicloud — Vault integration for secrets and auth. Consul uses Vault as a CA backend for its Connect service mesh PKI.
  • github.com/hashicorp/vault/api/auth/gcp — GCP Vault auth method; used in cloud auto-join and CA configuration.
  • github.com/hashicorp/go-rootcerts v1.0.2 — Cross-platform root certificate loading.
  • github.com/hashicorp/go-secure-stdlib/awsutil/v2 — AWS credential helpers (SigV4, IMDS).
  • github.com/hashicorp/consul-awsauth — Consul-specific AWS authentication for cloud auto-join.
  • golang.org/x/crypto v0.48.0 — Low-level crypto; TLS certificate generation and SSH key utilities.
  • golang.org/x/oauth2 v0.35.0 — OAuth2 flows for cloud provider auth.

Cloud / Service Discovery Auto-join#

  • github.com/hashicorp/go-discover v1.1.0 — Multi-cloud peer discovery (AWS, GCP, Azure, Alibaba, DO, etc.); used by the retry-join mechanism to auto-discover cluster members.
  • github.com/aws/aws-sdk-go-v2 v1.41.0 (+ config, credentials, acmpca, smithy-go) — AWS integration for auto-join, Private CA backend for Connect.
  • github.com/aliyun/alibaba-cloud-sdk-go v1.62.156 — Alibaba Cloud SDK for Alibaba auto-join.

Kubernetes Integration#

  • k8s.io/api v0.26.2 / apimachinery / client-go — Kubernetes client used for Consul’s Kubernetes service discovery and the Kubernetes auth method.

Serialization / Data#

  • google.golang.org/protobuf — Primary serialization for internal gRPC APIs and xDS resources.
  • github.com/hashicorp/hcl / hcl/v2 — HCL config parsing.
  • github.com/zclconf/go-cty v1.11.1 — Type system for HCL/v2 expressions.
  • github.com/xeipuuv/gojsonschema v1.2.0 — JSON Schema validation; used in config entry validation.
  • github.com/mitchellh/hashstructure + /v2 — Structural hashing of Go values; used for cache keys.
  • github.com/mitchellh/copystructure — Deep copy of structs; used when cloning config entries.
  • github.com/mitchellh/reflectwalk — Walks struct fields reflectively; underlying engine for copystructure.
  • github.com/mitchellh/pointerstructure — JSON Pointer access into nested structs.
  • github.com/armon/circbuf v0.0.0-20150827004946 — Circular byte buffer; used for check output capture.
  • github.com/hashicorp/go-bexpr v0.1.2 — Boolean expression evaluator for API filtering (?filter= queries).

Testing#

  • github.com/stretchr/testify v1.11.1 — Primary test framework; assert, require, mock, suite packages all used.
  • gotest.tools/v3 v3.4.0 — Additional test assertions, particularly for Golden file comparisons.
  • go.uber.org/goleak v1.3.0 — Goroutine leak detection in tests; many test suites call goleak.VerifyNone.
  • github.com/google/go-cmp v0.7.0 — Deep equality comparison for complex structs.
  • github.com/google/gofuzz v1.2.0 — Fuzz testing for API types.
  • github.com/mitchellh/go-testing-interface v1.14.1 — Allows passing *testing.T vs a TestingT interface for test helpers.
  • github.com/google/pprof v0.0.0-20210720184732 — CPU/memory profiling tooling used in bench/ subdirectory.

Internal Sub-modules (replace directives)#

The root go.mod replaces five internal modules to local paths, enabling them to be consumed independently:

  • consul/api — Official HTTP API client library (used by operators and tooling)
  • consul/sdk — Shared types, utilities, and testutil helpers
  • consul/proto-public — Public-facing protobuf API definitions
  • consul/envoyextensions — Envoy extension configuration types
  • consul/troubleshoot — Consul troubleshooting CLI tools

Stdlib reliance#

Consul makes heavy, idiomatic use of the Go standard library. Key packages from agent/agent.go: context, crypto/tls, encoding/json, errors, fmt, io, net, net/http, os, path/filepath, reflect, regexp, strconv, strings, sync, sync/atomic, time.

The pattern is consistent across all major packages: stdlib provides the scaffolding (HTTP server, TLS, networking, JSON), while third-party packages provide domain-specific functionality (Raft, Serf, gRPC, Envoy xDS). Consul notably implements its own DNS server on top of github.com/miekg/dns rather than using the stdlib DNS resolver, and manages TLS certificate rotation manually rather than relying on stdlib’s tls.Config auto-rotation.

Shared dependencies#

Dependencies that appear across multiple projects in the 50-project set (high-value cross-project connection points):

  • google.golang.org/grpc — ubiquitous in distributed systems Go projects
  • google.golang.org/protobuf — same
  • github.com/stretchr/testify — appears in the vast majority of Go projects
  • github.com/hashicorp/go-hclog — standard across the entire HashiCorp ecosystem (Vault, Nomad, Terraform)
  • golang.org/x/crypto, x/net, x/sync, x/sys — extended stdlib used by almost all networked Go projects
  • github.com/prometheus/client_golang — standard for metrics in cloud-native Go
  • github.com/mitchellh/mapstructure (v1 indirectly) — extremely common config decoding utility
  • github.com/pkg/errors — legacy but widespread
  • github.com/google/go-cmp — common in projects with complex struct testing
  • github.com/hashicorp/raft — shared with Vault and projects implementing distributed consensus
  • go.etcd.io/bbolt — shared with etcd, Vault, and other embedded-storage projects

Vendoring#

No vendor directory. Consul relies on the Go module cache and uses go.sum for integrity verification. This is consistent with HashiCorp’s practice across large projects — vendoring would add hundreds of MB to the repository given the 730+ module dependency graph.

The go.mod does include exclude directives for github.com/hashicorp/go-msgpack v1.1.5 and v1.1.6 due to breaking changes, demonstrating active dependency governance even without vendoring.

Notable dependency decisions#

  1. All-in on the HashiCorp Go ecosystem. Twenty-five of the 111 direct dependencies are first-party HashiCorp libraries (hashicorp/*). This creates a tightly integrated but somewhat proprietary dependency graph. The consistency is a strength (shared conventions for logging, metrics, config) but also means Consul is deeply coupled to HashiCorp’s release cadence.

  2. Five Envoy sub-modules as direct deps. Rather than pulling a single go-control-plane, Consul lists five distinct sub-modules from the envoyproxy organization. This reflects the modular restructuring of the go-control-plane project and shows Consul tracking Envoy’s API evolution very closely — a necessary commitment for a service mesh xDS management plane.

  3. mitchellh/cli over cobra. Consul uses Mitchell Hashimoto’s own CLI framework rather than the now-dominant cobra. This is a legacy decision (mitchellh/cli predates cobra’s dominance) maintained for backward compatibility in command interface contracts.

  4. Dual Raft storage backends. Both raft-boltdb/v2 (BoltDB) and raft-wal are direct dependencies, exposing that Consul supports two storage backends for the Raft log. This is an explicit architectural choice to let operators choose between the mature BoltDB and a newer WAL-based store.

  5. Both HCL v1 and v2 simultaneously. The coexistence of github.com/hashicorp/hcl v1.0.1-vault-7 and github.com/hashicorp/hcl/v2 v2.14.1 reflects a multi-year migration rather than a clean cut. HCL v2 adds structured expression evaluation; v1 remains for config paths that predate the migration.

  6. Multi-cloud by design. go-discover, the AWS SDK, Alibaba Cloud SDK, and multiple Vault cloud auth plugins are direct dependencies — not optional plugins. Cloud auto-discovery is a first-class feature compiled into the binary rather than delegated to external tooling.

  7. Kubernetes as a first-class citizen. The k8s client libraries appear as direct (not indirect) dependencies, reflecting that Consul’s Kubernetes service sync and auth method are built directly into the main binary.

Backward Consul — Structure Consul — Architecture Forward