Deploy your Bitnami Kong Stack on Microsoft Azure now! Launch Now

Bitnami Kong for Microsoft Azure

Description

Kong is an open source API gateway and microservice management layer. It is designed for high availability, fault-tolerance and distributed systems.

First steps with the Bitnami Kong Stack

Welcome to your new Bitnami application running on Microsoft Azure! Here are a few questions (and answers!) you might need when first starting with your application.

What credentials do I need?

You need two sets of credentials:

  • The application credentials, consisting of a username and password. These credentials allow you to log in to your new Bitnami application.

  • The server credentials, consisting of an SSH username and key/password. These credentials allow you to log in to your Microsoft Azure server using an SSH client and execute commands on the server using the command line.

What is the administrator username set for me to log in to the application for the first time?

Username: cassandra

What is the administrator password?

What SSH username should I use for secure shell access to my application?

SSH username: bitnami

How do I get my SSH key or password?

What are the default ports?

A port is an endpoint of communication in an operating system that identifies a specific process or a type of service. Bitnami stacks include several services or servers that require a port.

Remember that if you need to open some ports you can follow the instructions given in the FAQ to learn how to open the server ports for remote access.

Port 22 is the default port for SSH connections.

Bitnami opens some ports for the main servers. These are the ports opened by default: 80, 443, 8000, 8443.

Getting started with Bitnami Kong Stack

Kong installation folder is located in /opt/bitnami/apps/kong/, which has the following contents:

  • openresty/: contains Openresty, LuaJIT and Luarocks libraries and binary files.
    • openresty/nginx : Openresty's bundled Nginx server
    • openresty/luajit/: LuaJIT folder. Lua modules can be found in openresty/luajit/lib and openresty/luajit/share. All binary files can be found in openresty/luajit/bin.
  • serf/: Serf Cluster management used by Kong
  • conf/: Kong's configuration files.
  • server/: Kong's server working directory
  • bin/: Kong's binary resides here.

Apart from this, you can find Cassandra located in /opt/bitnami/cassandra.

In order to manage Kong, you can use /opt/bitnami/ctlscript.sh, which allows start, stop and check the status of Kong:

$ sudo /opt/bitnami/ctlscript.sh start kong # Start Kong
$ sudo /opt/bitnami/ctlscript.sh stop kong  # Stop Kong
$ sudo /opt/bitnami/ctlscript.sh restart kong  # Restart Kong
$ sudo /opt/bitnami/ctlscript.sh status kong # Check Kong status

Alternatively, you can also use the bin/kong command which is located in /opt/bitnami/apps/kong/. Please note that it must be executed as the user kong in order to work correctly.

$ cd /opt/bitnami/apps/kong
$ sudo su kong
$ bin/kong start  # Start Kong
$ bin/kong stop   # Stop Kong
$ bin/kong restart   # Restart Kong
$ bin/kong status # Check Kong status

You can find a 5-minute quickstart guide (where you will create an API, a consumer and enable the key-auth plugin) in Kong's official getting started documentation.

How to access the Kong server console?

For security reasons, the Kong server console will be accessible only when using 127.0.0.1 as the hostname. To access the server console, it is necessary to create an SSH tunnel by forwarding port 8001 on the Kong server to port 8001 on the local host.

An example of configuring the SSH tunnel using PuTTY on Windows is displayed below.

PuTTY tunnel config

While the tunnel is active, you should be able to access the server console through the secure SSH tunnel you created, by browsing to http://127.0.0.1:8001/.

Refer to the FAQ for platform-specific instructions to create the SSH tunnel.

What is the default configuration?

Kong configuration file

Kong's configuration properties are set in /opt/bitnami/apps/kong/conf/kong.conf. The most important properties are:

  • database: This is the datastore used by Kong, and it is fundamental for setting a Kong cluster. The default image uses Cassandra as its default provider.
  • proxy_listen: This is the address at which Kong's proxy will listen. Even though its default value is 0.0.0.0:8000, open the corresponding port in order to allow remote requests.
  • admin_listen: This is the address at which Kong's administration interface will listen for requests. Its default value is 127.0.0.1:8001 (and 127.0.0.1:8444 for SSL), and you will need to SSH your instance in order to access it.
  • cluster: All the properties starting with cluster (such as cluster_encrypt_key or cluster_listen) are important when configuring Kong in cluster mode.

If you modify your configuration file, do not forget to restart Kong:

$ sudo /opt/bitnami/ctlscript.sh restart kong  # Restart Kong

Kong also allows setting configuration via environment variables (which override the contents of kong.conf). You can set them in /opt/bitnami/scripts/setenv.sh.

Find a full reference of the different configuration properties in the configuration reference in Kong's site.

Kong ports

  • Port 80: Welcome page.
  • Port 8000: Kong API forward port.
  • Port 8001: Kong admin API port. Only connections from localhost are permitted.

Kong log file

  • Kong log files are created at:
    • /opt/bitnami/apps/server/logs/access.log
    • /opt/bitnami/apps/server/logs/admin_access.log
    • /opt/bitnami/apps/server/logs/error.log
  • Cassandra log file: /opt/bitnami/cassandra/log/system.log.

How to start or stop the services?

Each Bitnami stack includes a control script that lets you easily stop, start and restart services. The script is located at /opt/bitnami/ctlscript.sh. Call it without any service name arguments to start all services:

$ sudo /opt/bitnami/ctlscript.sh start

Or use it to restart a single service, such as Apache only, by passing the service name as argument:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Use this script to stop all services:

$ sudo /opt/bitnami/ctlscript.sh stop

Restart the services by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh restart

Obtain a list of available services and operations by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh

How to access the administration panel?

Access the administration panel by browsing to http://SERVER-IP//.

How to create a full backup of Kong?

Backup

The Bitnami Kong Stack is self-contained and the simplest option for performing a backup is to copy or compress the Bitnami stack installation directory. To do so in a safe manner, you will need to stop all servers, so this method may not be appropriate if you have people accessing the application continuously.

Follow these steps:

  • Change to the directory in which you wish to save your backup:

      $ cd /your/directory
    
  • Stop all servers:

      $ sudo /opt/bitnami/ctlscript.sh stop
    
  • Remove the following files in Kong's server directory:

      $ sudo rm /opt/bitnami/apps/kong/server/pids/*.pid
      $ sudo rm /opt/bitnami/apps/kong/server/serf/serf.id
    
  • Create a compressed file with the stack contents:

      $ sudo tar -pczvf application-backup.tar.gz /opt/bitnami
    
  • Restart all servers:

      $ sudo /opt/bitnami/ctlscript.sh start
    

You should now download or transfer the application-backup.tar.gz file to a safe location.

Restore

Follow these steps:

  • Change to the directory containing your backup:

      $ cd /your/directory
    
  • Stop all servers:

      $ sudo /opt/bitnami/ctlscript.sh stop
    
  • Move the current stack to a different location:

      $ sudo mv /opt/bitnami /tmp/bitnami-backup
    
  • Uncompress the backup file to the original directoryv

      $ sudo tar -pxzvf application-backup.tar.gz -C /
    
  • Start all servers:

    $ sudo /opt/bitnami/ctlscript.sh start
    

How to create a Virtual Network peering?

To connect two instances internally you can enable a Virtual Network (VNet) peering from the Azure Portal. Depending if the instances were launched in the same or in different resource groups, there are two methods for performing a internal connection: sharing a virtual network or enabling a virtual network peering.

How to upload files to the server with SFTP?

Although you can use any SFTP/SCP client to transfer files to your server, the link below explains how to configure FileZilla (Windows, Linux and Mac OS X), WinSCP (Windows) and Cyberduck (Mac OS X). It is required to use your server's private SSH key to configure the SFTP client properly. Choose your preferred application and follow the steps in the link below to connect to the server through SFTP.

How to upload files to the server

Troubleshooting Kong

How to debug errors in Kong?

If Kong is not working properly, change the logging level of the application in /opt/bitnami/apps/kong/conf/kong.conf. Change the log_level line so it ends like this:

  log_level = debug

Save the file and restart kong:

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

Now you will be able to get more details of the errors in /opt/bitnami/apps/kong/server/logs/error.log. When the cause of the error is found, you can restore /opt/bitnami/apps/kong/conf/kong.conf to its original contents.

How To 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 accesible 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 via SSH to the seed node. Then 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 via SSH and execute the following command to stop Kong:

      $ sudo /opt/bitnami/ctlscript.sh stop kong 
    
Steps on Kong nodes
  • Log in via SSH and 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
    

How to set Kong for production environments?

By default, the Kong proxy server works at ports 8000 and 8443. In production environments it is desirable to change these ports to 80 and 443, respectively. In order to do so, you can follow these steps:

  • Stop Kong:

    $ sudo /opt/bitnami/ctlscript.sh stop kong
    
  • Modify /opt/bitnami/apps/kong/conf/kong.conf by changing these contents:

     proxy_listen = 0.0.0.0:80
     proxy_listen_ssl = 0.0.0.0:443
    
  • Remove the following line in /opt/bitnami/apps/kong/conf/kong_nginx.tmpl:

     include /opt/bitnami/apps/bitnami/banner/conf/infopage.conf;
    
  • Restart Kong:

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

After this change, Kong's API will work at ports 80 and 443 instead of 8000 and 8443. Therefore, the curl command that can be seen in Kong's API Forward Example would change from:

$ curl -i -X GET \
  --url http://localhost:8000/ \
  --header 'Host: example.com'

To:

$ curl -i -X GET \
  --url http://localhost/ \
  --header 'Host: example.com'

If you want to restore the original setup, then change both /opt/bitnami/apps/kong/conf/kong.conf and /opt/bitnami/apps/kong/conf/kong_nginx.tmpl to their original contents.

azure

Bitnami Documentation