You are browsing documentation for an older version. See the latest documentation here.

Cassandra to PostgreSQL Migration Guidelines

This guide walks you through migrating Kong Gateway from a Cassandra DB-backed traditional deployment to a PostgreSQL-backed hybrid deployment.

This guide uses a blue-green migration approach. In this approach, DNS switching helps cut traffic over from a Blue environment to a Green environment. This provides the ability to roll back faster if an issue is detected.

We recommend using decK, Kong’s declarative configuration management tool.

Migration steps:

1. Build a target Kong Gateway hybrid environment with PostgreSQL. This acts as your blank canvas.
2. Use decK to export (dump) configuration from the old traditional Cassandra-backed deployment.
3. Use decK to import (sync) the configuration to the new hybrid PostgreSQL-backed deployment.
4. Create basic auth credentials and local RBAC users using either the Admin API or Kong Manager.
5. When the Kong Gateway configuration has been migrated over to the green environment, slowly redirect traffic via canary into the green environment. This lowers the risk of the release with a fast rollback mechanism in place.

Considerations

While the document provides high level guidelines, actual migration steps may differ based on the following factors:

• Complexity of the Kong deployment environment
• Kong plugins
• Custom plugins
• External touch points to the Gateway (for example, OIDC with external IdPs)
• Number of configuration entities, for example services and routes
• If running an older version of Kong Gateway, we recommend doing a Kong Gateway version upgrade before the database migration. This reduces the moving parts in the upgrade procedure.
• If you’re using Cassandra, you likely have a traditional deployment. We recommend taking this opportunity to review the deployment topology options for Kong Gateway and converting to a hybrid mode deployment, if possible.

The following diagram shows the architecture of a hybrid mode deployment, which means there is a split between the Kong Gateway control and data planes. You can follow the same database migration approach for Kong Gateway instances deployed in traditional mode.

flowchart LR
A[api.customer.com]
B[(Cassandra)]
C( Kong Gateway VM)
D( Kong Gateway DP)
E( Kong Gateway CP)
F[(Postgres)]
H[[decK]]
A --> C & D
subgraph id1 ["`**On premise**`"]
C --> B
end
subgraph id2 ["`**Kubernetes**`"]
D --> E --> F
end
C --export config via yaml--> H --sync config to CP--> E
style id1 stroke-dasharray:3,rx:10,ry:10
style id2 stroke-dasharray:3,rx:10,ry:10

Prerequisites

• The Kong Gateway blue environment (using Cassandra) and green environment (using PostgreSQL) are running the same Gateway version.
• In the following examples, blue is deployed in traditional mode and green is deployed in hybrid mode. If you prefer to migrate to a traditional deployment, you can still follow the steps, but you don’t need to worry about performing separate control plane and data plane tasks.

Migration approach

The following steps should be tested in a non-production environment. Any gaps in the target state should be identified and remediated before running it in production.

Preparation

Execution

The goal of this phase is to reproduce the Kong Gateway configuration in the blue environment and perform regression and smoke testing ahead of live traffic cut-over.

Traffic cut over

The purpose of this phase is to migrate traffic in a controlled manner, with a rapid fallback mechanism if a problem is detected. You can increase or decrease the wait times before increasing the canary split depending on the risk tolerance.

Next steps

• If using the Basic Authentication plugin, the passwords are hashed and encrypted in the database. A decK dump doesn’t export these credentials, so it is impossible to get the passwords out of the database in the cleartext. You must migrate these credentials using the Admin Api or Kong Manager.

• Admin users on the Kong Gateway control plane are not propagated using decK. Migrate them using the Kong Admin API.

After migration, basic authentication credentials can be managed by decK. See the following topics to learn how to manage secrets with deck:

• Gateway secret management GCP
• Secrets management with decK