CKafka supports configuring custom SSL certificates for instances that have SASL_SSL access enabled. After configuration, data transmission between clients and the CKafka Broker is TLS-encrypted using the specified certificates. If you choose mutual authentication, the client must also provide a client certificate issued by the specified CA to enhance access security.
This document describes how to set up, replace, and unbind custom SSL certificates in the CKafka console.
Prerequisites
Before configuring custom SSL certificates, check whether the instance meets the following requirements:
|
Instance Version | Serverful pro edition 2.4 and 2.8 version instances and Serverless instances support using SASL_SSL access points and configuring custom SSL Certificates. |
Instance State | The instance must be in normal operation, its state must be healthy, and it must not be undergoing configuration change tasks such as scale-out, scale-in, configuration upgrades, configuration downgrades, AZ changes, or version upgrades. |
Status | The SSL Certificates must have been issued or hosted in Tencent Cloud SSL Certificates service, and their status must be normal. |
Permission Requirements | The current account must have read permissions for the SSL Certificates service. For the first operation, you must complete the role authorization for CKafka to access the SSL Certificates service according to the prompts on the page. |
Access Mode | The instance must have or plan to have a SASL_SSL-type VPC access point or public network access point created. |
Client Preparation | The client must support TLS/SASL_SSL configuration. If mutual authentication is used, the client certificate, private key, and trust chain configuration must be prepared in advance. |
Domain Name Verification | CKafka custom certificates do not currently support certificate domain name verification based on the access domain name, so the client must disable hostname/domain verification. |
Attention:
For instances that had SSL certificates configured when purchased under the old version, their certificate configuration remains the old version. When you set up or replace a custom certificate for the first time, the system triggers a rolling restart of the Broker. After the rolling restart is complete, the instance is automatically upgraded to the new certificate configuration. It is recommended that you perform these operations during off-peak hours and ensure that the client has automatic reconnection capability.
If an instance meets the requirements for using custom SSL certificates but the console does not display the SSL certificate configuration entry, the underlying configuration of the instance may not have been upgraded. You can first perform a configuration upgrade that involves data migration. After the upgrade is complete, check whether the SSL certificate configuration entry is enabled.
For newly purchased instances, if you need to use custom certificates, it is recommended that you complete the certificate replacement as soon as possible after instance creation and then connect to the formal business traffic. This helps minimize the impact of certificate changes on business connections.
Risk Warnings
Setting up, replacing, or unbinding custom SSL certificates is an instance configuration change operation. Before performing the operation, note the following risks:
Connection Flash Break Risk
Setting up, replacing, or unbinding certificates may trigger a rolling restart of the Broker. During the rolling restart, client connections may experience brief interruptions. It is recommended that you perform certificate changes during off-peak hours and confirm in advance that the client is configured with the following capabilities:
Producers and consumers enable automatic reconnection.
Properly configure parameters such as retries, retry.backoff.ms, request.timeout.ms, and session.timeout.ms.
The consumer-side business logic has idempotency or duplicate consumption handling capabilities.
Producers configure the acks and retry policy according to business requirements.
Certificate Compatibility Risks
The client must trust the server certificate chain. In a two-way authentication scenario, the server also verifies the client certificate. If the client uses a fixed certificate, a fixed CA, certificate fingerprint verification, or a certificate pinning policy, certificate replacement may cause connection failures.
Before replacing a certificate, confirm the following:
The client truststore already contains the root CA or intermediate CA of the new certificate. If you use two-way authentication, ensure that the client certificate is issued by the CA configured on the server, and that the client certificate, private key, and password are correctly configured.
The truststore for the Java client has been updated.
The client has disabled domain name verification or hostname verification.
Authentication Method Description
|
One-way Authentication | Uses a custom server certificate for TLS encryption. The client verifies the server certificate, and the server does not verify the client certificate. | Scenarios that require the use of enterprise-owned certificates or a specified certificate chain. | Configure security.protocol=SASL_SSL, and configure the CA or the complete certificate chain corresponding to the server certificate in the client truststore. |
Two-Way Authentication | Uses a custom server certificate and configures a client CA certificate. The client verifies the server certificate, and the server verifies the client certificate. | Scenarios that require high-level terminal identity authentication, such as finance, government and enterprise, and cross-organizational data exchange. | Configure security.protocol=SASL_SSL, configure the server certificate chain in the client truststore, and configure the client certificate and private key. |
Default Certificate | Uses the default CKafka SSL certificates for TLS encrypted transmission and does not require binding a custom certificate. You can click the link to download the CKafka Default Certificate and complete the truststore or certificate trust configuration based on your client type. | Scenarios that require only encrypted transmission and do not mandate the use of enterprise-owned certificates. Attention: Using default certificates may not meet higher-level security and compliance requirements. To enhance instance access security, it is recommended that you replace them with your own certificates as soon as possible. | Configure security.protocol=SASL_SSL and trust the default CKafka SSL certificate chain. |
Pre-Change Security Check
Setting up, replacing, or unbinding custom SSL certificates is an instance configuration change operation. Before you submit the change, CKafka performs a security check on the instance to prevent data loss and unnecessary damage caused by a restart in a high-risk state. Common check items include, but are not limited to, the following:
|
Single Replica Check | If a single-replica Topic or partition exists in the instance, data availability will be affected during Broker restart, causing partial data loss, and the system will block this change. |
Unsynchronized Replica Check | If out-of-sync replicas exist in the instance, it indicates that replica data synchronization is not yet complete. Performing certificate setup, replacement, or unbinding operations under this condition may increase the risk of partition unavailability, message synchronization delay, or data inconsistency. The system may block this change. |
Instance Load Check | If the current load on the instance's CPU, memory, disk, network, connections, or requests is high, connection jitter may occur during the change, and the system may block this change. |
Broker Health Check | If conditions such as Broker exceptions, incomplete partition synchronization, or unhealthy ISR exist, the system may block the change. |
Task Conflict Check | If the instance is undergoing tasks such as scaling in or out, migration, upgrade, or route changes, wait for the current task to complete before proceeding. |
If the security check fails, it is recommended that you first complete risk remediation as prompted by the console, for example, by adding replicas, reducing business traffic, waiting for tasks to complete, or restoring the instance health status, and then retry.
Attention:
When certificates are configured via API, some APIs may provide a force_restart parameter to control whether to force the submission of changes. When security checks indicate risks, it is not recommended to directly enable forced execution. The forced parameter should be used only when you clearly understand the risks and have completed business-side disaster recovery and client reconnection preparations.
Setting a Custom Certificate
2. In the left sidebar, select Instance List. After selecting a region, click the ID of the target instance to go to the instance basic information page.
3. In the left sidebar, select SSL Management.
4. When you first go to the SSL Management page, you need to select the authorization for CKafka to download and apply SSL certificates. This authorization allows CKafka to read and load certificate content from the SSL Certificates service.
5. Initially, instances are bound to default certificates. Click the Set Custom Certificate button to go to the configuration pop-up window. CKafka supports switching between different authentication methods. Switching authentication methods triggers a rolling restart of the Broker. During the restart, connection interruptions may occur. It is recommended that you perform this operation during off-peak hours and ensure that the client has automatic reconnection capability.
6. After the pre-change security check for the cluster passes, complete the relevant configurations based on business requirements.
Attention:
If you choose two-way authentication, ensure that the server certificate matches the CA certificate and that the client certificate is issued by that CA. Otherwise, the client may fail the TLS handshake, resulting in connection failure.
7. After confirming that the configuration is correct, click Submit.
8. After submission, the instance will enter the configuration change in progress state. You can observe the instance status on the instance details page and wait for the task to complete. During this period, you cannot perform operations such as configuration changes.
9. After the certificate is successfully bound, you can refresh the page to update the certificate status. The binding status will then be changed to Bound.
10. After completing the custom SSL certificate setup, update the SASL_SSL configuration for producers and consumers according to the client configuration guide. Observe the instance connection quantity, production and consumption traffic, error logs, and client SSL handshake logs. Use the producer and consumer clients to verify whether messages are sent and received normally, and confirm that business operations have restored normal operation.
Unbinding a Certificate
If you no longer need to use a custom SSL certificate, you can unbind the current certificate on the SSL Management page. After the custom certificate is unbound, the instance will revert to using the default CKafka SSL certificate. The unbinding operation also triggers a certificate configuration change. For instances with certain editions or older certificate configuration templates, this may trigger a rolling restart of the Broker.
2. In the left sidebar, select Instance List. After selecting a region, click the ID of the target instance to go to the instance basic information page.
3. In the left sidebar, select SSL Management.
4. In the certificate list, locate the currently bound certificate. In the Operation column, click Unbind.
5. After reading the risk warning, confirm the unbinding. In two-way authentication, unbinding any certificate will also unbind the CA certificate and the server certificate. If the client trusts only the original custom certificate or its CA chain, it may fail to connect to the instance after the unbinding is performed. In production environments, it is not recommended to perform unbinding operations during peak business hours.
6. After confirming that the configuration is correct, click Submit and wait for the unbinding task to complete.
Operation Suggestion
To minimize the impact of certificate changes on your business, it is recommended that you follow the procedure below:
1. Ensure that the certificate has been issued or hosted in the SSL Certificate service and is in a normal state. Before replacing the certificate, add the CA chain corresponding to the new certificate to the client truststore to ensure that the client is compatible with both the old and new certificates.
2. Perform certificate setup, replacement, or unbinding operations during off-peak hours to minimize the impact of connection interruptions on your business. Also, confirm that producers and consumers are configured with automatic reconnection, retry, timeout, and consumption fault tolerance logic.
3. If the console indicates risks such as single replica, high load, or unhealthy instance, please complete the remediation first and then perform the change.
4. It is recommended that you allocate sufficient time before the certificate expires to complete certificate replacement and client verification, thereby avoiding connection failures caused by certificate expiration.