Licenses

Uses: Kong Gateway Admin API

What is a license?

A License entity allows you to configure a license in your self-managed Kong Gateway cluster, in both traditional and hybrid mode deployments.

You receive a license file when you sign up for a Kong Gateway Enterprise subscription. If you purchased a subscription but haven’t received a license file, contact your sales representative.

In hybrid and traditional modes, Kong Gateway checks for a license in the following order and loads the license at startup:

The contents of the environmental variable KONG_LICENSE_DATA.
The default location /etc/kong/license.json.
The contents of the file defined by the KONG_LICENSE_PATH environment variable.
A license directly deployed with the /licenses Admin API endpoint.

Each node independently checks for the license file when the Kong Gateway process starts. Network connectivity isn’t required for license validation.

In DB-less deployments (for example, when applying declarative configuration via POST /config), a license in the declarative configuration overrides KONG_LICENSE_DATA, because the environment variable is only read at startup. When a KongLicense resource exists, Kong Ingress Controller sends it in the configuration payload and it takes precedence.

Deployment methods

Licenses are deployed according to your deployment topology:

Method	Traditional database-backed	Hybrid mode	DB-less mode
Admin API	Supported	Supported	Not supported
License File	Supported	Supported	Supported
Environment variable	Supported	Supported	Supported

Deploy a license

You can deploy a license using the Admin API.

The control plane sends licenses configured through the /licenses endpoint to all data planes in the cluster. The data planes use the most recent updated_at license. This is the only method that automatically applies the license to data planes.

The following license payload is only an example. Substitute your own license before running the command.

curl -i -X POST http://localhost:8001/licenses/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "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\"}}"
    }
    '

Copied!

You can deploy a license with a license.json file.

The license data must contain straight quotes to be considered valid JSON (' and ", not ’ or “). Kong Gateway searches for the license by default in /etc/kong/license.json.

In a self-managed Kong Gateway deployment, 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.

Save your license to a file named license.json.
Copy the license file to the /etc/kong.
Restart the Kong Gateway nodes to apply the license by running kong restart from within the container.

You can deploy a license as an environment variable.

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. Add the license to each data plane node. Each node must start with the license. The license can’t be added after starting the node.

Unlike other KONG_* environment variables, the KONG_LICENSE_DATA and KONG_LICENSE_PATH can’t be defined inline as part of any kong CLI commands. These license environment variables must be exported to the shell where the Nginx process runs before using the kong CLI tool.

Export your license to an environment variable:
```
  export KONG_LICENSE_DATA='$YOUR_LICENSE_DATA'
```
Copied!
Reference the variable as part of your Kong Gateway deployment.

By default, Kong Gateway looks for a license file at /etc/kong/license.json. If your default Kong Gateway directory is different, or the location of license.json is different than the default, you can use the KONG_LICENSE_PATH variable instead to force Kong Gateway to check a different directory.

Expiration

Licenses expire at midnight on the expiration date. The expiration time is the same as that of the time zone of your control plane.

Kong Manager warns you of your license expiring 15 days before it expires. Kong Gateway logs also show a license expiration alert 90 and 30 days before the license expires as well as on and after the expiration date.

After a license expires, Kong Gateway behaves as follows:

All entity configurations become read-only.
You can continue to access API Gateway admin interfaces through Kong Manager and Konnect.
All proxy traffic continues to be processed with existing, unchanged configuration.
You can still restart and scale nodes in traditional mode.
New nodes can’t come up and restarts will break in DB-less mode and KIC.

You can update your license with a PUT request to the /licenses/{license-id} Admin API endpoint.

License reports

A license report contains information about your Kong Gateway deployment, including license usage and deployment information. Reports are generated manually on demand with the Admin API, you can’t generate them automatically or on a schedule. The report doesn’t send data to Kong servers.

You can share the report with Kong Support to perform a health-check analysis of product usage and overall deployment performance to ensure your organization is optimized with the best license and deployment plan for your needs.

To generate a license report, send a GET request to the /license/report endpoint:

curl http://localhost:8001/license/report

Copied!

The response contains the following fields:

Field	Description
`checksum`	SHA-256 digest of the full report contents.
`timestamp`	Unix timestamp of when the report was generated.
`kong_version`	The version of Kong Gateway running on this node.
`db_version`	The database engine and version in use.
`license`	Details about the active license: `license_key` and `license_expiration_date`.
`deployment_info`	The deployment topology type (`traditional`, `hybrid`, or `dbless`).
`system_info`	Information about the node: `hostname`, `cores` (number of online processors), and `uname` (OS and architecture).
`services_count`	Total number of Services configured in this deployment.
`routes_count`	Total number of Routes configured in this deployment.
`consumers_count`	Total number of Consumers configured in this deployment.
`workspaces_count`	Total number of Workspaces in this deployment.
`rbac_users`	Total number of configured RBAC users.
`plugins_count`	Plugin usage broken down into `tiers` (`free`, `enterprise`, `custom`)
`counters`	Request counts as `total_requests` and a `buckets` array.

Common errors

The following table lists some common license errors:

Error	Description
`license path environment variable not set`	The `KONG_LICENSE_DATA` or `KONG_LICENSE_PATH` environment variables weren’t defined. No license file could be opened at the default license location (`/etc/kong/license.json`).
`error opening license file`	The license file defined either in the default location, or using the `KONG_LICENSE_PATH` env variable, couldn’t be opened. Check that the user executing the Nginx process (for example, the user executing the Kong CLI utility) has permissions to read this file.
`error reading license file`	The license file defined either in the default location, or using the `KONG_LICENSE_PATH` env variable, was opened, but an error occurred while reading it. Confirm that the file isn’t corrupt, and that there are no kernel error messages reported (for example, out of memory conditions).
`could not decode license json`	The license file data couldn’t be decoded as valid JSON. Confirm that the file isn’t corrupt and hasn’t been altered since you received it from Kong. Try re-downloading and installing your license file from Kong. If you still receive this error after reinstallation, contact Kong support.
`invalid license format`	The license file data is missing one or more key/value pairs. Confirm that the file isn’t corrupt and hasn’t been altered since you received it from Kong. Try re-downloading and installing your license file from Kong. If you still receive this error after reinstallation, contact Kong support.
`validation failed`	Verifying the payload of the license with the license’s signature failed. Confirm that the file isn’t corrupt and hasn’t been altered since you received it from Kong. Try re-downloading and installing your license file from Kong. If you still receive this error after reinstallation, contact Kong support.
`license expired`	This error displays when the system time is past the license’s `license_expiration_date`. Contact Kong support for a new license.
`invalid license expiration date`	The data in the `license_expiration_date` field is incorrectly formatted. Try re-downloading and installing your license file from Kong. If you still receive this error after reinstallation, contact Kong support.

FAQs

How do I make sure the license is deployed to data plane nodes correctly in hybrid mode?

In hybrid mode, the license file must be deployed to each control plane and data plane node. As long as you deploy the License with the /licenses Admin API endpoint, the control plane automatically applies the license to its data plane nodes.

What happens to the license file in traditional mode when there are no separate control planes?

The license file must be manually deployed to each node running Kong Gateway.

How do I package a license report to send to Kong Support?

Run curl http://localhost:8001/license/report -o response.json && tar -cf report-$(date +"%Y_%m_%d_%I_%M_%p").tar response.json. This saves the report as response.json and creates a timestamped .tar archive ready to share with Kong Support.