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

Request Termination

This plugin terminates incoming requests with a specified status code and message. This allows to (temporarily) stop traffic on a Service or a Route, or even block a Consumer.

Configuration Reference

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • Setting a target's health status in the load balancer
  • Validating configurations against schemas
  • Uploading the declarative configuration using the /config endpoint

Enable the plugin on a service

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=request-termination"  \
    --data "config.status_code=403" \
    --data "config.message=So long and thanks for all the fish!"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-termination-example>
config: 
  status_code: 403
  message: So long and thanks for all the fish!
plugin: request-termination

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <request-termination-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: request-termination
  service: {SERVICE}
  config: 
    status_code: 403
    message: So long and thanks for all the fish!

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

  1. In Konnect Cloud, select the service on the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Scroll down to Plugins and click New Plugin.
  4. Find and select the Request Termination plugin.
  5. Click Create.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. Find and select the Request Termination 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, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.
  7. Click Create.

Enable the plugin on a route

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=request-termination"  \
    --data "config.status_code=403" \
    --data "config.message=So long and thanks for all the fish!"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-termination-example>
config: 
  status_code: 403
  message: So long and thanks for all the fish!
plugin: request-termination

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <request-termination-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

plugins:
- name: request-termination
  route: <route>
  config: 
    status_code: 403
    message: So long and thanks for all the fish!

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the Request Termination plugin.
  6. Click Create.

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. Find and select the Request Termination plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.
  8. Click Create.

Enabling the plugin on a consumer

For example, configure this plugin on a consumer with:

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=request-termination"  \
    --data "config.status_code=403" \
    --data "config.message=So long and thanks for all the fish!"

CONSUMER is the id or username of the consumer that this plugin configuration will target.

You can combine consumer.id, service.id, or route.id in the same request, to further narrow the scope of the plugin.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-termination-example>
config: 
  status_code: 403
  message: So long and thanks for all the fish!
plugin: request-termination

Then, apply it to a consumer by annotating the KongConsumer resource as follows:

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <request-termination-example>
    kubernetes.io/ingress.class: kong

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a consumer by adding this section to your declarative configuration file:

plugins:
- name: request-termination
  consumer: {CONSUMER}
  config: 
    status_code: 403
    message: So long and thanks for all the fish!

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Configure this plugin on a consumer:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Consumers and click View for the consumer row.
  3. Select the Plugins tab.
  4. Click Add Plugin.

  5. Find and select the Request Termination plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Global.
  7. Click Create.

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=request-termination"  \
    --data "config.status_code=403" \
    --data "config.message=So long and thanks for all the fish!"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-request-termination>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  status_code: 403
  message: So long and thanks for all the fish!
plugin: request-termination

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

plugins:
- name: request-termination
  config: 
    status_code: 403
    message: So long and thanks for all the fish!

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 Request Termination 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. 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 request-termination.
service.id

Type: string		 The ID of the Service the plugin targets.
route.id

Type: string		 The ID of the Route the plugin targets.
consumer.id

Type: string		 The ID of the Consumer the plugin targets.
enabled
required

Type: boolean

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

Type: integer

Default value: 503

The response code to send. Must be an integer between 100 and 599.
config.message
optional

Type: string

The message to send, if using the default response generator.
config.body
optional

Type: string

The raw response body to send. This is mutually exclusive with the config.message field.
config.content_type
optional

Type: string

Default value: application/json; charset=utf-8

Content type of the raw response configured with config.body.
config.trigger
optional

When not set, the plugin always activates. When set to a string, the plugin will activate exclusively on requests containing either a header or a query parameter that is named the string.
config.echo
optional

Default value: false

When set, the plugin will echo a copy of the request back to the client. The main usecase for this is debugging. It can be combined with trigger in order to debug requests on live systems without disturbing real traffic.

Once applied, every request (within the configured plugin scope of a Service, Route, Consumer, or global) will be immediately terminated by sending the configured response.

New in 2.1.0

  • trigger config option
  • echo config option

Example Use Cases

  • Temporarily disable a Service (e.g. it is under maintenance).
  • Temporarily disable a Route (e.g. the rest of the Service is up and running, but a particular endpoint must be disabled).
  • Temporarily disable a Consumer (e.g. excessive consumption).
  • Block anonymous access with multiple auth plugins in a logical OR setup.
  • Debugging erroneous requests in live systems.