This blog walks through the installation of Kong Enterprise (via rpm) on a CentOS 7 Virtual Machine. You can download and install the latest version of CentOS from https://www.centos.org/download/. We will be installing Kong Enterprise in a development environment so it is recommended that you use at least 2 GB of RAM and 2 vCPUs with 20 GB of storage space.
Additionally, it is recommended to setup 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 on the same server. For production environments, you can choose to install the database and application tiers on separate machines. To get started, on the Kong Enterprise server, run the following commands:
sudo yum update
sudo yum install wget
sudo yum install python36
sudo pip3 install httpie
We will also create a new folder to store the Kong RPMs:
mkdir kong
In order to download Kong Enterprise you will need to work with your Kong Partner Manager or Kong Enterprise sales rep 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.
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. Steps for the latter are below.
On a separate machine, download the specific rpm for your OS and version (kong-enterprise-edition-0.36-4.el7.noarch.rpm) and the license file. In this case, we first download the files under the ‘Downloads’ folder on the jump box, and then SCP the files to the target VM.
scp ~/Downloads/kong-enterprise-edition-0.36-4.el7.noarch.rpm
root@<Kong-Enterprise-VM-IP>:~/kong
scp ~/Downloads/ex12162020.license.json root@
<Kong-Enterprise-VM-IP>
:~/kong
Log back into the Kong Enterprise VM via SSH:
cd /root/kong
sudo yum install kong-enterprise-edition-0.36-4.el7.noarch.rpm
sudo cp ex12162020.license.json /etc/kong/license.json
sudo yum install
https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum --disablerepo=bintray--kong-kong-enterprise-edition-rpm 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
Login to the PostgreSQL database, and create the necessary structures for Kong Enterprise installation. Note: For this example, we are using kong as our username, database name, and password. You will want to choose user, database, and passwords according to the naming and complexity standards of your organization. If you need assistance with this step, your friends at Keyva are no more than a click away!
For this example, we are using kong as our username, database name, and password.
sudo -i -u postgres
$ psql
$ CREATE USER kong; CREATE DATABASE kong OWNER kong; ALTER USER kong WITH password 'kong';
$ \q
$ exit
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
Update the database configuration file postgresql.conf:
sudo vi /var/lib/pgsql/9.5/data/postgresql.conf
Add the line at the end –
listen_addresses = '*'
Restart the PostgreSQL server:
sudo systemctl restart postgresql-9.5
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
Update the following variables with your environment specific values:
sudo vi /etc/kong/kong.conf
database = postgres
pg_host = <Kong-Enterprise-VM-IP>
pg_port = 5432
pg_timeout = 5000
pg_user = kong
pg_password = kong
pg_database = kong
Update the user environment with ulimit value:
vi $HOME/.bashrc
At the end of the file, add
ulimit –n 4096
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
Update permissions:
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
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 this record in the 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 is 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’
: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 in to specific errors not covered here, please feel free to reach out to info@keyvatech.com
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/
Join the Keyva Community! Follow Keyva on LinkedIn at: