Installing Kong EE Docker Image

Introduction

A guide to installing Kong Enterprise Edition (and its license file) as a Docker Container. Trial users should skip directly to step 3.

Login to bintray.com (your credentials will have been emailed to you by your Sales or Support contact)
In the upper right corner, choose edit profile so you can retrieve your API key which you will use in step 3 (or click this link: https://bintray.com/profile/edit)

For users with existing contracts add the Kong Docker repository and pull the image:

 docker login -u <your_username_from_bintray> -p <your_apikey_from_bintray> kong-docker-kong-enterprise-edition-docker.bintray.io
 docker pull kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition

For trial users, run the following, replacing <your trial image URL> with the URL you received in your welcome email:

 curl -Lsv "<your trial image URL>" -o /tmp/kong-docker-ee.tar.gz
 docker load -i /tmp/kong-docker-ee.tar.gz

Now you have the docker image for EE locally this way Run docker images to find the image

Tag it (for easier use in the commands below) as follows (replace w/ your image’s IMAGE ID):

 docker tag 92aa781a99db kong-ee

Generally, we’ll be following the instructions here with some slight (but important) differences

For convenience, the commands will look something like this (PostgreSQL 9.5 is required):

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

To make the license data easier to handle, export it as a shell variable. Please note that your KONG_LICENSE_DATA will differ! Users with Bintray accounts should visit https://bintray.com/kong/<YOUR_REPO_NAME>/license#files to retrieve their license. Trial users should download their license from their welcome email. Once you have your license, you can set it in an environment variable:

 export KONG_LICENSE_DATA='{"license":{"signature":"LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tClZlcnNpb246IEdudVBHIHYyCgpvd0did012TXdDSFdzMTVuUWw3dHhLK01wOTJTR0tLWVc3UU16WTBTVTVNc2toSVREWk1OTFEzVExJek1MY3dTCjA0ek1UVk1OREEwc2pRM04wOHpNalZKVHpOTE1EWk9TVTFLTXpRMVRVNHpTRXMzTjA0d056VXdUTytKWUdNUTQKR05oWW1VQ21NWEJ4Q3NDc3lMQmorTVBmOFhyWmZkNkNqVnJidmkyLzZ6THhzcitBclZtcFZWdnN1K1NiKzFhbgozcjNCeUxCZzdZOVdFL2FYQXJ0NG5lcmVpa2tZS1ozMlNlbGQvMm5iYkRzcmdlWFQzek1BQUE9PQo9b1VnSgotLS0tLUVORCBQR1AgTUVTU0FHRS0tLS0tCg=","payload":{"customer":"Test Company Inc","license_creation_date":"2017-11-08","product_subscription":"Kong Enterprise Edition","admin_seats":"5","support_plan":"None","license_expiration_date":"2017-11-10","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU"},"version":1}}'

Run Kong migrations:

 docker run --rm --link kong-ee-database:kong-ee-database \
   -e "KONG_DATABASE=postgres" -e "KONG_PG_HOST=kong-ee-database" \
   -e "KONG_CASSANDRA_CONTACT_POINTS=kong-ee-database" \
   -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
   kong-ee kong migrations up

Start Kong:

 docker run -d --name kong-ee --link kong-ee-database:kong-ee-database \
   -e "KONG_DATABASE=postgres" \
   -e "KONG_PG_HOST=kong-ee-database" \
   -e "KONG_CASSANDRA_CONTACT_POINTS=kong-ee-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_VITALS=on" \
   -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
   -e "KONG_PORTAL=on" \
   -e "KONG_PORTAL_GUI_URI=localhost:8003" \
   -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
   -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

Congratulations! You now have Kong Enterprise installed and running. You can use Kong Enterprise’s web interfaces by visiting http://localhost:8002 (Admin GUI) and http://localhost:8003 (Developer Portal).

Enable RBAC

Role-based Access Control (RBAC) allows you to create multiple Kong administrators and control which resources they have access to. To enable it:

Create an initial RBAC administrator:

 curl -X POST http://localhost:8001/rbac/users/ -d name=admin -d user_token=12345
 curl -X POST http://localhost:8001/rbac/users/admin/roles -d roles=super-admin

Start a bash session on the container:

 docker exec -it kong-ee /bin/sh

Reload Kong with RBAC enabled:

 KONG_ENFORCE_RBAC=on kong reload

Confirm that your user token is working by passing the Kong-Admin-Token header in requests:

 curl -X GET http://localhost:8001/status -H "Kong-Admin-Token: 12345"

If you are able to access Kong without issues, you can add KONG_ENFORCE_RBAC=on to your initial container environment variables.

FAQs

The Admin API only listens on the local interface by default. This was done as a security enhancement. Note that here, we are overriding that in the above example with KONG_ADMIN_LISTEN=0.0.0.0:8001 because Docker container networking benefits from more open settings and enables the Admin GUI & Dev Portal to talk with the Kong Proxy.

Without a license properly referenced, you’ll get errors running migrations. Also, without a license, you’ll do a docker start <name> and not see an error attempting to start the container. But when you check the process, it won’t be running. Doing a docker logs <container_name> will show you:

    nginx: [alert] Error validating Kong license: license path environment variable not set

As awareness, another error that can occur due to the vagaries of the interactions between text editors and copy & paste changing straight quotes (“ or ‘) into curly ones (“ or ” or ’ or ‘) is:

    nginx: [alert] Error validating Kong license: could not decode license json

Your license data must contain only straight quotes to be considered valid JSON.