Setting up certificates

Event Streams is secure by default. All internal and external communication is TLS-encrypted. Confluent Platform supports the same standard, but TLS must be explicitly configured. Set up your certificate authorities and issue the required certificates before you deploy any Confluent Platform custom resources.

Certificate model differences

Review the certificate model differences between Event Streams and CFK as part of planning your migration.

Event Streams certificate model

In Event Streams, the operator manages the entire certificate lifecycle automatically by default. It generates a Cluster CA and a Client CA at install time, then issues a unique certificate per broker signed by the Cluster CA. Each broker has its own key pair with SANs scoped to that broker’s DNS name. The operator also issues individual client certificates for KafkaUser resources and handles certificate rotation, including CA renewal and per-broker certificate reissuance, without any manual intervention. To supply your own CA instead, set generateCertificateAuthority: false on the Cluster CA or Client CA. In that case, you must supply your own CA certificate and key.

CFK certificate model

Unlike Event Streams, CFK does not generate or rotate certificates automatically by default. CFK provides an option to use auto-generated TLS certificates. For more information, see use auto-generated TLS certificates. Alternatively, you can supply your own certificates and manage the certificate lifecycle.

By default, CFK applies a single global TLS certificate to all listeners of a component by using spec.tls.secretRef. This guide uses separate certificates per listener, following the same two-CA separation that Event Streams enforces. The two certificates used in this guide are described as follows:

• cluster-tls: the certificate for the controller and replication listener. In the two-CA setup, this certificate is signed by a Cluster CA dedicated to internal communication. Wildcard entries in the SANs (for example, *.<namespace>.svc.cluster.local) cover all brokers and internal components without issuing a separate certificate per pod.
• client-tls: the certificate for the external listener. In the two-CA setup, this certificate is signed by a separate Client CA. The SANs cover both the internal cluster DNS and all external broker addresses that clients connect to.

Create the CAs, issue the required certificates, and store them in Kubernetes secrets. CFK supports TLS configuration through Kubernetes secrets in PEM or Java KeyStore (JKS) formats. The supported secret formats are:

You can use any PKI tooling that produces secrets in one of these formats, such as cert-manager, OpenSSL, or your corporate PKI. For how CFK consumes TLS secrets, see the CFK TLS documentation.

Separate CAs for internal and external communication

Event Streams enforces a two-CA model: a Cluster CA for internal broker communication and a Client CA for external listener and client certificates. This separation ensures that a compromise of one CA does not affect the other. Although CFK does not enforce this model, using the same two-CA pattern is the preferred approach for security. Use one CA for internal broker communication and a separate CA for external clients.

Note: Unless you are using the listener certificate override path, external application clients connecting to the Confluent Platform external listener must trust the Client CA, not the Cluster CA. The Cluster CA is only used for internal broker-to-broker communication and is not presented on the external listener. If you are migrating mTLS-authenticated client applications, you use this Client CA to issue user certificates. For more information, see migrating mTLS users.

Certificate rotation

In Event Streams, the operator rotates all certificates automatically for operator-generated CAs. If you supply your own CA, you must rotate it.

In CFK, certificate rotation depends on which approach you use:

• Auto-generated certificates: You supply the CA. CFK automates provisioning and renewing the server certificates from it. CA rotation is your responsibility. CFK does not rotate the CA you provide.
• cert-manager: cert-manager handles automated server certificate renewal as long as it writes the renewed certificates back to the Kubernetes secrets that CFK references. cert-manager manages CA rotation only if the CA itself is a cert-manager Certificate resource. Otherwise, you must manage it manually.
• Manual certificates: You must handle issuing certificates, renewal, CA rotation, and secret updates manually. After the secrets are updated, CFK detects the change and performs the necessary rolling restarts for supported configurations.

Choose your migration path

Your migration path depends on how certificates were configured in your Event Streams deployment. Review the table to identify your scenario and follow the corresponding guidance.

Generate new CAs

If Event Streams was using operator-generated CAs (the default), there are no existing CA certificates or private keys to migrate. Create two new CAs by using your chosen PKI tooling: one Cluster CA and one Client CA. Use them to issue the CFK listener and client certificates, and place the resulting certificates and keys in Kubernetes secrets in one of the formats CFK supports (for example, tls.crt, tls.key, and ca.crt for PEM).

After you issue the certificates and place the cluster-tls and client-tls Kubernetes secrets, configure both the KRaftController and Kafka custom resources to reference them. Deploy KRaftController first and wait for it to reach a Ready state before deploying Kafka.

Add the following configuration to your KRaftController custom resource:

spec:
  listeners:
    controller:
      tls:
        enabled: true
        secretRef: cluster-tls    # signed by the Cluster CA, used for controller-to-broker communication

Add the following configuration to your Kafka custom resource:

spec:
  dependencies:
    kRaftController:
      clusterRef:
        name: kraftcontroller     # must match the name of your KRaftController resource
      controllerListener:
        tls:
          enabled: true
          secretRef: cluster-tls  # must match the secretRef on the KRaftController listener
  listeners:
    external:
      tls:
        enabled: true
        secretRef: client-tls     # signed by the Client CA, presented to external clients
  replication:
    tls:
      enabled: true
      secretRef: cluster-tls      # inter-broker replication uses the same Cluster CA certificate

Where:

• cluster-tls is the Kubernetes secret containing the certificate signed by your Cluster CA, with wildcard SANs covering internal cluster DNS.
• client-tls is the Kubernetes secret containing the certificate signed by your Client CA, with SANs covering both internal cluster DNS and external broker addresses.

All client applications must update their truststores to include the new Client CA, because you are replacing the CA entirely.

Import existing Cluster CA

If you supplied a custom Cluster CA to Event Streams, reuse it so that CFK broker certificates are signed by the same root CA.

Event Streams stores the Cluster CA in two secrets in the Event Streams namespace:

CFK reads CA secrets as standard Kubernetes tls secrets containing only the certificate and key. Run the following commands to extract the Cluster CA and create the secret in the Confluent namespace:

# Extract the Cluster CA certificate and key from Event Streams
kubectl get secret <instance-name>-cluster-ca \
  -n <es-namespace> \
  -o jsonpath='{.data.ca\.key}' | base64 -d > cluster-ca.key

kubectl get secret <instance-name>-cluster-ca-cert \
  -n <es-namespace> \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > cluster-ca.crt

# Create the imported CA secret in the Confluent namespace
kubectl create secret tls es-imported-cluster-ca \
  -n <confluent-namespace> \
  --cert=cluster-ca.crt \
  --key=cluster-ca.key

Where:

• <instance-name> is the name of your Event Streams instance.
• <es-namespace> is the Kubernetes namespace where Event Streams is deployed.
• <confluent-namespace> is the Kubernetes namespace where you are deploying Confluent Platform (for example, confluent).

Use the es-imported-cluster-ca secret to issue broker certificates with the updated CFK SANs:

• If you are using cert-manager, create a ClusterIssuer or Issuer that references this secret as the CA, then issue the broker certificate from it.
• If you are using a different PKI tooling, use the extracted cluster-ca.crt and cluster-ca.key files directly to sign the new broker certificates.

Important: The bootstrap addresses and broker SANs change when moving to CFK. You must issue new broker certificates with the updated SANs even if you are reusing the same CA. Existing client truststores that already trust this CA require no changes for broker verification.

Import existing Client CA

If you supplied a custom Client CA that you used to sign KafkaUser mTLS certificates, reuse it on CFK so that existing client certificates remain valid.

Event Streams stores the Client CA in two secrets in the Event Streams namespace:

Run the following commands to extract the Client CA and create the secret in the Confluent namespace:

# Extract the Client CA certificate and key from Event Streams
kubectl get secret <instance-name>-clients-ca \
  -n <es-namespace> \
  -o jsonpath='{.data.ca\.key}' | base64 -d > client-ca.key

kubectl get secret <instance-name>-clients-ca-cert \
  -n <es-namespace> \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > client-ca.crt

# Create the imported CA secret in the Confluent namespace
kubectl create secret tls es-imported-client-ca \
  -n <confluent-namespace> \
  --cert=client-ca.crt \
  --key=client-ca.key

Where:

• <instance-name> is the name of your Event Streams instance.
• <es-namespace> is the Kubernetes namespace where Event Streams is deployed.
• <confluent-namespace> is the Kubernetes namespace where you are deploying Confluent Platform (for example, confluent).

Use the es-imported-client-ca secret to issue the external listener certificate and any new client certificates:

• If you are using cert-manager, create a ClusterIssuer or Issuer that references this secret as the CA, then issue the listener and client certificates from it.
• If you are using a different PKI tooling, use the extracted client-ca.crt and client-ca.key files directly to sign the new certificates.

Because the CA root has not changed, existing client certificates that have not expired remain valid without reissuance, and client truststores require no changes.

Migrate listener certificate override

Note: This only applies if your Event Streams deployment used the brokerCertChainAndKey listener override to supply a PKI-issued certificate for the broker’s external listener.

In Event Streams, the brokerCertChainAndKey listener override provides a PKI-issued certificate that the broker presents to clients on the external listener. Because clients already have the PKI CA in their truststore, they can verify the broker without any additional configuration.

On CFK, you configure the equivalent by placing the broker certificate and key in the secretRef secret for the external listener. The bootstrap addresses change when moving to CFK, so you must reissue the broker certificate with SANs covering the new CFK routes. Use the same PKI CA and key to issue the new certificate so that client truststores require no changes when you switch over.

The CFK external listener secret (client-tls) must use one of the secret formats that CFK supports. The following example uses the PEM standard format (tls.crt, tls.key, ca.crt). If you are using the PEM full chain format or JKS, use the equivalent fields for your chosen format. For the full list of supported formats, see CFK certificate model.

Extract the Client CA certificate from your PKI tooling, then run the following command to create the listener secret in PEM standard format:

kubectl create secret generic client-tls -n <cp-namespace> \
  --from-file=tls.crt=<broker-cert-file> \
  --from-file=tls.key=<broker-key-file> \
  --from-file=ca.crt=<client-ca-file>

Where:

• <cp-namespace> is the Kubernetes namespace where you are deploying Confluent Platform.
• <broker-cert-file> is the reissued PKI broker certificate file.
• <broker-key-file> is the corresponding private key file.
• <client-ca-file> is the Client CA certificate file extracted from your PKI tooling.

Reference this secret in the external listener secretRef on the Kafka custom resource. For the full listener configuration, see mTLS listener configuration.

Note: This secret is not automatically rotated. If the PKI broker certificate is renewed, you must recreate this secret with the updated certificate and key.

Next steps

If your cluster uses a multi-zone deployment, proceed to configuring rack awareness to set up zone labels and RBAC before deploying the cluster. Otherwise, proceed to setting up Confluent Platform.