DB-less mode

Kong Gateway can be run without a database using only in-memory storage for entities. We call this DB-less mode. When running Kong Gateway DB-less, the configuration of entities is done in a second configuration file, in YAML or JSON, using declarative configuration.

The combination of DB-less mode and declarative configuration has a number of benefits:

• Reduced number of dependencies: No need to manage a database installation if the entire setup for your use-cases fits in memory.
• Automation in CI/CD scenarios: Configuration for entities can be kept in a single source of truth managed via a Git repository.
• Enables more deployment options for Kong Gateway.

Important: decK also manages configuration declaratively, but it requires a database to perform any of its sync, dump, or similar operations. Therefore, decK can’t be used in DB-less mode.

 
flowchart TD

A( Kong Gateway instance)
B( Kong Gateway instance)
C( Kong Gateway instance)

A2(fa:fa-file kong1.yml)
B2(fa:fa-file kong1.yml)
C2(fa:fa-file kong1.yml)

A2 --> A
B2 --> B
C2 --> C

  

The key idea in declarative configuration is the notion that it is declarative, as opposed to an imperative style of configuration. Imperative means that a configuration is given as a series of orders. Declarative means that the configuration is given all at once.

The Admin API is an example of an imperative configuration tool. The final state of the configuration is attained through a sequence of API calls: one call to create a Service, another call to create a Route, another call to add a plugin, and so on.

Incremental configuration like this has the undesirable side-effect that intermediate states happen. In the above example, there is a window of time in between creating a Route and adding the plugin in which the Route didn’t have the plugin applied.

A declarative configuration file, on the other hand, contains the settings for all needed entities in a single file. Once that file is loaded into Kong Gateway, it replaces the entire configuration. When incremental changes are needed, they are made to the declarative configuration file, which is then reloaded in its entirety. At all times, the configuration described in the file loaded into Kong Gateway is the configured state of the system.

To use Kong Gateway in DB-less mode, set the database directive of kong.conf to off. You can do this by editing kong.conf and setting database=off or via environment variables (export KONG_DATABASE=off), and then starting Kong Gateway.

You can verify that Kong Gateway is deployed in DB-less mode by sending the following:

curl -i -X GET http://localhost:8001

This will return the entire Kong Gateway configuration. Verify that database is set to off in the response body.

There are two ways to load a declarative configuration file into Kong Gateway: using kong.conf or the using the /config Admin API endpoint.

You can use the following kong.conf parameters to load the declarative config file:

You can run DB-less mode with Kubernetes both with and without Kong Ingress Controller.

DB-less mode with Kong Ingress Controller

Kong Ingress Controller provides a Kubernetes native way to configure Kong Gateway using custom resource definitions (CRDs). In this deployment pattern, Kong Gateway is deployed in DB-less mode, where the Data Plane configuration is held in memory.

Operators configure Kong Gateway using standard CRDs such as Ingress and HTTPRoute, and Kong Ingress Controller translates those resources into Kong Gateway entities before sending a request to update the running Data Plane configurations.

In this topology, the Kubernetes API server is your source of truth. Kong Ingress Controller reads resources stored on the API server and translates them into a valid Kong Gateway configuration object. You can think of Kong Ingress Controller as the Control Plane for your DB-less Data Planes.

For more information about Kong Gateway and Kong Ingress Controller, see the Kong Ingress Controller getting started guide. This guide walks you through installing Kong Gateway, configuring a Service and Route, then adding a rate limiting and caching plugin to your deployment.

DB-less with Helm (Kong Ingress Controller disabled)

When deploying Kong Gateway on Kubernetes in DB-less mode (env.database: "off") and without the Kong Ingress Controller (ingressController.enabled: false), you have to provide a declarative configuration for Kong Gateway to run. You can provide an existing ConfigMap (dblessConfig.configMap) or place the whole configuration into a values.yaml (dblessConfig.config) parameter. See the example configuration in the default values.yaml for more detail.

Use --set-file dblessConfig.config=/path/to/declarative-config.yaml in Helm commands to substitute in a complete declarative config file.

Externally supplied ConfigMaps aren’t hashed or tracked in deployment annotations. Subsequent ConfigMap updates require user-initiated deployment rollouts to apply the new configuration. Run kubectl rollout restart deploy after updating externally supplied ConfigMap content.

There are a number of limitations you should be aware of when using Kong Gateway in DB-less mode.

Memory cache requirements

The entire configuration of entities must fit inside the Kong Gateway cache. Make sure that the in-memory cache is configured appropriately in kong.conf:

No central database coordination

Since there is no central database, Kong Gateway nodes have no central coordination point and no cluster propagation of data. Nodes are completely independent of each other.

This means that the declarative configuration should be loaded into each node independently. Using the /config endpoint doesn’t affect other Kong Gateway nodes, since they have no knowledge of each other.

Read-only Admin API

Since the only way to configure entities is via declarative configuration, the endpoints for CRUD operations on entities are effectively read-only in the Admin API when running Kong Gateway in DB-less mode. GET operations for inspecting entities work as usual, but attempts to POST, PATCH PUT or DELETE in endpoints such as /services or /plugins will return HTTP 405 Not Allowed.

This restriction is limited to what would otherwise be database operations. In particular, using POST to set the health state of targets is still enabled, since this is a node-specific in-memory operation.

Kong Manager compatibility

Kong Manager cannot guarantee compatibility with Kong Gateway operating in DB-less mode. You cannot create, update, or delete entities with Kong Manager when Kong Gateway is running in this mode. Entity counters in the Summary section on the global and workspace overview pages will not function correctly either.

Plugin compatibility

Not all Kong Gateway plugins are compatible with DB-less mode. By design, some plugins require central database coordination or dynamic creation of entities.

For current plugin compatibility, see Plugins.