Skip to content
|
Kong Gateway
3.2.x
github-edit-pageEdit this page
report-issueReport an issue
You are browsing documentation for an older version. See the latest documentation here.

Set up data store

Kong Gateway comes with a default configuration property file that can be found at /etc/kong/kong.conf.default. 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: using a database (PostgreSQL), or using a YAML declarative configuration file, also known as DB-less mode.

Before starting Kong Gateway, you must update the kong.conf.default configuration property file with a reference to your data store.

Note: The following data store setup is only necessary if you installed Kong Gateway without a data store. If you followed one of our Docker, Kubernetes, or quickstart guides, you should already have a data store configured.

Set up 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.

Then, choose one of the following options to set up your data store:

Using a database

Configure Kong Gateway using the kong.conf.default file so it can connect to your database. See the data store section of the Configuration Property Reference for all relevant configuration parameters.

We don’t recommend using Cassandra with Kong Gateway, because support for Cassandra is deprecated and planned to be removed.

Provision a PostgreSQL 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 password and store the password in a safe place:

KONG_PASSWORD=<PASSWORD> kong migrations bootstrap -c <KONG_DECLARATIVE_CONFIG_PATH>

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 <KONG_DECLARATIVE_CONFIG_PATH>

Older versions of PostgreSQL use ident authentication by default, newer versions (PSQL 10+) use scram-sha-256. To allow the kong user to communicate with the database locally, change the authentication method to md5 by modifying the PostgreSQL configuration file.

Using a YAML declarative config file

Instead of using a database, you can also 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).

Create a kong.yml file and update the kong.conf configuration file to include the file path to the kong.yml file.

  1. Generate a kong.yml declarative configuration file in your current folder:

     kong config init

    The generated kong.yml file contains instructions for configuring Kong Gateway using the file.

  2. In kong.conf, set the database option to off, and set the declarative_config directive to the path to your kong.yml:

     database = off
 declarative_config = <KONG_DECLARATIVE_CONFIG_PATH>

Start Kong Gateway

Important: When you start Kong Gateway, 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 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.

Depending on your desired environment, see the following guides:

You can also check out Kong Gateway’s series of Getting Started guides to learn how get the most out of Kong Gateway.