Skip to content
|
You are browsing the Kong Gateway documentation archive. This documentation is no longer actively maintained.
See the latest Kong Gateway documentation.
Kong Gateway Enterprise [ARCHIVE]
2.3.x

PermalinkInstall Kong Gateway on CentOS

PermalinkIntroduction

This guide walks through downloading, installing, and starting Kong Gateway on CentOS.

The configuration shown in this guide is intended as an example. Depending on your environment, you may need to make modifications and take measures to properly conclude the installation and configuration.

Kong Gateway supports both PostgreSQL 9.5+ and Cassandra 3.11.* as its datastore. This guide provides steps to configure PostgreSQL. For assistance in setting up Cassandra, please contact your Sales or Support representative.

This software is governed by the Kong Software License Agreement.

PermalinkDeployment options

The following instructions assume that you are deploying Kong Gateway in classic embedded mode.

If you want to run Kong Gateway in Hybrid mode, the instructions in this topic will walk you though setting up a Control Plane instance. Afterward, you will need to bring up additional gateway instances for the Data Planes, and perform further configuration steps. See Hybrid Mode Setup for details.

PermalinkPrerequisites

To complete this installation you will need a supported CentOS system with root-equivalent access.

PermalinkStep 1. Prepare to install Kong Gateway

  1. Choose your CentOS version:

  2. Click a Kong Gateway version from the list to download it.

    Versions are listed in chronological order.

    For example: kong-enterprise-edition-2.3.3.2.el8.noarch.rpm

  3. Copy the RPM file to your home directory on the CentOS system.

    For example:

     $ scp kong-enterprise-edition-2.3.3.2.el8.noarch.rpm <centos user>@<server>:~

  1. Download and save the Kong Gateway RPM repo file as config.repo:

  2. Securely copy the repo file to your home directory on the CentOS system:

     $ scp config.repo <centos user>@<server>:~

PermalinkStep 2. Install Kong Gateway

Execute a command similar to the following, using the appropriate RPM filename for the package you downloaded:

$ sudo yum install /path/to/package.rpm

  1. Move the repo file from your home directory to the /etc/yum.repos.d/ directory.

     $ sudo mv config.repo /etc/yum.repos.d/

  2. Run the installation using the Yum repository:

     $ sudo yum update -y
 $ sudo yum install kong-enterprise-edition -y

PermalinkStep 3. Set up PostgreSQL

  1. Install PostgreSQL.

    Follow the instructions available at https://www.postgresql.org/download/linux/redhat/ to install a supported version of PostgreSQL. Kong supports version 9.5 and higher. As an example, you can run a command set similar to:

     $ sudo yum install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
 $ sudo yum install postgresql96
 $ sudo yum install postgresql96-server

  2. Initialize the PostgreSQL database and enable automatic start.

     $ sudo /usr/pgsql-9.6/bin/postgresql96-setup initdb
 $ sudo systemctl enable postgresql-9.6
 $ sudo systemctl start postgresql-9.6

  3. Switch to PostgreSQL user and launch PostgreSQL.

     $ sudo -i -u postgres
 $ psql

  4. Create a Kong database with a username and password.

    ⚠️Note: Make sure the username and password for the Kong Database are kept safe. This example uses a simple username and password for illustration purposes only. Note the database name, username and password for later.

     $ psql> CREATE USER kong; CREATE DATABASE kong OWNER kong; ALTER USER kong WITH password 'kong';

  5. Exit from PostgreSQL and return to your terminal account.

     $ psql> \q
 $ exit

  6. Edit the the PostgreSQL configuration file /var/lib/pgsql/9.6/data/pg_hba.conf using your preferred editor.

    Under IPv4 local connections replace ident with md5:

    Protocol Type Database User Address Method
    IPv4 local host all all 127.0.0.1/32 md5
    IPv6 local host all all 1/128 ident

    PostgreSQL uses ident authentication by default. To allow the kong user to communicate with the database locally, change the authentication method to md5 by modifying the PostgreSQL configuration file.

  7. Restart PostgreSQL.

     $ sudo systemctl restart postgresql-9.6

PermalinkStep 4. Modify Kong Gateway’s configuration file to work with PostgreSQL

  1. Make a copy of Kong Gateway’s default configuration file.

     $ sudo cp /etc/kong/kong.conf.default /etc/kong/kong.conf

  2. Uncomment and update the PostgreSQL database properties in /etc/kong/kong.conf using your preferred text editor. Replace pg_user, pg_password and pg_database with the values:

     pg_user = kong
 pg_password = kong
 pg_database = kong

PermalinkStep 5. Seed the Super Admin password and bootstrap Kong Gateway

Note: When you start Kong, the Nginx master process runs as root, and the worker processes run as kong by default. If this is not the desired behavior, you can switch the Nginx master process to run on the built-in kong user or to a custom non-root user before starting Kong. For more information, see Running Kong as a Non-Root User.

Setting a password for the Super Admin before initial start-up is strongly recommended. This will permit the use of RBAC (Role Based Access Control) at a later time, if needed.

  1. Create an environment variable with the desired Super Admin password and store the password in a safe place. Run migrations to prepare the Kong database:

     $ sudo KONG_PASSWORD=<password-only-you-know> /usr/local/bin/kong migrations bootstrap -c /etc/kong/kong.conf

  2. Start Kong Gateway:

     $ sudo /usr/local/bin/kong start -c /etc/kong/kong.conf

  3. Verify Kong Gateway is working:

     $ curl -i -X GET --url http://localhost:8001/services

  4. You should receive a HTTP/1.1 200 OK message.

PermalinkStep 6. Finalize your configuration and verify installation

PermalinkEnable and configure Kong Manager

  1. To access the gateway’s Graphical User Interface, Kong Manager, update the admin_gui_url property in /etc/kong/kong.conf file to the DNS, or IP address, of the CentOS system. For example:

     admin_gui_url = http://<DNSorIP>:8002

    This setting needs to resolve to a network path that will reach the CentOS host.

  2. It is necessary to update the administration API setting to listen on the needed network interfaces on the CentOS host. A setting of 0.0.0.0:8001 will listen on port 8001 on all available network interfaces.

     admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl

  3. You may also list network interfaces separately as in this 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

  4. Restart Kong for the setting to take effect:

     $ sudo /usr/local/bin/kong restart

  5. You may now access Kong Manager on port 8002.

Permalink(Optional) Enable the Dev Portal

Enterprise This feature is only available with a Kong Konnect Enterprise subscription.

  1. Deploy a license.

  2. Enable the Dev Portal by setting the portal property to on and the portal_gui_host property to the DNS or IP address of the CentOS system. For example:

     portal = on
 portal_gui_host = <DNSorIP>:8003

  3. Restart Kong Gateway for the setting to take effect:

     $ sudo /usr/local/bin/kong restart

  4. Enable the Dev Portal for a workspace. Execute the following command, updating DNSorIP to reflect the IP or valid DNS for the CentOS system:

     $ curl -X PATCH http://<DNSorIP>:8001/workspaces/default \
   --data "config.portal=true"

  5. Access the Dev Portal for the default workspace using the following URL, substituting your own DNS or IP:

     http://<DNSorIP>:8003/default

PermalinkTroubleshooting

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.

PermalinkNext Steps

Check out Kong Gateway’s series of Getting Started guides to get the most out of Kong Gateway.

If you have an Enterprise subscription, add the license using the /licenses Admin API endpoint.