This blog walks through the installation of Kong Enterprise (via rpm) on a Red Hat Enterprise 7 Virtual Machine.
Since we will be installing Kong Enterprise in a development environment, it is recommended that you use at least 2 GB of RAM and 2 vCPUs with 20 GB of storage space for your virtual machine.
It is also recommended to set up VMware tools. In order to do that, you will need to mount the VMware tools via the VMware console, and run the following commands via SSH.
yum install perl
mkdir /mnt/cdrom
Mount /dev/cdrom /mnt/cdrom
cp /mnt/cdrom/VMwareTools-
version
.tar.gz /tmp/
tar -zxvf VMwareTools-
version
.tar.gz
/tmp/vmware-tools-distrib/./vmware-install.pl
umount /mnt/cdrom
In this tutorial, we will install the Kong Enterprise server and the required PostgreSQL database on the same server. For production environments, you can choose to install the database and application tiers on separate machines. On the Kong Enterprise server, run the following commands:
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
sudo yum update
sudo yum install wget
sudo yum install python36
sudo pip3 install httpie
For this development instance, we will stop and disable the firewall on the local machine, and then install PostgreSQL locally:
sudo systemctl stop firewalld
sudo systemctl disable firewalld
Download PostgreSQL RPM
sudo yum install
https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
Install PostgreSQL
sudo yum install postgresql95 postgresql95-server
Initialize the PostgreSQL Database, and start it:
sudo /usr/pgsql-9.5/bin/postgresql95-setup initdb
sudo systemctl enable postgresql-9.5
sudo systemctl start postgresql-9.5
Log in to the PostgreSQL database, and create the necessary structures for Kong Enterprise installation (Note that you will want to follow naming & password standards for your organization):
sudo -i -u postgres
$ psql
$ CREATE USER kong; CREATE DATABASE kong OWNER kong; ALTER USER kong WITH password 'kong';
$ \q
$ exit
Backup the original postgresql.conf file before modification
sudo cp /var/lib/pgsql/9.5/data/postgresql.conf /var/lib/pgsql/9.5/data/postgresql.conf.orig
Update the database configuration file postgresql.conf
sudo vi /var/lib/pgsql/9.5/data/postgresql.conf
Update the postgresql.conf file with the listen_addresses entry
listen_addresses = '*'
Backup the original pg_hba.conf file before modification
sudo cp /var/lib/pgsql/9.5/data/pg_hba.conf /var/lib/pgsql/9.5/data/pg_hba.conf.orig
Update database settings in pg_hba.conf
sudo vi /var/lib/pgsql/9.5/data/pg_hba.conf
Change the IPv4 entry to the IP address and the method to md5
host all all 0.0.0.0/0 md5
Restart PostgreSQL server
sudo systemctl restart postgresql-9.5
sudo systemctl status postgresql-9.5
Let’s create a new folder to store the Kong RPMs:
mkdir kong
cd kong
In order to download Kong Enterprise, please work with your Kong Partner Manager or Account Executive to get access to your specific repository. Log in with your credentials at https://bintray.com/kong
The license file is located in the folder with your company or repository name.
On a separate machine, download the license file from the Kong repository portal, and then SCP it to the target VM.
scp ~/Downloads/ex12162020.license.json root@
<Kong-Enterprise-VM-IP>
:~/kong
You can either use wget to download the kong rpm and the license files directly on the VM, or you can download the files on a jump box and transfer them to the Kong Enterprise VM. We will use wget in this example:
wget '
https://<kong-supplied-username>:<kong-supplied-password>@bintray.com/kong/kong-enterprise-edition-rpm/rpm
' -O bintray-kong-kong-enterprise-edition-rpm.repo --auth-no-challenge
Copy the repo file under /etc/yum.repos.d
sudo mv bintray-kong-kong-enterprise-edition-rpm.repo /etc/yum.repos.d/
Next we will need to get the API key from the Kong bintray portal. Once you log in to https://bintray.com/kong click on your Username -> Edit Profile -> API Key
Update the repo file that we copied earlier
sudo vi /etc/yum.repos.d/bintray-kong-kong-enterprise-edition-rpm.repo
Modify the baseurl line by adding in your username and API key
#bintray--kong-kong-enterprise-edition-rpm - packages by from Bintray
[bintray--kong-kong-enterprise-edition-rpm]
name=bintray--kong-kong-enterprise-edition-rpm
baseurl=https://<Username>:<User-API-Key>@kong.bintray.com/kong-enterprise-edition-rpm/rhel/7
gpgcheck=0
repo_gpgcheck=0
enabled=1
Install the Kong service
sudo yum install kong-enterprise-edition
Add the language settings for the user environment:
sudo vi /etc/environment
Add the following lines
LANGUAGE=en_US.utf-8
LC_ALL=en_US.UTF-8
LC_CTYPE=UTF-8
LANG=en_US.utf-8
Logout of the session, and log in again
Update the user environment with ulimit value:
vi $HOME/.bashrc
At the end of the file, add
ulimit –n 4096
Save a copy of the default Kong conf file that ships with the installation before making modifications:
cp /etc/kong/kong.conf.default /etc/kong/kong.conf
sudo vi /etc/kong/kong.conf
Update the following variables with your environment specific values:
database = postgres
pg_host = <Kong-Enterprise-VM-IP>
pg_port = 5432
pg_timeout = 5000
pg_user = kong
pg_password = kong
pg_database = kong
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl
We will now move the license file under the /etc/kong folder
sudo cp ex12162020.license.json /etc/kong/license.json
Update permissions for kong user
sudo chmod -R 777 /usr/local/kong/
Important: The KONG_PASSWORD environment variable needs to be exported before running the database migration and bootstrap processes. The password defined in this variable will be used to log in to the Kong Enterprise console once it is set up:
export KONG_PASSWORD=kong
kong migrations bootstrap -c /etc/kong/kong.conf -vv
kong start -c /etc/kong/kong.conf
Run a test against the local service to make sure Kong is up and running:
curl -i -X GET --url
http://localhost:8001/services
You can access the Kong Enterprise portal here:
http://<Kong-Enterprise-VM-IP>:8002/
https://<Kong-Enterprise-VM-IP>:8445/
Troubleshooting
Even the best-made plans can occasionally go awry, but don’t worry, your friends at Keyva have your back. In our experience here’s a list of some issues you could encounter, and if you do, how to fix them.
1) If you are unable to open or access the portal, make sure the firewall is turned off
sudo systemctl stop firewalld
2) Error: [PostgreSQL error] failed to retrieve server_version_num: connection refused OR
Error: [PostgreSQL error] failed to retrieve server_version_num: host or service not provided, or not known
Possible Remediations:
- Database timing issue after restart of db – sometimes it can take up to 10 mins for the database to be ready for Kong to connect
- Try restarting the Kong server
- In pg_hba.conf add the record in this file host all all 0.0.0.0/0 trust
- Make sure the following environment variables are set up and they exist prior to running the database migration and bootstrap process: export KONG_DATABASE=postgres export KONG_PG_HOST=<Kong-Enterprise-VM-IP>
3) “Username/Password is invalid” – for the kong admin portal
Try running the bootstrap process again and clearing the browser cache
kong migrations reset
kong migrations bootstrap -c /etc/kong/kong.conf
kong migrations bootstrap
kong reload
kong stop
kong start
Try clearing cache, and going directly to the URL https://<Kong-Enterprise-VM-IP>:8445/overview
Important: You will also need to go to the URL https://<Kong-Enterprise-VM-IP>:8444 and accept the certificate. After accepting the certificate, go to the URL https://<Kong-Enterprise-VM-IP>:8445
4) “RBAC is disabled! Configuration will not be applied until RBAC is enabled. ”
Rbac enabled but still keeps showing as disabled when you go to :8002/overview
In order to use RBAC, you will need to set up the following variables in kong.conf:
enforce_rbac = on
admin_gui_auth = basic-auth
admin_gui_session_conf = { "secret":"your_secret_text" }
Reload and restart kong service
kong reload
kong stop
kong start
5) Error: /usr/local/share/lua/5.1/kong/cmd/start.lua:31: [PostgreSQL error] failed to retrieve server_version_num: FATAL: no pg_hba.conf entry for host “127.0.0.1”, user “kong”, database “kong”, SSL off
Verify that the below line exists in pg_hba.conf file
host all all 0.0.0.0/0 md5
You can also try adding the following line to trust all endpoints
host all all 0.0.0.0/0 trust
6) Error: /usr/local/share/lua/5.1/kong/db/migrations/state.lua:291: attempt to index local ‘legacy_res’ (a nil value)
stack traceback:
/usr/local/share/lua/5.1/kong/db/migrations/state.lua:291: in function ‘load’
/usr/local/share/lua/5.1/kong/db/init.lua:412: in function ‘schema_state’
/usr/local/share/lua/5.1/kong/cmd/migrations.lua:111: in function ‘cmd_exec’
/usr/local/share/lua/5.1/kong/cmd/init.lua:88: in function </usr/local/share/lua/5.1/kong/cmd/init.lua:88>
[C]: in function ‘xpcall’
/usr/local/share/lua/5.1/kong/cmd/init.lua:88: in function </usr/local/share/lua/5.1/kong/cmd/init.lua:45>
/usr/local/bin/kong:9: in function ‘file_gen’
init_worker_by_lua:50: in function <init_worker_by_lua:48>
[C]: in function ‘xpcall’
init_worker_by_lua:57: in function <init_worker_by_lua:55>
Verify that the following environment variables are exported
export KONG_DATABASE=postgres
export KONG_PG_HOST=kong-database
Restart the PostgreSQL, and Kong service
sudo systemctl status postgresql
kong reload
kong stop
kong start
7) Error: /usr/local/share/lua/5.1/kong/cmd/migrations.lua:109: [PostgreSQL error] failed to retrieve server_version_num: host or service not provided, or not known
stack traceback:
[C]: in function ‘assert’
/usr/local/share/lua/5.1/kong/cmd/migrations.lua:109: in function ‘cmd_exec’
/usr/local/share/lua/5.1/kong/cmd/init.lua:88: in function </usr/local/share/lua/5.1/kong/cmd/init.lua:88>
[C]: in function ‘xpcall’
/usr/local/share/lua/5.1/kong/cmd/init.lua:88: in function </usr/local/share/lua/5.1/kong/cmd/init.lua:45>
/usr/local/bin/kong:9: in function ‘file_gen’
init_worker_by_lua:50: in function <init_worker_by_lua:48>
[C]: in function ‘xpcall’
init_worker_by_lua:57: in function <init_worker_by_lua:55>
Verify that the following environment variable is exported
export KONG_PG_HOST=<Kong-Enterprise-VM-IP>
Restart the PostgreSQL, and Kong service
sudo systemctl status postgresql
kong reload
kong stop
kong start
8) Kong Manager portal error: “Authentication is not enabled. ”
Set basic authentication variable (admin-gui-auth) configured in the kong.conf file
enforce_rbac = on
admin_gui_auth = basic-auth
admin_gui_session_conf = { "secret":"your_secret_text" }
Reload and restart kong service
kong reload
kong stop
kong start
If you have any questions or comments on the tutorial content above, or run into specific errors not covered here, please feel free to reach out to info@keyvatech.com
Anuj Tuli is the chief technology officer at Keyva. In this role, he specializes in developing and delivering vendor-agnostic solutions that avoid the “rip-and-replace” of existing IT investments. Tuli helps customers chart a prescriptive strategy for Application Containerization, CI/CD Pipeline Implementations, API abstraction, Application Modernization, and Cloud Automation integrations. He leads the development and management of Cloud Automation IP and related professional services. With an application developer background, he provides a hands-on perspective towards various technologies.
Like what you read? Follow Anuj on LinkedIn.
Join the Keyva Community! Follow Keyva on LinkedIn at: