How to set up cluster


I have been studying Kong recently and encountered some troubles. I tried to search relevant information on Google,but nothing could help!

my question is: how to configure cluster.

I have installed kong (v13) on three virtual machines which system is CentOS x64 (v7.4).
I learned carefully about the “cluster reference” of official document ( But I only know a little about the cluster’s concept and the cluster cache.
I didn’t see any information or configuration about cluster,let alone how to confige cluster step by step.
I prefer to call this document “cache reference” than “cluster reference”.

Then,I search Kong cluster information on Google.Although the information is not much ,but I found they all mentioned some key configuration fileds as below:

I digged every files under kong directory ,But I can’t find the filename which contains those configuration fileds above.Then I realized that they are suit to old version of Kong.

Could anyone please help me ?
Thank you in advance!


my question is: how to configure cluster.

The docs you mentioned before ( are the best resource for answering that question.

I didn’t see any information or configuration about cluster,

The first paragraph explains what a cluster is:

A Kong cluster allows you to scale the system horizontally by adding more machines to handle more incoming requests. They will all share the same configuration since they point to the same database. Kong nodes pointing to the same datastore will be part of the same Kong cluster.

Regarding this:

let alone how to confige cluster step by step.

This really depends on your configuration and your needs. The first node in the cluster is just a regular Kong instance. You can add nodes to the cloud by making them share the same database as the first node.


The cluster_listen and cluster_listen_rpc config options belong to older versions of Kong (they used Serf to manage the cluster). Newer versions of Kong don’t use Serf any more, so those config options no longer apply. The new versions of Kong use the database itself (Postgresql or Cassandra) to keep the nodes of the Cluster in sync (so that if you remove a Service using a node’s Admin API, the rest of the nodes in the cluster are aware of the change).

HI Kikito

Thank you very much …Although you didn’t say anything useful . Because after I reading all your response.I still don’t know how to configure the cluster.

I didn’t see the cluster_listen and cluster_listen_rpc config options in Kong config file.I knew they were deprecated since V10 version.

Please forgive that I am a beginner of Kong ,and maybe even a beginner of English .But please tell me: Is there any single word in that Cluster document tell us How to configure Cluster? I only see the cache knowledge if you want to create a cluster

To configure multiple Kong nodes into a cluster, point them all to the same datastore.

That’s it! There is no further cluster configuration necessary.

Thank you Cooper.

I tried to point the database config option to the same remote server as below:

[root@localhost kong]$grep -A 10 ‘database = postgres’ kong.conf

database = postgres # Determines which of PostgreSQL or Cassandra
# this node will use as its datastore.
# Accepted values are postgres and
# cassandra.

pg_host = # The PostgreSQL host to connect to.
pg_port = 5432 # The port to connect to.
pg_user = kong # The username to authenticate if required.
pg_password = kong # The password to authenticate if required.
pg_database = kong_db # The database name to connect to.

after copied the kong.conf file on all cluster nodes servers and restarted the Kong Service , I didn’t see any cluster nodes:

[root@kong kong]# curl -XGET http://localhost:8001/cluster
{“message”:“Not found”}

The “Not found" response indicates that the /cluster endpoint does not exist.

It did exist in earlier versions of Kong - I wonder if you are referring to the correct version of Kong’s documentation? Be sure to use the docs that match the version of Kong you are using.

Truly thanks for your kind helps ,Cooper

I am running 0.13 version on CentOS 7 server

[root@kong ~]# kong version
[root@kong ~]# cat /etc/redhat-release
CentOS Linux release 7.2.1511 (Core)

I am learning the 0.13 version document of Kong (
But just like I said: this document didn’t mention any single word about how to configure Kong cluster.

We welcome pull requests to improve the documentation!

Could you please help me solve this issue? We can discuss about improving the documentation later.
Except for point the database to the same address in the Kong configure file(/etc/kong/kong.conf) ,what else can I do to set up a cluster .

P.S: I also uncomment below fileds according to the instructions in the document.
db_update_frequency = 5
db_update_propagation = 0
db_cache_ttl = 3600

You should see previous verions for install.

I think the document @kikito showed you should clarify some misconceptions you may have. Quoting from it:

Kong nodes pointing to the same datastore will be part of the same Kong cluster.

Having a Kong cluster does not mean that your clients traffic will be load-balanced across your Kong nodes out of the box. You still need a load-balancer in front of your Kong nodes to distribute your traffic. Instead, a Kong cluster means that those nodes will share the same configuration.

This document clearly explains that a Kong cluster is stateless (hence, no such /cluster endpoint), and the sole purpose of “clustering” is to propagate cache invalidation events of configuration entities (all entities configured via the Admin API are cached by each Kong node, and thus need invalidation when you perform, say, a DELETE on one of these entities).

To verify that your cluster is working, you can configure some Services/Routes on a node, hit the other node, and verify that it has the same settings. If you delete the configured Service/Route from one of the nodes, the change should eventually be propagated to the other node.

Really, all of this is explained in the document we linked you to.

Thank you very much .

I can see the Services component in another Kong node which joined later:

[root@localhost test]$curl -XGET http://localhost:8001/services

I am sorry that I made this complicated, I didn’t expect that the configuration of cluster was so simply.
But I still think it would be much better if clearly explained the configuration and demonstrated cluster’s work.
Because of the misunderstanding of old version manual , I verified the cluster by using “kong cluster” command and getting the endpoint of “/cluster”. I didn’t know how to verify if I did the right things to set up a cluster and if it was running or not .

Thank you very much again,
And thanks all kind people to comment and help me !