If you’ve tried to install Kong from scratch, you know that it is a little more involved than what is posted on the official website guide. There are some pre-requisites that the system needs to be set up with, in order to make sure the service installs and runs successfully. Let us take a look at the steps involved in setting up a Kong instance from the ground up.
This guide is valid for RHEL 7, PostgreSQL 11, and Kong 0.14.1.
We will set up Kong on a VMware virtual machine. If you are using another hypervisor, the steps for hardware configurations may differ slightly.
First, let us take a look at the pre-requisite steps that need to be addressed before we begin our work.
- RHEL 7 VM with minimum/base packages
- A valid Subscription with RedHat with appropriate entitlements
- Static IP configuration set up
- /etc/hosts configured for name resolution
- /etc/hostname set up with the fully qualified domain name
- SSH Keys copied on your local workstation (optional)
- Nameserver set up
- firewalld service disabled
- Yum enabled
- Non-root user set up for sudo access (optional)
- VMware tools package installed
Prepare and Install OS Packages
Since we set up RHEL with minimal packages, we would need to enable all the needed rpms.
First register with subscription manager using your Red Hat profile credentials: subscription-manager register
subscription-manager refresh
subscription-manager attach –-auto
subscription-manager repos –-list
subscription-manager repos –enable rhel-7-server-rh-common-beta-rpms
subscription-manager repos –enable rhel-7-server-rpms
subscription-manager repos –enable rhel-7-server-source-rpms
subscription-manager repos –enable rhel-7-server-rh-common-source-rpms
subscription-manager repos –enable rhel-7-server-rh-common-debug-rpms
subscription-manager repos –enable rhel-7-server-optional-source-rpms
subscription-manager repos –enable rhel-7-server-extras-rpms
Finish setting up other utils:
yum repolist
yum -y update
yum –y install wget
PostgreSQL 11 Installation
We will first have to set up PostgreSQL 9.5+ or Cassandra database to use with Kong. The version compatibility is listed on Kong’s website. We decided to go with PostgreSQL 11.
Download the latest build for PostgreSQL 11
curl -O https://download.postgresql.org/pub/repos/yum/11/redhat/rhel-7-x86_64/pgdg-redhat11-11-2.noarch.rpm
Extract the package
rpm -ivh pgdg-redhat11-11-2.noarch.rpm
Find the relevant RPMs and install
yum list postgres*
yum install postgresql11-server.x86_64
Initialize the DB
/usr/pgsql-11/bin/postgresql-11-setup initdb
Start the PostgreSQL service
systemctl enable postgresql-11.service
systemctl start postgresql-11.service
Verify the install was successful and the service is up, as well as set the database password
su – postgres -c “psql”
postgres=# \password postgres
postgres-# \q
Set up the database for Kong
postgres=# create user kong; create database kong owner kong;
Make a note of the configuration file location. We will need this later
postgres=# show hba_file;
hba_file
————————————
/var/lib/pgsql/11/data/pg_hba.conf
(1 row)
We will also set (or update) the password for the kong user. It is recommended you use a password with no numbers (string only). It has been observed with previous versions that using numbers in the password can cause issues. Since this will be lab environment, it may be easier to choose a string only password and avoid troubleshooting any potential issues caused due to this.
postgres=# alter user kong with password ‘kong’;
Kong 0.14.1 Installation
Enable the relevant EPEL repository
EL_VERSION=`cat /etc/redhat-release | grep -oE ‘[0-9]+\.[0-9]+’` && \
> sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${EL_VERSION%.*}.noarch.rpm
Fetch the latest Kong package
The saved file gets a strange name, so let’s change the name to make it cleaner
mv download_file\?file_path\=rhel%2F7%2Fkong-community-edition-0.14.1.rhel7.noarch.rpm kong-community-edition-0.14.1.rhel7.noarch.rpm
Extract the package
rpm -ivh kong-community-edition-0.14.1.rhel7.noarch.rpm
You can now verify the install by running the command kong on the prompt. It will display various command options for kong.
We will now need to modify the PostgreSQL config file to make sure the database allows connections from Kong. We had noted the location of the pg_hba.conf file earlier in the database install section.
vi /var/lib/pgsql/11/data/pg_hba.conf
Add the IP of Kong host (or let the default entry of 127.0.0.1 stay as is, if installing on the same host as the database) under the IPv4 section.
Change the authentication method from ident to md5. This is important – otherwise you will get ident authentication errors when you try to start the kong service later.
The Kong configuration file that ships with the package has an extension .default to it. We therefore copy the default file to the .conf extension before making changes
cp /etc/kong/kong.conf.default /etc/kong/kong.conf
By default, all entries in the configuration file are commented out. You can choose to let them be as is. Or you can decide to uncomment specific sections or specific lines. In our case, we will do the following:
1) Under the GENERAL section, uncomment the prefix line, and update it to the following path
prefix = /etc/nginx/ssl
2) Under the NGINX section, uncomment the admin_listen line, and update it as per the following
admin_listen = <Kong_Server_IP>:8001, 127.0.0.1:8001, 127.0.0.1:8444 ssl
3) Under the DATASTORE section, uncomment the lines for postgresql, and update them with the connection information for your database.
database = postgres
pg_host = 127.0.0.1
pg_port = 5432
pg_user = kong
pg_password = <Password you set during DB initiation>
pg_database = kong
pg_ssl = off
pg_ssl_verify = off
Save and exit the configuration file.
Also note that we changed the default prefix path; so we will need to manually create a directory for that path, and chmod the appropriate permissions for that folder.
cd /etc
mkdir nginx
cd nginx
mkdir ssl
cd /
chown –R root:root /etc/nginx/ssl
chmod –R 600 /etc/nginx/ssl
Run Kong migrations
kong migrations up [-c /etc/kong/kong.conf] –v
Start the Kong service
kong start [-c /etc/kong/kong.conf] –v
Verify the service is up and running
curl -i http://<Kong_Server_IP>:8001/
You can also verify the service status by going to URL http://<Kong_Server_IP>:8001/ via a browser.
Troubleshooting
1) Error: Absolute path to the certificate
/usr/local/share/lua/5.1/kong/cmd/start.lua:71: /usr/local/share/lua/5.1/kong/cmd/start.lua:28: nginx configuration is invalid (exit code 1):
nginx: [emerg] SSL_CTX_load_verify_locations(“/etc/nginx/ssl/# Absolute path to the certificate”) failed (SSL: error:02001002:system library:fopen:No such file or directory:fopen(‘/etc/nginx/ssl/# Absolute path to the certificate’,’r’) error:2006D080:BIO routines:BIO_new_file:no such file error:0B084002:x509 certificate routines:X509_load_cert_crl_file:system lib)
nginx: configuration file /etc/nginx/ssl/nginx.conf test failed
If you get an error like the above, make sure that the DEVELOPMENT & MISCELLANEOUS section in the /etc/kong/kong.conf file are all commented out. If you are not using SSL certificates, you may want to comment out all lines that point to the certificate path (e.g. #lua_ssl_trusted_certificate = )
2) Error: Permission Denied
This could be caused by Kong trying to access the default prefix path of /usr/local/kong without proper permissions. If the install is being run by a non-root user, you will have to provide folder write permissions for that user as well. Alternatively, you can manually create a different folder (see instructions above) and assign appropriate write permissions to it.
3) Error: During service verification, the curl command works, but the browser URL access fails with Page Not Found
Make sure that the admin_listen = <Kong_Server_IP>:8001, 127.0.0.1:8001, 127.0.0.1:8444 ssl line is not commented out in the /etc/kong/kong.conf file. Also, Kong_Server_IP should reflect the IPv4 address of the server where Kong is installed.
4) Error: Unauthorized ident access
Make sure that in the postgresql configuration file (/var/lib/pgsql/11/data/pg_hba.conf), the access method for the kong host is set to md5.
5) Error: In postgres.lua Expected value but found T_END at character 1
Check the database configuration parameters in /etc/kong/kong.conf. Verify the database server name, IP, and credentials are correct. Also, try to drop the database and recreating it within PostgreSQL (in case the database got corrupt). You can do so by running the commands
postgres=# drop database kong;
postgres=# create database kong owner kong;
and then restarting the PostgreSQL service from the console
systemctl stop postgresql-11
systemctl start postgresql-11
If you have any questions about the steps documented here, would like more information on the installation procedure, or have any feedback or requests, please let us know at [email protected].
Anuj joined Keyva from Tech Data where he was the Director of Automation Solutions. In this role, he specializes in developing and delivering vendor-agnostic solutions that avoid the “rip-and-replace” of existing IT investments. Tuli has worked on Cloud Automation, DevOps, Cloud Readiness Assessments and Migrations projects for healthcare, banking, ISP, telecommunications, government and other sectors.
During his previous years at Avnet, Seamless Technologies, and other organizations, he held multiple roles in the Cloud and Automation areas. Most recently, he led the development and management of Cloud Automation IP (intellectual property) and related professional services. He holds certifications for AWS, VMware, HPE, BMC and ITIL, and offers a hands-on perspective on these technologies.
Like what you read? Follow Anuj on LinkedIn at https://www.linkedin.com/in/anujtuli/