Deploy an Enterprise License

Deploy an enterprise license to a Kong Gateway installation to gain access to Enterprise-specific features.

You can deploy a license file in one of the following ways:

MethodSupported deployment types
/licenses Admin API endpoint• Traditional database-backed deployment
• Hybrid mode deployment
File on the node filesystem
(license.json)		• Traditional database-backed deployment
• DB-less mode
Environment variable containing the full license
(KONG_LICENSE_DATA)		• Traditional database-backed deployment
• DB-less mode
Environment variable containing path to license file
(KONG_LICENSE_PATH)		• Traditional database-backed deployment
• DB-less mode

The recommended method is using the Admin API.

Important:

  • If you deploy a license using the /license endpoint on the control plane, the control plane propagates the license to connected data planes automatically.
  • If you deploy a license using a KONG_LICENSE_DATA or KONG_LICENSE_PATH environment variable, the control plane does not propagate the license to data plane nodes. You must add the license to each data plane node, and each node must start with the license. The license can’t be added after starting the node.

We don’t recommend using this method in hybrid mode deployments.

Prerequisites

  • You have received a license.json file from Kong.
  • Kong Gateway is installed.

Deploy the license

Admin API

Filesystem

Environment variable (JSON)

Environment variable (file path)

You can use the Kong Admin API to distribute the license in any database-backed or hybrid mode deployment. We recommend using this method in most deployments.

In hybrid mode, apply the license to the control plane. The control plane distributes the license to its data plane nodes. This is the only method that applies the license to data planes automatically.

The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

Note: The payload of the following license is only an example. You must use the following format, but provide your own content.

Add new license

Update existing license

To add a new license, POST the contents of the provided license.json license to your Kong Gateway instance:

  1. curl -i -X POST http://localhost:8001/licenses \
  2.   -d payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

Result:

  1. {
  2.   "created_at": 1500508800,
  3.   "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
  4.   "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-20\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b\",\"version\":\"1\"}}",
  5.   "updated_at": 1500508800
  6. }

Update the license with a PATCH request to the existing license’s ID:

  1. Find the license you want to update, and copy the ID from the output:

    1.  curl -i -X GET http://localhost:8001/licenses

  2. Submit a PATCH request to the license ID:

    1.  curl -i -X PATCH http://localhost:8001/licenses/30b4edb7-0847-4f65-af90-efbed8b0161f \
    2.    payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-21","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb","version":"1"}}'

    Response:

    1.  {
    2.    "created_at": 1500595200,
    3.    "id": "30b4edb7-0847-4f65-af90-efbed8b0161f",
    4.    "payload": "{\"license\":{\"payload\":{\"admin_seats\":\"1\",\"customer\":\"Example Company, Inc\",\"dataplanes\":\"1\",\"license_creation_date\":\"2017-07-20\",\"license_expiration_date\":\"2017-07-21\",\"license_key\":\"00141000017ODj3AAG_a1V41000004wT0OEAU\",\"product_subscription\":\"Konnect Enterprise\",\"support_plan\":\"None\"},\"signature\":\"24cc21223633044c15c300be19cacc26ccc5aca0dd9a12df8a7324a1970fe304bc07b8dcd7fb08d7b92e04169313377ae3b550ead653b951bc44cd2eb59f6beb\",\"version\":\"1\"}}",
    5.    "updated_at": 1500595200
    6.  }

Restart the Kong Gateway nodes after adding or updating a license.

For more detail and options, see the Admin API licenses endpoint reference.

You can provide a license file to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

  1. Securely copy the license.json file to your home directory on the filesystem where you have installed Kong Gateway.

    1.  $ scp license.json <system_username>@<server>:~

  2. Then, copy the license file again, this time to the /etc/kong directory:

    1.  $ scp license.json /etc/kong/license.json

    Kong Gateway will look for a valid license in this location.

You can use the KONG_LICENSE_DATA environment variable to apply a license to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “).

  1. Export the license key to a variable by running the following command, substituting your own license key.

    Note: The following license is only an example. You must use the following format, but provide your own content.

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

  2. Include the license as part of the docker run command when starting a Kong Gateway container:

    Note: This is only a snippet. For a full working example, see the instructions to Install Kong Gateway on Docker.

    1.  docker run -d --name kong-gateway \
    2.   --network=kong-net \
    3.   ...
    4.   -e KONG_LICENSE_DATA \
    5.   kong/kong-gateway:-alpine

You can use the KONG_LICENSE_PATH environment variable to apply a license to Kong Gateway in any database-backed or DB-less deployment. This method is not recommended for use in hybrid mode, as you have to maintain the license on each node manually.

Include the license as part of the docker run command when starting a Kong Gateway container. Mount the path to the file on your local filesystem to a directory in the Docker container, making the file visible from the container:

Note: This is only a snippet. For a full working example, see the instructions to Install Kong Gateway on Docker.

  1. docker run -d --name kong-gateway \
  2.  --network=kong-net \
  3.  ...
  4.  -v "$(pwd)/kong-license/:/kong-license/" \
  5.  -e "KONG_LICENSE_PATH=/kong-license/license.json" \
  6.  kong/kong-gateway:-alpine

Troubleshooting and support

For troubleshooting license issues, see:

For more details and examples, see:

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.