More Docker. Easy Access. New Streamlined Plans. Learn more.

kong/kong-gateway

Verified Publisher

By Kong Inc.

Updated 16 days ago

Kong Gateway - The world’s most popular API gateway.

Image
56

500M+

What is Kong Gateway?

Kong Gateway is a scalable, open source API Platform (also known as an API Gateway or API Middleware). Kong Gateway was originally built by Kong Inc. (formerly known as Mashape) to secure, manage and extend over 15,000 Microservices for its API Marketplace, which generates billions of requests per month.

Under active development, Kong Gateway is now used in production at hundreds of organizations from startups, to large enterprises and governments including: The New York Times, Expedia, Healthcare.gov, The Guardian, Condè Nast, The University of Auckland, Ferrari, Rakuten, Cisco, SkyScanner, Yahoo! Japan, Giphy and so on.

Kong Gateway's official documentation can be found at docs.konghq.com.

How to use this image without a Database

Kong Gateway 1.1 added the capability to run Kong without a database, using only in-memory storage for entities: we call this DB-less mode. When running Kong Gateway DB-less, the configuration of entities is done in a second configuration file, in YAML or JSON, using declarative configuration.

Important: Kong Gateway's admin API must be secured when running on a public system. The following example is provided for testing Kong Gateway on your local machine. We recommend that you only expose the admin ports on localhost such as in this example https://docs.konghq.com/gateway/latest/install/docker/?install=oss#start-kong-gateway

$ docker run -d --name kong \
    -e "KONG_DATABASE=off" \
    -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 8001:8001 \
    -p 8444:8444 \
    kong/kong-gateway

Generate a skeleton configuration file to get you started

$ docker exec -it kong/kong-gateway kong config init /home/kong/kong.yml
$ docker exec -it kong/kong-gateway cat /home/kong/kong.yml >> kong.yml

Load a declarative configuration into a running Kong node via its Admin API using HTTPie

$ http :8001/config config=@kong.yml

Note: Not all Kong Gateway plugins are compatible with DB-less mode, since some of them by design require a central database coordination and/or dynamic creation of entities, see the doc for details at DB-less and Declarative Configuration

How to use this image with a Database

First, for fully-compatible with all plugins (e.g. acl, oauth2), Kong Gateway requires a running PostgreSQL instance (9.6+) before it starts. You can either use the official PostgreSQL container, or use your own.

1. Link Kong Gateway to a PostgreSQL container

Kong Gateway primarily expects to use PostgreSQL as a datastore.

Postgres

Start a PostgreSQL container by executing:

$ docker run -d --name kong-database \
                -p 5432:5432 \
                -e "POSTGRES_USER=kong" \
                -e "POSTGRES_DB=kong" \
                -e "POSTGRES_PASSWORD=kong" \
                postgres:9.6

2. Prepare your database

Run the database migrations with an ephemeral Kong container:

$ docker run --rm \
    --link kong-database:kong-database \
    -e "KONG_DATABASE=postgres" \
    -e "KONG_PG_HOST=kong-database" \
    -e "KONG_PG_USER=kong" \
    -e "KONG_PG_PASSWORD=kong" \
    kong/kong-gateway kong migrations bootstrap

In the above example PostgreSQL is configured, but you should update the KONG_DATABASE environment variable with either postgres or off (for "DB-less" mode).

Note for Kong Gateway < 0.15: with Kong Gateway versions below 0.15 (up to 0.14), use the up sub-command instead of bootstrap. Also note that with Kong Gateway < 0.15, migrations should never be run concurrently; only one Kong Gateway node should be performing migrations at a time. This limitation is lifted for Kong Gateway 0.15, 1.0, and above.

Start Kong Gateway

Once the database has been started and prepared, we can start a Kong Gateway container and link it to the database container, and configuring the KONG_DATABASE environment variable with postgres:

Important: Kong Gateway's admin API must be secured when running on a public system. The following example is provided for testing Kong Gateway on your local machine. We recommend that you only expose the admin ports on localhost such as in this example https://docs.konghq.com/gateway/3.6.x/install/docker/?install=oss#start-kong-gateway

$ docker run -d --name kong \
    --link kong-database:kong-database \
    -e "KONG_DATABASE=postgres" \
    -e "KONG_PG_HOST=kong-database" \
    -e "KONG_PG_PASSWORD=kong" \
    -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 8001:8001 \
    -p 8444:8444 \
    kong/kong-gateway

If everything went well, and if you created your container with the default ports, Kong Gateway should be listening on your host's 8000 (Proxy), 8443 (Proxy SSL), 8001 (Admin API) and 8444 (Admin API SSL) ports.

You can now read the docs at docs.konghq.com to learn more about Kong Gateway.

3. Use Kong Gateway with a custom configuration (and a custom PostgreSQL cluster)

You can override any property of the Kong configuration file with environment variables. Just prepend any Kong Gateway configuration property with the KONG_ prefix, for example:

Important: Kong Gateway's admin API must be secured when running on a public system. The following example is provided for testing Kong Gateway on your local machine. We recommend that you only expose the admin ports on localhost such as in this example https://docs.konghq.com/gateway/3.6.x/install/docker/?install=oss#start-kong-gateway

$ docker run -d --name kong \
    -e "KONG_DATABASE=postgres"
    -e "KONG_PG_HOST=kong-database" \
    -e "KONG_LOG_LEVEL=info" \
    -e "KONG_CUSTOM_PLUGINS=helloworld" \
    -e "KONG_PG_HOST=1.1.1.1" \
    -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
    -p 8000:8000 \
    -p 8443:8443 \
    -p 8001:8001 \
    -p 8444:8444 \
    kong/kong-gateway

Reload Kong Gateway in a running container

If you change your custom configuration, you can reload Kong Gateway (without downtime) by issuing:

$ docker exec -it kong/kong-gateway kong reload

This will run the kong reload command in your container.

Kubernetes Ingress

Among the many deployment options available, Kong also offers a Kubernetes Ingress Controller ready to use in your K8S environment.

Image Variants

The kong/kong-gateway images come in many flavors, each designed for a specific use case.

kong/kong-gateway:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

"Major dot minor" (e.x. kong/kong-gateway:3.7) and full version (e.x. kong/kong-gateway:3.7.0.0) tags are available for modern Kong Gateway images.

kong/kong-gateway:<version>-<os><os version>

OS and OS versions vary by Kong version. But you can expect to find at least kong/kong-gateway:3.7-debian, kong/kong-gateway:3.7-ubuntu, and kong/kong-gateway:3.7-rhel.

Note: kong/kong-gateway:latest & kong/kong-gateway:latest-<os> are NOT guaranteed to be the latest Generally Available versions and are intended for developer use only.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Docker Pull Command

docker pull kong/kong-gateway