Skip to main content
Version: Latest(v3.0) 🔥

Using Static PV When Deploying Kong API Gateway

Overview​

By default, when creating a Kong Gateway using the APIM UI, Persistent Volume Claim (PVC) and Persistent Volume (PV) are dynamically provisioned via StorageClass. However, in certain environments, you may want to use pre-provisioned static PVs. This guide explains how to configure and deploy a Kong Gateway using static PVs.

Pre-deployment Setup​

Define Gateway Name in Advance​

Decide and list the Gateway names you plan to deploy.

Example:

  • test-gw
  • dev-gw

Manually Create PVC Bound to Static PV​

PVC naming convention:

data-<GATEWAY_NAME>-postgresql-0

Example:

data-test-gw-postgresql-0

Make sure the PVC is pre-bound to the appropriate static PV.

Deploy Gateway and Handle Init Migration​

Create Gateway via APIM UI​

Use the same name as previously defined (e.g., test-gw) during Gateway creation in the APIM UI.

Handle Migration Pod Startup Failure​

  • At the init-migrations step, the Pod may fail if the DB is not ready yet.
  • This is usually due to timing issues where Kong starts before the DB is fully initialized.

Manual Migration Execution​

Check Kong Pod Logs​

Confirm that the Pod is waiting for migration via one of the following logs:

kong migrations bootstrap

or

kong migrations up

Add Sleep Command to Kong Container​

Modify the Deployment spec with a custom command to keep the Kong container running:

command: ["/bin/bash", "-c", "sleep 300000"]

This ensures the Kong container enters a sleep state after the init-container finishes.

Execute Manual Migration (Inside Pod)​

Run the following commands to perform migration manually:

k exec -it -n <namespace> <kong-pod-name> -- kong migrations bootstrap
k exec -it -n <namespace> <kong-pod-name> -- kong migrations up

Finalizing for Normal Operation​

Remove Sleep and Restart Kong:

  • Revert or delete the custom command from the Deployment spec.
  • Restart the Kong Pod to allow it to start normally.

Additional Notes​

  • This procedure is only necessary when using static PVs during initial Gateway setup.
  • In production environments, ensure that the DB is fully ready before Kong starts. Use appropriate settings like:
    • initContainer
    • readinessProbe