You are browsing documentation for an older version. See the latest documentation here.
Install Kong Gateway on CentOS
The Kong Gateway software is governed by the Kong Software License Agreement. Kong is licensed under an Apache 2.0 license.
Prerequisites
- A supported system with root or root-equivalent access.
- (Enterprise only) A
license.json
file from Kong
Download and Install
You can install Kong Gateway by downloading an installation package or using our yum repository.
Set up configs
Kong Gateway comes with a default configuration property file that can be found
at /etc/kong/kong.conf.default
if you installed Kong Gateway with one of the official packages.
This configuration file is used for setting Kong Gateway’s configuration properties at startup.
Kong Gateway offers two options for storing the configuration properties for all of
Kong Gateway’s configured entities, a database or a yaml declarative configuration file.
Before starting Kong Gateway you must update the kong.conf.default
configuration property file with a reference
to your data store.
To alter the default properties listed in the kong.conf.default
file and configure Kong Gateway,
make a copy of the file, rename it (for example kong.conf
), make your updates, and save it to the same location.
Using a database
First, configure Kong Gateway using the kong.conf
configuration file so it can connect to your database.
See the data store section of the Configuration Property Reference for all relevant configuration parameters.
Kong Gateway supports both PostgreSQL and Cassandra as its data store.
The following instructions use PostgreSQL as a database to store Kong configuration.
-
Provision a database and a user before starting Kong Gateway:
CREATE USER kong WITH PASSWORD 'super_secret'; CREATE DATABASE kong OWNER kong;
-
Run one of the following Kong Gateway migrations:
-
In Enterprise environments, we strongly recommend seeding a password for the Super Admin user with the
kong migrations
command. This allows you to use RBAC (Role Based Access Control) at a later time, if needed. Create an environment variable with the desired Super Admin password and store the password in a safe place:KONG_PASSWORD={PASSWORD} kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}
Important: Setting your Kong password (
KONG_PASSWORD
) using a value containing four ticks (for example,KONG_PASSWORD="a''a'a'a'a"
) causes a PostgreSQL syntax error on bootstrap. To work around this issue, do not use special characters in your password. - If you aren’t using Enterprise, run the following:
kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}
-
In Enterprise environments, we strongly recommend seeding a password for the Super Admin user with the
Note: Older versions of PostgreSQL use
ident
authentication by default, newer versions (PSQL 10+) usescram-sha-256
. To allow thekong
user to communicate with the database locally, change the authentication method tomd5
by modifying the PostgreSQL configuration file.
Using a yaml declarative config file
If you want to store the configuration properties for all of Kong Gateway’s configured entities
in a yaml declarative configuration file, also referred to as DB-less mode, you must create a kong.yml
file
and update the kong.conf
configuration file to include the file path to the kong.yml
file.
First, the following command will generate a kong.yml
declarative configuration file in your current folder:
kong config init
The generated kong.yml
file contains instructions for how to configure Kong Gateway using the file.
Second, you must configure Kong Gateway using the kong.conf
configuration file so it is aware of
your declarative configuration file.
Set the database
option to off
and the declarative_config
option to the path of your kong.yml
file as in the following example:
database = off
declarative_config = {PATH_TO_KONG.CONF_FILE}
Start Kong Gateway
Important: When you start Kong Gateway, the NGINX master process runs as
root
, and the worker processes run askong
by default. If this is not the desired behavior, you can switch the NGINX master process to run on the built-inkong
user or to a custom non-root user before starting Kong Gateway.For more information, see Running Kong as a Non-Root User.
Start Kong Gateway using the following command:
kong start -c {PATH_TO_KONG.CONF_FILE}
Verify install
If everything went well, you should see a message (Kong started
) informing you that Kong Gateway is running.
You can also check using the Admin API:
curl -i http://localhost:8001
You should receive a 200
status code.
By default, listens on the following ports:
-
:8000
: Port on which listens for incoming HTTP traffic from your clients, and forwards it to your upstream services. -
:8443
: Port on which listens for incoming HTTPS traffic. This port has similar behavior as the:8000
port, except that it expects HTTPS traffic only. This port can be disabled with thekong.conf
configuration file. -
:8001
: Port on which the Admin API used to configure listens. -
:8444
: Port on which the Admin API listens for HTTPS traffic.
Post-install configuration
The following steps are all optional and depend on the choices you want to make for your environment.
Apply Enterprise license
If you have an Enterprise license for Kong Gateway, apply it using one of the methods below, depending on your environment.
Enable Kong Manager
-
Update the
admin_gui_url
property in thekong.conf
configuration file to the DNS, or IP address, of your system. For example:admin_gui_url = http://localhost:8002
This setting needs to resolve to a network path that will reach the operating system (OS) host.
-
Update the Admin API setting in the
kong.conf
file to listen on the needed network interfaces on the OS host. A setting of0.0.0.0:8001
will listen on port8001
on all available network interfaces.Important: The settings below are intended for non-production use only, as they override the default
admin_listen
setting to listen for requests from any source. Do not use these settings in environments directly exposed to the internet.
If you need to expose theadmin_listen
port to the internet in a production environment, secure it with authentication.Example configuration:
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl
You may also list network interfaces separately as in this configuration example:
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl, 127.0.0.1:8001, 127.0.0.1:8444 ssl
-
Restart Kong Gateway for the setting to take effect, using the following command:
kong restart -c {PATH_TO_KONG.CONF_FILE}
-
Access Kong Manager on port
8002
.
Enable Dev Portal
If you’re running Kong Gateway with a database (either in traditional or hybrid mode), you can enable the Dev Portal.
-
Enable the Dev Portal in the
kong.conf
file by setting theportal
property toon
and theportal_gui_host
property to the DNS or IP address of the system. For example:portal = on portal_gui_host = localhost:8003
-
Restart Kong Gateway for the setting to take effect, using the following command:
kong restart -c {PATH_TO_KONG.CONF_FILE}
-
To enable the Dev Portal for a workspace, execute the following command, updating
DNSorIP
to reflect the IP or valid DNS for the system:curl -X PATCH http://localhost:8001/workspaces/default \ --data "config.portal=true"
-
Access the Dev Portal for the default workspace using the following URL, substituting your own DNS or IP:
http://localhost:8003/default
Troubleshooting and support
For troubleshooting license issues, see:
If you did not receive an HTTP/1.1 200 OK
message or need assistance completing
your setup, reach out to your Kong Support contact or go to the
Support Portal.
Next steps
Check out Kong Gateway’s series of Getting Started guides to get the most out of Kong Gateway.