Getting Started

Run the Consul Agent

After you install Consul you'll need to start the Consul agent. In this guide you will run Consul in development mode, which isn't secure or scalable, but does let you easily experiment with most of Consul's functionality without extra configuration. You will also learn how to gracefully shut down the Consul agent.

Server and Client Agents

In production you would run each Consul agent in either in server or client mode. Each Consul datacenter must have at least one server, which is responsible for maintaining Consul's state. This includes information about other Consul servers and clients, what services are available for discovery, and which services are allowed to talk to which other services.

In order to make sure that Consul's state is preserved even if a server fails, you should always run either three or five servers in production. The odd number of servers (and no more than five of them) strikes a balance between performance and failure tolerance. You can learn more about these requirements in Consul's architecture documentation.

Non-server agents run in client mode. A client is a lightweight process that registers services, runs health checks, and forwards queries to servers. A client must be running on every node in the Consul datacenter that runs services, since clients are the source of truth about service health.

When you're ready to got into production you can find more guidance on production deployment of servers and clients in this guide. For now, lets start our local agent in development mode, which is an in memory server mode with some common features enabled (despite security risks) for ease of use, and all persistence options turned off.

Starting the Agent

Start the Consul agent in development mode.

$ consul agent -dev
==> Starting Consul agent...
           Version: 'v1.5.2'
           Node ID: '019063f6-9215-6f2c-c930-9e84600029da'
         Node name: 'Judiths-MBP'
        Datacenter: 'dc1' (Segment: '<all>')
            Server: true (Bootstrap: false)
       Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: -1, gRPC: 8502, DNS: 8600)
      Cluster Addr: 127.0.0.1 (LAN: 8301, WAN: 8302)
           Encrypt: Gossip: false, TLS-Outgoing: false, TLS-Incoming: false, Auto-Encrypt-TLS: false

==> Log data will now stream in as it occurs:

    2019/07/15 19:24:34 [DEBUG] agent: Using random ID "019063f6-9215-6f2c-c930-9e84600029da" as node ID
    2019/07/15 19:24:34 [DEBUG] tlsutil: Update with version 1
    2019/07/15 19:24:34 [DEBUG] tlsutil: OutgoingRPCWrapper with version 1
    2019/07/15 19:24:34 [INFO]  raft: Initial configuration (index=1): [{Suffrage:Voter ID:019063f6-9215-6f2c-c930-9e84600029da Address:127.0.0.1:8300}]
    2019/07/15 19:24:34 [INFO]  raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "")
    2019/07/15 19:24:34 [INFO] serf: EventMemberJoin: Judiths-MBP.dc1 127.0.0.1
    2019/07/15 19:24:34 [INFO] serf: EventMemberJoin: Judiths-MBP 127.0.0.1
    2019/07/15 19:24:34 [INFO] consul: Handled member-join event for server "Judiths-MBP.dc1" in area "wan"
    2019/07/15 19:24:34 [INFO] consul: Adding LAN server Judiths-MBP (Addr: tcp/127.0.0.1:8300) (DC: dc1)
    2019/07/15 19:24:34 [DEBUG] agent/proxy: managed Connect proxy manager started
    2019/07/15 19:24:34 [INFO] agent: Started DNS server 127.0.0.1:8600 (tcp)
    2019/07/15 19:24:34 [INFO] agent: Started DNS server 127.0.0.1:8600 (udp)
    2019/07/15 19:24:34 [INFO] agent: Started HTTP server on 127.0.0.1:8500 (tcp)
    2019/07/15 19:24:34 [INFO] agent: Started gRPC server on 127.0.0.1:8502 (tcp)
    2019/07/15 19:24:34 [INFO] agent: started state syncer
==> Consul agent running!
    2019/07/15 19:24:34 [WARN]  raft: Heartbeat timeout from "" reached, starting election
    2019/07/15 19:24:34 [INFO]  raft: Node at 127.0.0.1:8300 [Candidate] entering Candidate state in term 2
    2019/07/15 19:24:34 [DEBUG] raft: Votes needed: 1
    2019/07/15 19:24:34 [DEBUG] raft: Vote granted from 019063f6-9215-6f2c-c930-9e84600029da in term 2. Tally: 1
    2019/07/15 19:24:34 [INFO]  raft: Election won. Tally: 1
    2019/07/15 19:24:34 [INFO]  raft: Node at 127.0.0.1:8300 [Leader] entering Leader state
    2019/07/15 19:24:34 [INFO] consul: cluster leadership acquired
    2019/07/15 19:24:34 [INFO] consul: New leader elected: Judiths-MBP
    2019/07/15 19:24:34 [INFO] connect: initialized primary datacenter CA with provider "consul"
    2019/07/15 19:24:34 [DEBUG] consul: Skipping self join check for "Judiths-MBP" since the cluster is too small
    2019/07/15 19:24:34 [INFO] consul: member 'Judiths-MBP' joined, marking health alive
    2019/07/15 19:24:34 [DEBUG] agent: Skipping remote check "serfHealth" since it is managed automatically
    2019/07/15 19:24:34 [INFO] agent: Synced node info
    2019/07/15 19:24:36 [DEBUG] tlsutil: OutgoingRPCWrapper with version 1
    2019/07/15 19:24:36 [DEBUG] agent: Skipping remote check "serfHealth" since it is managed automatically
    2019/07/15 19:24:36 [DEBUG] agent: Node info in sync
    2019/07/15 19:24:36 [DEBUG] agent: Node info in sync

The logs report that the Consul agent has started and is streaming some log data. They also report that the agent is running as a server and has claimed leadership. Additionally, the local agent has been marked as a healthy member of the datacenter.

Datacenter Members

Check the membership of the Consul datacenter by running the consul members command in a new terminal window. The output lists the agents in the datacenter. We'll cover ways to join Consul agents together later on, but for now there is only one member (your machine).

$ consul members
Node         Address         Status  Type    Build  Protocol  DC   Segment
Judiths-MBP  127.0.0.1:8301  alive   server  1.5.2  2         dc1  <all>

The output displays your agent, its IP address, its health state, its role in the datacenter, and some version information. You can discover additional metadata by providing the -detailed flag.

The members command runs against the Consul client, which gets its information via gossip protocol. The information that the client has is eventually consistent, but at any point in time its view of the world may not exactly match the state on the servers. For a strongly consistent view of the world, query the HTTP API, which forwards the request to the Consul servers.

$ curl localhost:8500/v1/catalog/nodes
[
    {
        "ID": "019063f6-9215-6f2c-c930-9e84600029da",
        "Node": "Judiths-MBP",
        "Address": "127.0.0.1",
        "Datacenter": "dc1",
        "TaggedAddresses": {
            "lan": "127.0.0.1",
            "wan": "127.0.0.1"
        },
        "Meta": {
            "consul-network-segment": ""
        },
        "CreateIndex": 9,
        "ModifyIndex": 10
    }
]

In addition to the HTTP API, you can use the DNS interface to discover the nodes. The DNS interface will send your query to the Consul servers unless you've enabled caching. To perform DNS lookups you have to point to the Consul agent's DNS server, which runs on port 8600 by default. The format of the DNS entries (such as Judiths-MBP.node.consul) will be covered in more detail later.

$ dig @127.0.0.1 -p 8600 Judiths-MBP.node.consul

; <<>> DiG 9.10.6 <<>> @127.0.0.1 -p 8600 Judiths-MBP.node.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 7104
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 2
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;Judiths-MBP.node.consul.   IN  A

;; ANSWER SECTION:
Judiths-MBP.node.consul. 0  IN  A   127.0.0.1

;; ADDITIONAL SECTION:
Judiths-MBP.node.consul. 0  IN  TXT "consul-network-segment="

;; Query time: 0 msec
;; SERVER: 127.0.0.1#8600(127.0.0.1)
;; WHEN: Mon Jul 15 19:43:58 PDT 2019
;; MSG SIZE  rcvd: 104

Stopping the Agent

Stop the Consul agent by using the consul leave command. This will gracefully stop the agent, causing it to leave the Consul datacenter and shut down.

$ consul leave
Graceful leave complete

If you switch back to the window with Consul's streaming log output, the logs indicate that the Consul agent left the datacenter.

2019/07/15 19:52:11 [INFO] consul: server starting leave
2019/07/15 19:52:11 [INFO] serf: EventMemberLeave: Judiths-MBP.dc1 127.0.0.1
2019/07/15 19:52:11 [INFO] consul: Handled member-leave event for server "Judiths-MBP.dc1" in area "wan"
2019/07/15 19:52:11 [INFO] manager: shutting down
2019/07/15 19:52:14 [INFO] serf: EventMemberLeave: Judiths-MBP 127.0.0.1
2019/07/15 19:52:14 [INFO] consul: Removing LAN server Judiths-MBP (Addr: tcp/127.0.0.1:8300) (DC: dc1)
2019/07/15 19:52:14 [WARN] consul: deregistering self (Judiths-MBP) should be done by follower
2019/07/15 19:52:16 [ERR] autopilot: Error updating cluster health: error getting server raft protocol versions: No servers found
2019/07/15 19:52:17 [INFO] consul: Waiting 5s to drain RPC traffic
2019/07/15 19:52:18 [ERR] autopilot: Error updating cluster health: error getting server raft protocol versions: No servers found
2019/07/15 19:52:20 [ERR] autopilot: Error updating cluster health: error getting server raft protocol versions: No servers found
2019/07/15 19:52:21 [ERR] agent: Coordinate update error: No cluster leader
2019/07/15 19:52:22 [ERR] autopilot: Error updating cluster health: error getting server raft protocol versions: No servers found
2019/07/15 19:52:22 [INFO] agent: Requesting shutdown
2019/07/15 19:52:22 [WARN] agent: dev mode disabled persistence, killing all proxies since we can't recover them
2019/07/15 19:52:22 [DEBUG] agent/proxy: Stopping managed Connect proxy manager
2019/07/15 19:52:22 [INFO] consul: shutting down server
2019/07/15 19:52:22 [INFO] agent: consul server down
2019/07/15 19:52:22 [INFO] agent: shutdown complete
2019/07/15 19:52:22 [DEBUG] http: Request PUT /v1/agent/leave (11.004695827s) from=127.0.0.1:54434
2019/07/15 19:52:22 [INFO] agent: Stopping DNS server 127.0.0.1:8600 (tcp)
2019/07/15 19:52:22 [INFO] agent: Stopping DNS server 127.0.0.1:8600 (udp)
2019/07/15 19:52:22 [INFO] agent: Stopping HTTP server 127.0.0.1:8500 (tcp)
2019/07/15 19:52:22 [INFO] agent: Waiting for endpoints to shut down
2019/07/15 19:52:22 [INFO] agent: Endpoints down
2019/07/15 19:52:22 [INFO] agent: Exit code: 0

When you issue the leave command, Consul notifies other members that the agent left the datacenter. When an agent leaves, its local services running on the same node and their checks are removed from the catalog and Consul doesn't try to contact that node again.

Forcibly killing the agent process indicates to other agents in the Consul datacenter that the node failed instead of left. When a node fails, its health is marked as critical, but it is not removed from the catalog. Consul will automatically try to reconnect to a failed node, assuming that it may be unavailable because of a network partition, and that it may be coming back.

If an agent is operating as a server, a graceful leave is important to avoid causing a potential availability outage affecting the consensus protocol. See the Adding and Removing Servers guide for details on how to safely add and remove servers.

Summary

Now that you have started and stopped a Consul agent in development mode, continue to the next guide where you will learn how Consul knows about the existence and location of services in your datacenter.