consul agent: Run a Consul Agent in CI
consul agent runs the long-lived Consul process that joins the cluster and serves the HTTP and DNS APIs.
For integration tests you usually want consul agent -dev: a single in-memory server that needs no config and exposes the full API on localhost.
What it does
consul agent starts a Consul agent. In server mode it participates in Raft consensus and stores the catalog and KV; in client mode it forwards requests to servers. -dev runs a throwaway single-node server with sane defaults for local testing.
Common usage
# disposable single-node server for tests
consul agent -dev
# a real server expecting a 3-node quorum
consul agent -server -bootstrap-expect=3 \
-data-dir=/opt/consul -retry-join=10.0.0.2 -retry-join=10.0.0.3Options
| Flag | What it does |
|---|---|
| -dev | Single-node in-memory server with defaults (testing only) |
| -server | Run as a server (Raft member) rather than a client |
| -bootstrap-expect <n> | Wait for n servers before bootstrapping Raft |
| -retry-join <addr> | Address to join, retried until it succeeds |
| -data-dir <path> | Where the agent persists state (required for servers) |
| -config-dir <path> | Directory of HCL/JSON config fragments |
In CI
Start consul agent -dev in the background, then poll consul members until it is alive before the test reads or writes. Pair it with a trap so the agent is killed when the job exits. The dev agent loses all data on restart, which is exactly what a test wants.
Common errors in CI
"==> Error starting agent: Failed to start Consul server: Failed to start Raft: ... data-dir is not set" means a server agent without -data-dir. "Bind address ... Address already in use" means port 8500/8300 is taken by another agent. "bootstrap_expect > 0: expecting 3 servers" in the log just means it is waiting for quorum, not an error.