Dump server

The dump config server is a diagnostic feature in Kong Operator that allows you to inspect the Kong configuration generated for each ControlPlane. This is particularly useful when debugging configuration issues or understanding how your Kubernetes resources are translated to Kong configuration.

The dump config server is disabled by default. You must enable it when installing or upgrading Kong Operator.

Enable the dump config server by setting the values during installation:

helm upgrade --install kong-operator kong/kong-operator \
  --set enableControlplaneConfigDump=true \
  --set controlplaneConfigDumpPort=10256 \
  --namespace kong-system \
  --create-namespace

# operator-values.yaml
enableControlplaneConfigDump: true
controlplaneConfigDumpPort: 10256  # Optional: defaults to 10256

helm upgrade --install kong-operator kong/kong-operator \
    -f operator-values.yaml \
    --namespace kong-system \
    --create-namespace

Verify the dump config service is created:

kubectl get service -n kong-system kong-operator-kong-operator-config-dump

The output should show:

NAME                                     TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)     AGE
kong-operator-kong-operator-config-dump  ClusterIP   10.96.100.150   <none>        10256/TCP   1m

Create a minimal ControlPlane using the latest v2beta1 API and enable per-ControlPlane config dump.

apiVersion: gateway-operator.konghq.com/v2beta1
kind: ControlPlane
metadata:
  name: controlplane-v2
spec:
  ingressClass: kong # required when dataplane.type is ref. Only Ingress supported
  dataplane:
    type: ref
    ref:
      name: dataplane-v2
  featureGates:
  - name: GatewayAlpha
    state: enabled
  configDump:
    state: enabled
---
apiVersion: gateway-operator.konghq.com/v1beta1
kind: DataPlane
metadata:
  name: dataplane-v2
spec:
  deployment:
    podTemplateSpec:
      metadata:
        labels:
          dataplane-pod-label: example
        annotations:
          dataplane-pod-annotation: example
      spec:
        containers:
        - name: proxy
          image: kong:3.9
          resources:
            requests:
              memory: "64Mi"
              cpu: "250m"
            limits:
              memory: "1024Mi"
              cpu: "1000m"
          readinessProbe:
            initialDelaySeconds: 1
            periodSeconds: 1
  network:
    services:
      ingress:
        annotations:
          foo: bar

Save it to a file and apply it to the cluster:

kubectl apply -f cp-dp-v2.yaml

You can wait for the ControlPlane to be ready:

kubectl wait --for=condition=Ready controlplane controlplane-v2
kubectl get  controlplane controlplane-v2

The output looks like this:

NAME              AGE   READY
controlplane-v2   4m    True

The dump config server is not exposed externally by default. Use port-forwarding to access it locally:

kubectl port-forward -n kong-system service/kong-operator-kong-operator-config-dump 10256:10256

Keep this terminal open while you work with the dump config server.

To see all control planes managed by the operator:

curl http://localhost:10256/debug/controlplanes | jq .

Example response:

{
  "controlPlanes": [
    {
      "namespace": "default",
      "name": "controlplane-v2",
      "id": "e40e8e10-6f3c-4e05-95a1-b1896eb09eaf"
    }
  ]
}

Filter by namespace

To list control planes in a specific namespace:

curl http://localhost:10256/debug/controlplanes/namespace/default | jq .

To inspect the Kong configuration for a specific ControlPlane:

# Replace with your ControlPlane's namespace and name
curl http://localhost:10256/debug/controlplanes/namespace/default/name/controlplane-v2/config/successful

This returns the raw Kong configuration that would be sent to the Kong Admin API.

It looks like this:

{
  "hash": "hash id of the configuration",
  "config": {
    "_format_version": "3.0",
    "_info": {
      "select_tags": [
        "managed-by-ingress-controller"
      ],
      "defaults": {}
    },
    "upstreams": [
      {
        "name": "kong"
      }
    ]
  }
}

Pretty-print the configuration

For better readability, pipe the output through jq:

curl -s http://localhost:10256/debug/controlplanes/namespace/default/name/controlplane-v2/config/successful | jq .

Save configuration to a file

To save the configuration for later analysis:

curl -s http://localhost:10256/debug/controlplanes/namespace/default/name/controlplane-v2/config/successful \
  > controlplane-config-$(date +%Y%m%d-%H%M%S).json

Monitor configuration changes

Create a script to monitor configuration size over time:

#!/bin/bash
# monitor-config-size.sh

NAMESPACE="default"
NAME="controlplane-v2"
INTERVAL=60  # seconds

echo "Monitoring ControlPlane $NAMESPACE/$NAME configuration size..."
echo "Timestamp,Size(bytes)"

while true; do
    SIZE=$(curl -s "http://localhost:10256/debug/controlplanes/namespace/$NAMESPACE/name/$NAME/config/successful" | wc -c)
    TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
    echo "$TIMESTAMP,$SIZE"
    sleep $INTERVAL
done

Compare configurations

To compare configurations between two control planes:

# Dump both configurations
curl -s http://localhost:10256/debug/controlplanes/namespace/default/name/cp1/config/successful > cp1.json
curl -s http://localhost:10256/debug/controlplanes/namespace/default/name/cp2/config/successful > cp2.json

# Compare them (requires jq and diff)
diff <(jq -S . cp1.json) <(jq -S . cp2.json)

Control plane not found

If you get a “ControlPlane not found” error:

1. Verify the ControlPlane exists:

   kubectl get controlplanes -A
   

   Copied!
2. Check that it’s managed by the operator:

   kubectl logs -n kong-system deployment/kong-operator-controller-manager | grep "your-controlplane-name"
   

   Copied!
3. Ensure you’re using the correct namespace and name in the URL.

Config dump not enabled for control plane

If you see “control plane does not enable config dump”:

This means the control plane exists but doesn’t have config dumping enabled at the individual control plane level. This is a per-control plane setting that may need to be configured separately from the global operator setting.

You can use the following command to check the configuration of the config dump:

kubectl get controlplane controlplane-v2 -o jsonpath='{.spec.configDump}'

The output looks like this, the state field should be set to "enabled":

{"dumpSensitive":"disabled","state":"enabled"}

Empty or minimal configuration

If the configuration appears empty or minimal:

1. Check the control plane status:

   kubectl get controlplane -n default my-controlplane -o jsonpath='{.status.conditions}' | jq .
   

   Copied!

2. Verify there are routes or services configured for this control plane.

3. Check operator logs for any errors:

   kubectl logs -n kong-system deployment/kong-operator-kong-operator-controller-manager --tail=50
   

   Copied!

The dump config server exposes potentially sensitive configuration data, including service endpoints and routing rules. Always use proper network policies and RBAC to restrict access to the dump config service in production environments.

Consider these security practices:

1. Use NetworkPolicies to restrict which pods can access the dump config service
2. Implement RBAC to control who can port-forward to the service
3. Avoid exposing the service externally through LoadBalancer or Ingress
4. Monitor access to the dump config endpoints through audit logs