Estimated reading time:
Warning: This feature is released as BETA and should not be deployed in a production environment.
To get started with a Hybrid mode deployment, first install an instance of
Kong Enterprise with TLS to be your Control Plane (CP) node. See the
We will bring up any subsequent Data Plane (DP) instances in this topic.
Note: For a Hybrid mode deployment on Kubernetes, see Hybrid mode
Step 1: Generate a certificate/key pair
In Hybrid mode, a mutual TLS handshake (mTLS) is used for authentication so the
actual private key is never transferred on the network, and communication
between CP and DP nodes is secure.
Before using Hybrid mode, you need to generate a shared certificate/key pair.
This certificate/key pair is shared by both CP and DP nodes.
Protect the Private Key. Ensure the private key file can only be accessed by
Kong nodes belonging to the cluster. If the key is compromised, you must
regenerate and replace certificates and keys on all CP and DP nodes.
- On an existing Kong Gateway instance, create a certificate/key pair:
This will generate
cluster.key files and save them to
the current directory. By default, the certificate/key pair is valid for three
years, but can be adjusted with the
--days option. See
kong hybrid --help
for more usage information.
- Copy the
cluster.key files to the same directory
on all Kong CP and DP nodes; e.g.,
Set appropriate permissions on the key file so it can only be read by Kong.
Step 2: Set up the Control Plane
Next, give the Control Plane node the
control_plane role, and set
certificate/key parameters to point at the location of your
Note that the Control Plane still needs a database (Postgres or Cassandra) to
store the central configurations, although the database never needs to
be accessed by Data Plane nodes. You may run multiple Control Plane nodes to
provide load balancing and redundancy, as long as they all point to the same
Note: Control Plane nodes cannot be used for proxying.
Step 3: Install and start Data Planes
Now that the Control Plane is running, you can attach Data Plane nodes to it to
start serving traffic.
In this step, you will give all Data Plane nodes the
point them to the Control Plane, set certificate/key parameters to point at
the location of your
cluster.key, and ensure the database
Important: Data Plane nodes receive updates from the Control Plane via a format
similar to declarative config, therefore the storage property has to be
memory for Kong to start up properly.
Step 4: Verify that nodes are connected
Use the Control Plane’s Cluster Status API to monitor your Data Planes. It provides:
- The name of the node
- The last time the node synced with the Control Plane
- The version of the config currently running on each Data Plane
To check whether the CP and DP nodes you just brought up are connected, run the
following on a Control Plane:
The output shows all of the connected Data Plane instances:
Now, you can start managing the cluster using the Control Plane. Once
all instances are set up, use the Admin API on the Control Plane as usual, and
these changes will be synced and updated on the Data Plane nodes automatically