Skip to content
Learn how to secure, route, and transform API requests  —Register Now! →
|
search
Kong Gateway
2.7.x (latest)

Install Kong Gateway on Docker

See the list of Docker tags and pull the Docker image:

(latest Kong Gateway version: 2.7.0.0)

Kong Gateway supports both PostgreSQL 9.5+ and Cassandra 3.11.* as its datastore. This guide provides steps to configure PostgreSQL.

If you prefer to use the open-source Kong Gateway image with Docker Compose, Kong also provides a Docker Compose template with built-in orchestration and scalability.

Some older Kong Gateway images are not publicly accessible. If you need a specific patch version and can’t find it on Kong’s public Docker Hub page, contact Kong Support.

The Kong Gateway software is governed by the Kong Software License Agreement. Kong Gateway (OSS) is licensed under an Apache 2.0 license.

Prerequisites

  • A Docker-enabled system with proper Docker access
  • (Enterprise only) A license.json file from Kong

Install Kong Gateway with a database

Set up a Kong Gateway container with a PostgreSQL database to store Kong configuration.

Deprecation warning: Cassandra as a backend database for Kong Gateway is deprecated. This means the feature will eventually be removed.
Our target for Cassandra removal is the Kong Gateway 4.0 release. Starting with the Kong Gateway 3.0 release, some new features might not be supported with Cassandra.

Pull and tag the Kong Gateway image

  1. Pull the Docker image:

    docker pull kong/kong-gateway:2.7.0.0-alpine

    docker pull kong:2.7.0-alpine

    You should now have your Kong Gateway image locally.

  2. Tag the image:

    docker tag kong/kong-gateway:2.7.0.0-alpine 
    {TAG_NAME}
    docker tag kong:2.7.0-alpine 
    {TAG_NAME}

Prepare the database

  1. Create a custom Docker network to allow the containers to discover and communicate with each other:

    docker network create 
    {NETWORK_NAME}

  2. Start a PostgreSQL container:

    docker run -d --name 
    {PG_CONTAINER_NAME}
     \
  --network=
    {NETWORK_NAME}
     \
  -p 5432:5432 \
  -e "POSTGRES_USER=
    {DATABASE_USER}
    " \
  -e "POSTGRES_DB=
    {DATABASE_NAME}
    " \
  -e "POSTGRES_PASSWORD=
    {DATABASE_PASSWORD}
    " \
  postgres:9.6

  3. Prepare the Kong database:

    docker run --rm --network=
    {NETWORK_NAME}
     \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=
    {PG_CONTAINER_NAME}
    " \
  -e "KONG_PG_PASSWORD=
    {CONTAINER_PASSWORD}
    " \
  -e "KONG_PASSWORD=
    {PASSWORD}
    " \
  
    {TAG_NAME}
     
    {DATABASE_NAME}
     migrations bootstrap

Start Kong Gateway

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 the admin_listen port to the internet in a production environment, secure it with authentication.

  1. Run the following command to start a container with Kong Gateway:

    docker run -d --name 
    {GATEWAY_CONTAINER_NAME}
     \
  --network=
    {NETWORK_NAME}
     \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=
    {PG_HOST_NAME}
    " \
  -e "KONG_PG_USER=
    {PG_USER_NAME}
    " \
  -e "KONG_PG_PASSWORD=
    {DATABASE_PASSWORD}
    " \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
  -e "KONG_ADMIN_GUI_URL=http://
    {HOSTNAME}
    :8002" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 8001:8001 \
  -p 8444:8444 \
  -p 8002:8002 \
  -p 8445:8445 \
  -p 8003:8003 \
  -p 8004:8004 \
  kong-ee
    docker run -d --name 
    {GATEWAY_CONTAINER_NAME}
     \
  --network=
    {NETWORK_NAME}
     \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=
    {PG_HOST_NAME}
    " \
  -e "KONG_PG_USER=
    {PG_USER_NAME}
    " \
  -e "KONG_PG_PASSWORD=kong" \
  -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 127.0.0.1:8001:8001 \
  -p 127.0.0.1:8444:8444 \
  kong:latest

    Note: The HOSTNAME for KONG_PORTAL_GUI_HOST should be preceded by a protocol, for example, http://.

  2. Verify your installation:

    Access the /services endpoint using the Admin API:

    curl -i -X GET --url http://
    {HOSTNAME}
    :8001/services

    You should receive a 200 status code.

  3. (Not available in OSS) Verify that Kong Manager is running by accessing it using the URL specified in KONG_ADMIN_GUI_URL:

    http://
    {HOSTNAME}
    :8002

Install Gateway in DB-less mode

Important: Running Kong Gateway on Docker in DB-less mode is supported for both Enterprise and OSS images. However, there is currently no documentation for setting up an Enterprise image in DB-less mode, so adjust the following steps as needed for an Enterprise deploy.

The steps involved in starting Kong in DB-less mode are the following:

  1. Create a Docker network:

    This is the same as in the Pg/Cassandra guide. We’re also using kong-net as the network name and it can also be changed to something else.

     docker network create kong-net

    This step is not strictly needed for running Kong in DB-less mode, but it is a good precaution in case you want to add other things in the future (like a rate-limiting plugin backed up by a Redis cluster).

  2. Create a Docker volume:

    For the purposes of this guide, a Docker Volume is a folder inside the host machine which can be mapped into a folder in the container. Volumes have a name. In this case we’re going to name ours kong-vol

     docker volume create kong-vol

    You should be able to inspect the volume now:

     docker volume inspect kong-vol

    The result should be similar to this:

     [
     {
         "CreatedAt": "2019-05-28T12:40:09Z",
         "Driver": "local",
         "Labels": {},
         "Mountpoint": "/var/lib/docker/volumes/kong-vol/_data",
         "Name": "kong-vol",
         "Options": {},
         "Scope": "local"
     }
 ]

    Notice the MountPoint entry. We will need that path in the next step.

  3. Prepare your declarative configuration file:

    The syntax and properties are described on the Declarative Configuration Format guide.

    Add whatever core entities (Services, Routes, Plugins, Consumers, etc) you need there.

    On this guide we’ll assume you named it kong.yml.

    Save it inside the MountPoint path mentioned in the previous step. In the case of this guide, that would be /var/lib/docker/volumes/kong-vol/_data/kong.yml

  4. Run the following command to start a container with Kong Gateway.

    Although it’s possible to start the Kong container with KONG_DATABASE=off, it is usually desirable to also include the declarative configuration file as a parameter via the KONG_DECLARATIVE_CONFIG variable name. To do this, we need to make the file “visible” from within the container. Use the -v flag, which maps the Docker volume to the /usr/local/kong/declarative folder in the container.

    docker run -d --name 
    {GATEWAY_CONTAINER_NAME}
     \
  --network=
    {NETWORK_NAME}
     \
  -v "kong-vol:/usr/local/kong/declarative" \
  -e "KONG_DATABASE=off" \
  -e "KONG_DECLARATIVE_CONFIG=/usr/local/kong/declarative/kong.yml" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
  -e "KONG_ADMIN_GUI_URL=http://
    {HOSTNAME}
    :8002" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 8001:8001 \
  -p 8444:8444 \
  -p 8002:8002 \
  -p 8445:8445 \
  -p 8003:8003 \
  -p 8004:8004 \
  kong-ee
    docker run -d --name 
    {GATEWAY_CONTAINER_NAME}
     \
  --network=
    {NETWORK_NAME}
     \
  -v "kong-vol:/usr/local/kong/declarative" \
  -e "KONG_DATABASE=off" \
  -e "KONG_DECLARATIVE_CONFIG=/usr/local/kong/declarative/kong.yml" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 127.0.0.1:8001:8001 \
  -p 127.0.0.1:8444:8444 \
  kong:latest

  5. Verify that Kong Gateway is running:

    curl -i http://
    {HOSTNAME}
    :8001

    For example, get a list of services:

    curl -i http://
    {HOSTNAME}
    :8001/services

Troubleshooting

If you did not receive a 200 OK status code or need assistance completing setup, reach out to your support contact or head over to the Support Portal.

Next Steps

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