How to Setup and Configure Consul Agent On Client Mode

consul agent setup in client mode

In our last consul post, we have explained the steps to setup up a multi-node consul cluster which runs on server more.

If you want to use consul services for your application on a server, you need to set up a consul agent on the client mode to talk to the consul cluster. A consul client agent is also a member of the system which can obtain the configurations present in the consul cluster.

In this post, we will look into the steps involved in running a consul agent on client mode for querying and retrieving services and information from the consul servers.

Install & Configure Consul Agent On Client Mode

Step 1: Update the package repositories and install unzip.

For RHEL/Centos,

sudo yum update -y
sudo yum install unzip -y

For Ubuntu,

sudo apt-get update -y
sudo apt-get install unzip -y

Step 2: Head over to consul downloads page. and get the link for Linux 64 bit.

Step 3: Download the consul binary to /opt directory.

cd /opt
sudo curl -o

Step 4: Unzip consul binary.

sudo unzip

Step 5: Move consul executable to /usr/bin directory to be accessible system-wide. You can also move it a location which is in your system path.

sudo mv consul /usr/bin/

Step 6: Verify the consul executable by executing the consul command. It should list the available commands.


Step 7: Create consul config directories.

sudo mkdir -p /etc/consul.d/client
mkdir /var/consul

Step 9: Create a consul config file.

sudo vi /etc/consul.d/client/config.json

Copy the following config content to the config.json file. You should have the value of encrypt which was used during the consul server configuration. If you don’t have this value, you can get it from the consul server from /var/consul/serf/local.keyring file. Also, provide the correct datacenter value available in the consul server

    "server": false,
    "datacenter": "Us-Central",
    "data_dir": "/var/consul",
    "encrypt": "gsdfHJ3KZvpC/Zsdf9JZSTQQ==",
    "log_level": "INFO",
    "enable_syslog": true,
    "leave_on_terminate": true,
    "start_join": [

Step 11: Create a consul client service file.

sudo vi /etc/systemd/system/consul-client.service

Copy the following contents

Description=Consul Startup process
ExecStart=/bin/bash -c '/usr/bin/consul agent -config-dir /etc/consul.d/client'

Step 12: Reload system daemon.

sudo systemctl daemon-reload

Step 13: Start & check the status of consul client service.

sudo systemctl start consul-client
sudo systemctl status consul-client

Step 14: Check the consul members using the following command.

consul members

You should see your client node in your list of members. It will be of type client. The server cluster members will be of type server.

consul list client members

Query Services & Key Value Pairs From Consul Server

Now that we have successfully configured the client, lets run some checks by retrieving data from the consul server.

List All Available Services

Method 1: Using consul command

consul catalog services

Method 2: Using API


Method 3: Using DNS query. Here you need to specify your service name to get the details.

dig @ -p 8600 consul.service.consul SRV

Query key Values From Consul Client

Lets list a key named backend recursively,

consul kv get -recurse backend
  1. Why is it necessary to have separate Servers and Clients? What is the purpose of them?

    Is it necessary to run consul agent on my every host where a service is running?

  2. Hi,

    I have done creating the consul servers its working fine.

    Now im trying to create consul agent with same way.

    We are getting error when try to run consul members.
    Error retrieving members: Get dial tcp connect: connection refused

    we have checked the $ ss -tunelp | grep 8500 and got empty response

    and $ systemctl status consul this command giving the errors

    May 09 10:50:01 ip-172-31-0-106 systemd[1]: Failed to start Consul Service Disco

    we set up the route53 also for this

  3. Hi TQuang,
    Please i need your help i need to configure Vault server and client for secret keys in my environment. Please i need your help and i will appreciate it if you can help me out on this. Thanks

  4. Thanks, best article. In my case, the same with this article: 3 servers quorum and 2 agents. They are serving like as private DNS.

    Add service (register a service = domain name for service):
    curl -X PUT -d ‘{“ID”: “app1”, “Name”: “app”, “Address”: “”, “Port”: 3000}’ http://:8500/v1/agent/service/register

    Check by dig comman: dig @ip-agent app.service.consule

    Remove service (deregister a service):
    curl -X PUT http://:8500/v1/agent/service/deregister/app1

Leave a Reply

Your email address will not be published. Required fields are marked *

You May Also Like