Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Upstream TLS

Enable TLS on upstream traffic by providing Kong with a list of trusted certificates.

This plugin is deprecated in Kong Gateway version 1.3, and removed in version 1.5.


Starting with Kong 1.3.0.0:

To configure Upstream TLS, use the NGINX directives proxy_ssl_trusted_certificate, proxy_ssl_verify, and proxy_ssl_verify_depth instead of the Upstream TLS plugin. Instructions on how to inject NGINX directives to Kong can be found here. This plugin is only functional for Kong Gateway versions 0.35 and 0.36.

Configuration Reference

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=upstream-tls"  \
    --data "config.trusted_certificates="

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-upstream-tls>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  trusted_certificates: 
plugin: upstream-tls

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: upstream-tls
  config: 
    trusted_certificates:

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the Upstream TLS plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, set the plugin scope to Global.

  6. Enter the following parameters, updating the default/sample values as needed:

    • Config.Trusted Certificates: ``
  7. Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case upstream-tls.
enabled
required

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.verify_mode
optional

Default value: none

Sets the certification verification mode flags. peer enables client peer validation. none disables client peer validation.
config.verify_depth
optional

Default value: 4

Set the maximum validation chain depth
config.trusted_certificates
required

PEM-encoded public certificate authorities of the upstream

In Enterprise versions 0.35 and 0.36, Upstream TLS can be added on top of an existing Service by executing the following request on your Kong server:

$ curl -X POST http://kong:8001/services/1e6507e9-5c72-4dc2-9a3a-5131c4c5bea6/plugins \
    --form "name=upstream-tls" \
    --form "config.verify_mode=peer" \
    --form "config.trusted_certificates=@path_to_cert.pem" \
    --form "config.verify_depth=2"

service: the id or name of the Service that this plugin configuration will target.

It can also be applied globally (for every Route, Service, or API) using the http://kong:8001/plugins/ endpoint.

Known Issues

PATCH requests to the trust_certificates configuration will not take affect until Kong is reloaded. This can be accomplished with the kong reload command.