generalkong

Create a Kong cluster

Kong allows to configure a cluster of several Kong nodes. In order to do so, the following must be taken into account:

  • Kong only allows IP addresses. Therefore, no DNS addresses can be used.
  • All instances reside in a flat network topology. Therefore, there cannot be any NAT (Network Address Translation) between the two datacenters. A common set-up would be configuring a Virtual Private Network (VPN) between all your Kong nodes. Another option would be using public IP addresses.

In this documentation, each node acts as a Datastore and a Kong node. Figure 1 shows this configuration.

Figure 1: Kong Cluster

In this guide, the following set-up is assumed:

  • You already have an instance with Kong and Cassandra up and running (“Seed node” from now on). In this guide it will have the address 10.1.15.3
  • All instances reside in the same flat network 10.1.15.0/24
  • All instances are accessible via SSH.
  • In the examples, Kong Datastore will have Cassandra password “foofoo123123”
  • The example string “Na5P3WKqXi9UDOsG43eSTg==" will be used as the Kong Cluster encrypt Key.

Before starting, stop Cassandra and Kong services in all the newly created instances (all but the Seed node):

$ sudo /opt/bitnami/ctlscript.sh stop kong
$ sudo /opt/bitnami/ctlscript.sh stop cassandra

Configure Database cluster

The following steps must be done in all the nodes but the Seed node:

  • Log in via SSH and modify the contents of /opt/bitnami/cassandra/conf/cassandra.yaml:

    From:

        # seeds is actually a comma-delimited list of addresses.
                 - seeds: "127.0.0.1"
    

    To:

        # seeds is actually a comma-delimited list of addresses.
                 - seeds: "<Seed Node Address>"
    

    Example:

        # seeds is actually a comma-delimited list of addresses.
                 - seeds: "10.1.15.3"
    
  • Execute the following command:

        $ sudo rm -rf /opt/bitnami/cassandra/data/*
    
  • Start Cassandra:

        $ sudo /opt/bitnami/ctlscript.sh start cassandra
    

    NOTE: For consistency reasons, it is better to wait 2 minutes between node additions. If you come across the error cannot bootstrap while cassandra.consistent.rangemovement is true, then repeat the previous two steps.

  • Now you have a Cassandra cluster up and running

Configure database password

The following steps must be done only on the Seed node:

  • Log in to the server console using SSH. Learn how to connect to the server through SSH.

  • Find the following information in /opt/bitnami/apps/kong/conf/kong.conf

        cassandra_username = bn_kong
        cassandra_password = KONG_DB_PASSWORD
    
  • Note down the value of KONG_DB_PASSWORD, as it will be used in later steps.

The following steps must be done in all the nodes except the Seed node:

  • Modify /opt/bitnami/apps/kong/conf/kong.conf by changing the database password value (using the previously noted KONG_DB_PASSWORD):

        cassandra_username = bn_kong
        cassandra_password = KONG_DB_PASSWORD
    

    Example:

        cassandra_username = bn_kong
        cassandra_password = foofoo123123
    

Restart Kong

  • The only step remaining is to start Kong on every node but the Seed node:

      $ sudo /opt/bitnami/ctlscript.sh start kong
    

Another configuration: Kong and Cassandra separated

Apart from the previously explained configuration, you can have Kong and Cassandra separated in different nodes (Datastore and Kong nodes), just like it is shown in figure 2.

Figure 2: Alternative Kong Cluster Configuration

This section assumes that you have configured your cluster as described previously.

Steps on Datastore nodes

  • Log in to the server console. Learn how to connect to the server through SSH.

  • Execute the following command to stop Kong:

      $ sudo /opt/bitnami/ctlscript.sh stop kong
    

Steps on Kong nodes

  • Log in to the server console. Learn how to connect to the server through SSH.

  • Execute the following command to stop Cassandra and Kong:

      $ sudo /opt/bitnami/ctlscript.sh stop cassandra
      $ sudo /opt/bitnami/ctlscript.sh stop kong
    
  • Modify /opt/bitnami/apps/kong/conf/kong.conf by changing the contact points values:

    To:

      cassandra_contact_points = DATASTORE_IP_1,DATASTORE_IP_2,...
    

    Example (for a cluster with 4 Kong Datastore nodes):

      cassandra_contact_points = 10.1.15.20,10.1.15.21,10.1.15.22,10.1.15.23
    
  • Start Kong:

      $ sudo /opt/bitnami/ctlscript.sh start kong
    
Last modification December 21, 2022