GraphQL Rate Limiting Advanced

The GraphQL Rate Limiting Advanced plugin provides rate limiting for GraphQL queries. The GraphQL Rate Limiting plugin extends the Rate Limiting Advanced plugin.

Configuration Reference

This plugin is partially 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

The cluster strategy is not supported in DB-less and hybrid modes. For Kong Gateway in DB-less or hybrid mode, use the redis strategy.

Enable the plugin on a service

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=graphql-rate-limiting-advanced"  \
    --data "config.cost_strategy=default" \
    --data "config.limit=5" \
    --data "config.window_size=30" \
    --data "config.identifier=consumer" \
    --data "config.dictionary_name=kong_rate_limiting_counters" \
    --data "config.sync_rate=-1" \
    --data "config.strategy=cluster" \
    --data "config.window_type=sliding"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <graphql-rate-limiting-advanced-example>
config: 
  cost_strategy: default
  limit:
  - 5
  window_size:
  - 30
  identifier: consumer
  dictionary_name: kong_rate_limiting_counters
  sync_rate: -1
  strategy: cluster
  window_type: sliding
plugin: graphql-rate-limiting-advanced

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

plugins:
- name: graphql-rate-limiting-advanced
  service: {SERVICE}
  config: 
    cost_strategy: default
    limit:
    - 5
    window_size:
    - 30
    identifier: consumer
    dictionary_name: kong_rate_limiting_counters
    sync_rate: -1
    strategy: cluster
    window_type: sliding

Enable the plugin on a route

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=graphql-rate-limiting-advanced"  \
    --data "config.cost_strategy=default" \
    --data "config.limit=5" \
    --data "config.window_size=30" \
    --data "config.identifier=consumer" \
    --data "config.dictionary_name=kong_rate_limiting_counters" \
    --data "config.sync_rate=-1" \
    --data "config.strategy=cluster" \
    --data "config.window_type=sliding"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <graphql-rate-limiting-advanced-example>
config: 
  cost_strategy: default
  limit:
  - 5
  window_size:
  - 30
  identifier: consumer
  dictionary_name: kong_rate_limiting_counters
  sync_rate: -1
  strategy: cluster
  window_type: sliding
plugin: graphql-rate-limiting-advanced

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

plugins:
- name: graphql-rate-limiting-advanced
  route: <route>
  config: 
    cost_strategy: default
    limit:
    - 5
    window_size:
    - 30
    identifier: consumer
    dictionary_name: kong_rate_limiting_counters
    sync_rate: -1
    strategy: cluster
    window_type: sliding

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.

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=graphql-rate-limiting-advanced"  \
    --data "config.cost_strategy=default" \
    --data "config.limit=5" \
    --data "config.window_size=30" \
    --data "config.identifier=consumer" \
    --data "config.dictionary_name=kong_rate_limiting_counters" \
    --data "config.sync_rate=-1" \
    --data "config.strategy=cluster" \
    --data "config.window_type=sliding"

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-graphql-rate-limiting-advanced>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  cost_strategy: default
  limit:
  - 5
  window_size:
  - 30
  identifier: consumer
  dictionary_name: kong_rate_limiting_counters
  sync_rate: -1
  strategy: cluster
  window_type: sliding
plugin: graphql-rate-limiting-advanced

plugins:
- name: graphql-rate-limiting-advanced
  config: 
    cost_strategy: default
    limit:
    - 5
    window_size:
    - 30
    identifier: consumer
    dictionary_name: kong_rate_limiting_counters
    sync_rate: -1
    strategy: cluster
    window_type: sliding

Parameters

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

Note: Redis configuration values are ignored if the cluster strategy is used.

Notes:

• PostgreSQL 9.5+ is required when using the cluster strategy with postgres as the backing Kong cluster data store. This requirement varies from the PostgreSQL 9.4+ requirement as described in the Kong Community Edition documentation.

• The dictionary_name directive was added to prevent the usage of the kong shared dictionary, which could lead to no memory errors.

The GraphQL Rate Limiting Advanced plugin is an extension of the Rate Limiting Advanced plugin and provides rate limiting for GraphQL queries.

Due to the nature of client-specified GraphQL queries, the same HTTP request to the same URL with the same method can vary greatly in cost depending on the semantics of the GraphQL operation in the body.

A common pattern to protect your GraphQL API is then to analyze and assign costs to incoming GraphQL queries and rate limit the consumer’s cost for a given time window.

Costs in GraphQL queries

GraphQL query costs are evaluated by introspecting the endpoint’s GraphQL schema and applying cost decoration to parts of the schema tree.

Initially all nodes start with zero cost, with any operation at cost 1. Add rate-limiting constraints on any subtree. If subtree omitted, then rate-limit window applies on the whole tree (any operation).

Since there are many ways of approximating the cost of a GraphQL query, the plugin exposes two strategies: default and node_quantifier.

The following example queries can be run on this SWAPI playground.

default

The default strategy is meant as a good middle ground for general GraphQL queries, where it’s difficult to assert a clear cost strategy, so every operation has a cost of 1.

query { # + 1
  allPeople {  # + 1
    people { # + 1
      name # + 1
    }
  }
}

# total cost: 4

Default node costs can be defined by decorating the schema:

query { # + 1
  allPeople(first:20) { # * 20 + 1
    people { # + 1
      name # + 1
      vehicleConnection(first:10) { # * 10 + 1
        vehicles { # + 1
          id  # + 1
          name # + 1
          cargoCapacity # + 1
        }
      }
    }
  }
}

# total cost: ((((4 * 10 + 1) + 1) + 1) * 20 + 1) + 1 = 862

Generally speaking, vehicleConnection weight (4) is applied 10 times, and the total weight of it (40) 20 times, which gives us a rough 800.

Cost constants can be atomically defined as:

On this example, Vehicle.name and Person.vehicleConnection have specific weights of 8 and 5 respectively. allPeople weights 2, and also has double its weight when multiplied by arguments.

query { # + 1
  allPeople(first:20) { # 2 * 20 + 2
    people { # + 1
      name # + 1
      vehicleConnection(first:10) { # * 10 + 5
        vehicles { # + 1
          id  # + 1
          name # + 8
          cargoCapacity # + 1
        }
      }
    }
  }
}

# total cost: ((((11 * 10 + 5) + 1) + 1) * 2 * 20 + 2) + 1 = 4683

node_quantifier

This strategy is fit for GraphQL schemas that enforce quantifier arguments on any connection, providing a good approximation on the number of nodes visited for satisfying a query. Any query without decorated quantifiers has a cost of 1. It is roughly based on github’s GraphQL resource limits.

query {
  allPeople(first:100) { # 1
    people {
      name
      vehicleConnection(first:10) { # 100
        vehicles {
          name
          filmConnection(first:5) { # 10 * 100
            films{
              title
              characterConnection(first:50) { # 5 * 10 * 100
                characters {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}
# total cost: 1 + 100 + 10 * 100 + 5 * 10 * 100 = 6101

Roughly speaking:

• allPeople returns 100 nodes, and has been called once
• vehicleConnection returns 10 nodes, and has been called 100 times
• filmConnection returns 5 nodes, and has been called 10 * 100 times
• characterConnection returns 50 nodes, and has been called 5 * 10 * 100 times

Specific costs per node can be specified by adding a constant:

query {
  allPeople(first:100) { # 1
    people {
      name
      vehicleConnection(first:10) { # 100 * 42
        vehicles {
          name
          filmConnection(first:5) { # 10 * 100
            films{
              title
              characterConnection(first:50) { # 5 * 10 * 100
                characters {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}
# total cost: 1 + 100 * 42 + 10 * 100 + 5 * 10 * 100 = 10201

Usage

The following configuration example targets a GraphQL endpoint at our SWAPI playground.

Add a GraphQL service and route

curl -X POST http://kong:8001/services \
  --data "name=example" \
  --data "host=mockbin.org" \
  --data "port=443" \
  --data "protocol=https"

curl -X POST http://kong:8001/services/example/routes \
  --data "hosts=example.com"

Enable the plugin on the service

Example using a single time window:

curl -i -X POST http://kong:8001/services/example/plugins \
  --data name=graphql-rate-limiting-advanced \
  --data config.limit=100 \
  --data config.window_size=60 \
  --data config.sync_rate=10

Example using multiple time windows:

curl -i -X POST --url http://kong:8001/services/example/plugins \
  --data 'name=graphql-rate-limiting-advanced' \
  --data 'config.window_size[]=60' \
  --data 'config.window_size[]=3600' \
  --data 'config.limit[]=10' \
  --data 'config.limit[]=100' \
  --data 'config.sync_rate=10'

Decorate gql schema for costs

Cost decoration schema looks like:

Cost decoration is available on the following routes:

/services/{service}/graphql-rate-limiting-advanced/costs

• GET: list of costs associated to a service schema
• PUT, POST: add a cost to a service schema

For example:

curl -X POST http://kong:8001/services/example/graphql-rate-limiting-advanced/costs \
  --data type_path="Query.allPeople" \
  --data mul_arguments="first"


curl -X POST http://kong:8001/services/example/graphql-rate-limiting-advanced/costs \
  --data type_path="Person.vehicleConnection" \
  --data mul_arguments="first"
  --data add_constant=42

curl -X POST http://kong:8001/services/example/graphql-rate-limiting-advanced/costs \
  --data type_path="Vehicle.filmConnection" \
  --data mul_arguments="first"


curl -X POST http://kong:8001/services/example/graphql-rate-limiting-advanced/costs \
  --data type_path="Film.characterConnection" \
  --data mul_arguments="first"

/graphql-rate-limiting-advanced/costs

• GET: list of all costs on any service
• PUT, POST: add a cost to a service schema

/graphql-rate-limiting-advanced/costs/{cost_id}

• GET: get cost associated by id
• PATCH: modify cost associated by id
• DELETE: delete cost associated by id

Changing the default strategy

curl -X POST http://kong:8001/services/example/plugins \
  --data name=graphql-rate-limiting-advanced \
  --data config.limit=100 \
  --data config.limit=10000 \
  --data config.window_size=60 \
  --data config.window_size=3600 \
  --data config.sync_rate=10 \
  --data config.cost_strategy=default

curl -i -X PATCH http://kong:8001/plugins/{plugin_id} \
  --data config.cost_strategy=node_quantifier

Limit query cost by using config.max_cost

It’s usually a good idea to define a maximum cost applied to any query, regardless if the call is within the rate limits for a consumer.

By defining a max_cost on our service, we are ensuring no query will run with a cost higher than our set max_cost. By default it’s set to 0, which means no limit.

curl -X POST http://kong:8001/services/example/plugins \
  --data name=graphql-rate-limiting-advanced \
  --data config.limit=100 \
  --data config.limit=10000 \
  --data config.window_size=60 \
  --data config.window_size=3600 \
  --data config.sync_rate=0 \
  --data config.max_cost=5000

To update max_cost:

curl -X PATCH http://kong:8001/plugins/{plugin_id} \
  --data config.max_cost=10000

Using config.score_factor to modify costs

GraphQL query cost depends on multiple factors based on our resolvers and the implementation of the schema. Cost on queries, depending on the cost strategy might turn very high when using quantifiers, or very low with no quantifiers at all. By using config.score_factor the cost can be divided or multiplied to a certain order of magnitude.

For example, a score_factor of 0.01 will divide the costs by 100, meaning every cost unit represents 100 nodes.

curl -X POST http://kong:8001/services/example/plugins \
  --data name=graphql-rate-limiting-advanced \
  --data config.limit=100 \
  --data config.limit=10000 \
  --data config.window_size=60 \
  --data config.window_size=3600 \
  --data config.sync_rate=0 \
  --data config.max_cost=5000 \
  --data config.score_factor=0.01

To update score_factor:

curl -i -X PATCH http://kong:8001/plugins/{plugin_id} \
  --data config.score_factor=1

Changelog

Kong Gateway 2.8.x (plugin version 0.2.5)

• Added the redis.username and redis.sentinel_username configuration parameters.

• The redis.username, redis.password, redis.sentinel_username, and redis.sentinel_password configuration fields are now marked as referenceable, which means they can be securely stored as secrets in a vault. References must follow a specific format.

• Fixed plugin versions in the documentation. Previously, the plugin versions were labelled as 1.3-x and 2.3.x. They are now updated to align with the plugin’s actual versions, 0.1.x and 0.2.x.