helm upgrade --install kong-operator kong/kong-operator -n kong-system \
--create-namespace \
--set image.tag=2.4 \
--set env.ENABLE_CONTROLLER_KONNECT=true
kubectl -n kong-system wait --for=condition=Available=true --timeout=300s deployment/kong-operator-kong-operator-controller-managerSync a Kubernetes TLS Secret to a Konnect Config Store
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
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- 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.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Kong Operator running
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=trueIf 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.
Create a KonnectAPIAuthConfiguration resource
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 -Create a KonnectGatewayControlPlane resource
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")]}' | jqThe 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")]}' | jqThe output should look similar to this:
{
"observedGeneration": 1,
"reason": "Programmed",
"status": "True",
"type": "Programmed"
}Create a TLS Secret
-
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" -
Store them in a TLS Secret:
kubectl create secret tls example-tls -n kong --cert=tls.crt --key=tls.key -
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")]}' | jqThe 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
-
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}') -
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
certandkeyfields in the response are{vault://certvault/example-tls/certificate}and{vault://certvault/example-tls/key}. -
Check the entry status:
kubectl get konnectconfigstoresync example-tls -n kong -o jsonpath-as-json='{.status.entries}' -
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 - -
Check the entry status again.
kubectl get konnectconfigstoresync example-tls -n kong -o jsonpath-as-json='{.status.entries}'The
hash,notAfter, andlastPushTimefields change once the new pair is synced, while theKongCertificateand its vault references stay the same. -
Delete the local copies of the certificate and key:
rm tls.key tls.crt
FAQs
How is this different from writing the key to the Config Store directly?
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.
Why do I need combined: {} if Combined is the default mode?
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.
Can I sync the certificate and the key into separate entries?
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.
What happens if the Secret is deleted or contains invalid data?
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.
What happens to the Config Store entry when I delete the KonnectConfigStoreSync?
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.