Sync a Kubernetes TLS Secret to a Konnect Config Store

TL;DR

Create a KonnectConfigStoreSync that points to the Secret and to a KonnectConfigStore. Kong Operator writes the certificate and key to a single Config Store entry. Then set spec.cert and spec.key of a KongCertificate to {vault://PREFIX/STORE_KEY/certificate} and {vault://PREFIX/STORE_KEY/key}. When the Secret changes, the entry is updated in place and the references stay the same.

Prerequisites

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

If you want cert-manager to issue and rotate the admission and conversion webhook certificates, install cert-manager to your cluster and enable cert-manager integration by passing the following argument while installing, in the next step:

   --set global.webhooks.options.certManager.enabled=true

If you do not enable this, the chart will generate and inject self-signed certificates automatically. We recommend enabling cert-manager to manage the lifecycle of these certificates. Kong Operator needs a certificate authority to sign the certificate for mTLS communication between the control plane and the data plane. This is handled automatically by the Helm chart. If you need to provide a custom CA certificate, refer to the certificateAuthority section in the values.yaml of the Helm chart to learn how to create and reference your own CA certificate.

kubectl create namespace kong --dry-run=client -o yaml | kubectl apply -f -
echo '
kind: KonnectAPIAuthConfiguration
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: konnect-api-auth
  namespace: kong
spec:
  type: token
  token: "'$KONNECT_TOKEN'"
  serverURL: us.api.konghq.com
' | kubectl apply -f -
echo '
kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha2
metadata:
  name: gateway-control-plane
  namespace: kong
spec:
  createControlPlaneRequest:
    name: gateway-control-plane
  konnect:
    authRef:
      name: konnect-api-auth
' | kubectl apply -f -

A KongCertificate that reads its certificate and key from a Kubernetes Secret sends the private key to Konnect as part of the certificate object. Anyone who can read certificates in Konnect can read the key.

A KonnectConfigStoreSync keeps the Secret as the source of truth but writes the certificate and key to a Konnect Config Store entry instead. The KongCertificate then references that entry through a KongVault, so the Konnect certificate object only holds vault references. When the Secret is updated, for example by cert-manager, the entry is updated in place and the references don’t change.

The private key is still stored in the Kubernetes Secret, and therefore in the Kubernetes API and etcd. Restrict access to the Secret and enable encryption at rest.

Create a KonnectConfigStore

Create the Config Store container in Konnect. It must reference the KonnectGatewayControlPlane that owns the Config Store:

echo '
kind: KonnectConfigStore
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: cert-keys
  namespace: kong
spec:
  controlPlaneRef:
    type: namespacedRef
    namespacedRef:
      name: gateway-control-plane
  apiSpec:
    name: cert-keys
' | kubectl apply -f -

You can verify the KonnectConfigStore was reconciled successfully by checking its Programmed condition.

kubectl get -n kong konnectconfigstore cert-keys \
  -o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Programmed",
  "status": "True",
  "type": "Programmed"
}

Allow the KongVault to reference the Config Store

KongVault is cluster-scoped, so its references to the KonnectConfigStore and to the KonnectGatewayControlPlane cross a namespace boundary. Allow them with a KongReferenceGrant whose from entry sets namespace: "":

echo '
apiVersion: configuration.konghq.com/v1alpha1
kind: KongReferenceGrant
metadata:
  name: allow-kongvault-to-konnect-resources
  namespace: kong
spec:
  from:
    - group: configuration.konghq.com
      kind: KongVault
      namespace: ""
  to:
    - group: konnect.konghq.com
      kind: KonnectConfigStore
    - group: konnect.konghq.com
      kind: KonnectGatewayControlPlane' | kubectl apply -f -

Create a KongVault backed by the Config Store

Create a KongVault with backend: konnect and point spec.configStoreRef to the KonnectConfigStore:

echo '
kind: KongVault
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: certvault
  namespace: kong
spec:
  backend: konnect
  prefix: certvault
  description: TLS certificates synced from Kubernetes Secrets
  configStoreRef:
    kind: KonnectConfigStore
    name: cert-keys
    namespace: kong
  controlPlaneRef:
    type: konnectNamespacedRef
    konnectNamespacedRef:
      name: gateway-control-plane
      namespace: kong
' | kubectl apply -f -

You can verify the KongVault was reconciled successfully by checking its Programmed condition.

kubectl get -n kong kongvault certvault \
  -o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Programmed",
  "status": "True",
  "type": "Programmed"
}

Create a TLS Secret

  1. Generate a self-signed certificate and key:

    openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.localdomain.dev"
  2. Store them in a TLS Secret:

    kubectl create secret tls example-tls -n kong --cert=tls.crt --key=tls.key
  3. Kong Operator only reads Secrets that carry the konghq.com/secret: "true" label. Add the label so that Kong Operator can read the Secret:

    kubectl label secret example-tls -n kong konghq.com/secret="true"

Sync the Secret to the Config Store

Create a KonnectConfigStoreSync that references the Secret and the KonnectConfigStore. In Combined mode, Kong Operator checks that the certificate and key form a valid pair, then writes both to a single Config Store entry as a JSON object with certificate and key fields:

echo '
kind: KonnectConfigStoreSync
apiVersion: konnect.konghq.com/v1alpha1
metadata:
  name: example-tls
  namespace: kong
spec:
  configStoreRef:
    name: cert-keys
  secretRef:
    name: example-tls
  mode: Combined
  combined:
    storeKey: example-tls
' | kubectl apply -f -

spec.combined.storeKey sets the name of the Config Store entry and is immutable. If you omit it, Kong Operator derives the name from the namespace and name of the KonnectConfigStoreSync, in the format k8s-<len(namespace)>-<namespace>-<len(name)>-<name>.

Confirm that the Secret is synced:

kubectl get -o yaml -n kong konnectconfigstoresync example-tls \
  | yq '.status.conditions[] | select(.type == "Synced") | .status'

You should see the value True.

The KonnectConfigStoreSync publishes the suffixes to use in vault references in status.references:

kubectl get konnectconfigstoresync example-tls -n kong -o jsonpath-as-json='{.status.references}'
[
  {
    "subfield": "certificate",
    "suffix": "example-tls/certificate"
  },
  {
    "subfield": "key",
    "suffix": "example-tls/key"
  }
]

Create a KongCertificate that references the entry

Set spec.cert and spec.key to vault references of the form {vault://PREFIX/SUFFIX}, where PREFIX is the spec.prefix of the KongVault and SUFFIX comes from status.references:

echo '
kind: KongCertificate
apiVersion: configuration.konghq.com/v1alpha1
metadata:
  name: cert-from-secret-sync
  namespace: kong
spec:
  controlPlaneRef:
    type: konnectNamespacedRef
    konnectNamespacedRef:
      name: gateway-control-plane
  cert: "{vault://certvault/example-tls/certificate}"
  key: "{vault://certvault/example-tls/key}"
' | kubectl apply -f -

You can verify the KongCertificate was reconciled successfully by checking its Programmed condition.

kubectl get -n kong kongcertificate cert-from-secret-sync \
  -o=jsonpath='{.status.conditions[?(@.type=="Programmed")]}' | jq

The output should look similar to this:

{
  "observedGeneration": 1,
  "reason": "Programmed",
  "status": "True",
  "type": "Programmed"
}

Use the default spec.type: inline. With spec.type: secretRef, the KongCertificate reads the key from the Secret and sends it to Konnect.

Validate

  1. Fetch the Konnect ID of the control plane:

    export CONTROL_PLANE_ID=$(kubectl get -n kong konnectgatewaycontrolplanes.konnect.konghq.com gateway-control-plane -o jsonpath='{.status.id}')
  2. Confirm that the certificate stored in Konnect holds the vault references rather than the certificate and key material:

    curl -X GET "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/certificates" \
         --no-progress-meter --fail-with-body  \
         -H "Authorization: Bearer $KONNECT_TOKEN"

    The cert and key fields in the response are {vault://certvault/example-tls/certificate} and {vault://certvault/example-tls/key}.

  3. Check the entry status:

    kubectl get konnectconfigstoresync example-tls -n kong -o jsonpath-as-json='{.status.entries}'
  4. Rotate the certificate by replacing the contents of the Secret:

    openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=example.localdomain.dev"
    kubectl create secret tls example-tls -n kong --cert=tls.crt --key=tls.key --dry-run=client -o yaml | kubectl apply -f -
  5. Check the entry status again.

    kubectl get konnectconfigstoresync example-tls -n kong -o jsonpath-as-json='{.status.entries}'

    The hash, notAfter, and lastPushTime fields change once the new pair is synced, while the KongCertificate and its vault references stay the same.

  6. Delete the local copies of the certificate and key:

    rm tls.key tls.crt

FAQs

With a KonnectConfigStoreSync, the Kubernetes Secret stays the source of truth, so tools like cert-manager can keep issuing and rotating certificates as usual. The private key is still stored in the Kubernetes API and etcd. If the key must never enter your cluster, write it to the Config Store directly instead, as described in Store TLS certificate private keys in a Konnect Config Store.

Validation requires the block that matches spec.mode to be set. Use combined: {} to accept the defaults, which read the certificate from tls.crt and the key from tls.key, and derive the store key from the namespace and name of the KonnectConfigStoreSync.

mode: Split writes each Secret field to its own entry, but it’s intended for single-field and non-TLS values. A two-entry rotation briefly exposes a mismatched certificate and key, so use Combined for TLS pairs.

Nothing is written to the Config Store. If the Secret is missing, or the certificate and key are malformed or don’t match, the KonnectConfigStoreSync reports Synced=False and the last value written to the Config Store keeps serving. For every condition reason, see KonnectConfigStoreSync conditions.

With the default spec.deletionPolicy: Orphan, the entry is kept. With Delete, Kong Operator deletes the entries that the sync owns, unless a KongCertificate still references them. For more information, see lifecycle and deletion.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!