Skip to content

Kong Component of API Gateway

Edge Xpert uses Kong as a component of the API gateway, as described below:

Service Description
kong-db The database used by Kong.

Started when the --api-gateway option is used with the edgexpert up command
kong The main Kong service.

Started when the --api-gateway option is used with the edgexpert up command
proxy The proxy service is a one-off service that set up service routes for Kong and then terminates.

The proxy service contains the secrets-config utility to assist in common configuration tasks. The commands and options are described in the EdgeX Foundry documentation.

Started when the --api-gateway option is used with the edgexpert up command

Start the Kong Service

To start the Kong service, use the following command: 

edgexpert up --api-gateway

Using a Bring-Your-Own External TLS Certificate for API Gateway

The API gateway will generate a default self-signed TLS certificate that is used for external communication. Since this certificate is not trusted by client software, it is commonplace to replace this auto-generated certificate with one generated from a known certificate authority, such as an enterprise PKI, or a commercial certificate authority.

The process for obtaining a certificate is out-of-scope for this document. For purposes of the example, the X.509 PEM-encoded certificate is assumed to be called cert.pem and the unencrypted PEM-encoded private key is called key.pem. Do not use an encrypted private key as the API gateway will hang on startup in order to prompt for a password.

Also, for purposes of the example, the external DNS name of the API gateway is assumed to be edge001.example.com. The API gateway requires a client to support Server Name Identification (SNI) and that the client connects to the API gateway using a DNS host name. The API gateway uses the host name supplied by the client to determine which certificate to present to the client. The API gateway will continue to serve the default (untrusted) certificate if clients connect via IP address or do not provide SNI at all.

Run the following command to install a custom certificate using the assumptions above: 

KONGJWT=`sudo cat /tmp/edgex/secrets/security-proxy-setup/kong-admin-jwt`
edgexpert run -v `pwd`:/host:ro --entrypoint /edgex/secrets-config proxy proxy tls --incert /host/cert.pem --inkey /host/key.pem --snis edge001.example.com --admin_api_jwt "$KONGJWT"

The utility will always add the internal host names, "localhost" and "kong" to the specified SNI list.

The following command can verify the certificate installation was successful. 

echo "GET /" | openssl s_client -showcerts -servername edge001.example.com -connect 127.0.0.1:8443

Using API Gateway to Proxy Existing EdgeX Microservices

Once the resource mapping and access token to API gateway are in place, a client can use the access token to use the protected EdgeX REST API resources behind the API gateway. Again, without the API Gateway in place, here is the sample request to hit the ping endpoint of the Core Data microservice using curl: 

curl http://<host-system-ip>:59880/api/v2/ping

With the security service and JWT authentication is enabled, the command changes to: 

curl -k -H 'Authorization: Bearer <JWT>' https://<host-system-ip>:8443/core-data/api/v2/ping

For information on creating JWTs to access the gateway, refer to Creating Access Token for API Gateway Authentication.

The /core-data/ path in the URL is used to identify which EdgeX micro service the request is routed to. As each EdgeX micro service has a dedicated service port open that accepts incoming requests, there is a mapping table kept by the API gateway that maps paths to micro service ports.

Microservice Path
Core Data core-data
Core Metadta core-metadata
Core Command core-command
Support Notifications support-notifications
Support Scheduler support-scheduler
System Management Agent sys-mgmt-agent
Device Virtual device-virtual
Kuiper rules-engine
Consul consul

API Gateway management interfaces

The default ports on which the Kong Admin API listens are not exposed. To use Kong Admin API, edit the environment variable KONG_ADMIN_LISTEN of the /etc/edgexpert/docker-compose-security.yaml file to allow Kong Admin API listen for requests from the host. 

KONG_ADMIN_LISTEN: "0.0.0.0:8001, 0.0.0.0:8444 ssl"

Note

This Kong Admin API is designed for internal use and provides full control over Kong, it is not recommended to add port mapping for Kong to avoid undue public exposure of this API.

Use the following command to find the IP address of the container running Kong in order to call Kong Admin API: 

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' kong
192.168.96.7

Here is an example of using Admin API to list all services: 

# HTTP
curl -H 'Authorization: Bearer <JWT>' http://<kong-ip>:8001/services

# HTTPS
curl -k -H 'Authorization: Bearer <JWT>' https://<kong-ip>:8444/services

For information on the available Kong Admin APIs, refer to Kong Admin API.

To give permissions to user accounts, configure the ACL plug-in as described in the Kong documentation.

Back to top