Soluciona problemas de mTLS

En esta sección, se proporciona orientación para la solución de problemas comunes que se producen cuando se configura y se usa mTLS con Managed Service para Apache Kafka.

Errores al actualizar un clúster

Es posible que encuentres los siguientes errores cuando ejecutes un comando gcloud managed-kafka clusters update o gcloud managed-kafka clusters create.

La regla de asignación de principal de SSL no es válida

Recibes un mensaje de error similar a uno de los siguientes:

INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rule: \"RULE:INVALID-RULE\". The rule must be of the format DEFAULT or
RULE:pattern/replacement/[LU]
INVALID_ARGUMENT: The request was invalid: invalid SSL principal mapping
rules: \"RULE:\\nRULE:,DEFAULT\" contains a newline

Los mensajes de error se producen porque el valor proporcionado para la marca ssl-principal-mapping-rules tiene un formato incorrecto o contiene caracteres no válidos.

Corrige la regla para que coincida con el formato requerido y verifica que la cadena de la regla no contenga caracteres de nueva línea. Para obtener más información sobre la marca ssl-principal-mapping-rules, consulta Asignación de principales.

La configuración del grupo de CA no es válida

Recibes un mensaje de error similar a uno de los siguientes:

INVALID_ARGUMENT: The request was invalid:
ca_pool: project/managed-kafka-test/locations/us-central1/test-ca-pool
doesn't match the expected format: projects/{project}/locations/{location}/caPools/{caPool}
INVALID_ARGUMENT: The request was invalid: maximum of 10 CA pools can be specified
INVALID_ARGUMENT: The request was invalid: duplicate CA pool:
projects/managed-kafka-test/locations/us-central1/caPools/test-ca-pool.
All CA pools must be unique

Los mensajes de error se producen porque la lista de grupos de AC proporcionada para la marca mtls-ca-pools no es válida. Revisa la lista de grupos de AC y verifica lo siguiente:

  • Todos los nombres de grupos de CA usan el formato de recurso completo: projects/PROJECT_ID/locations/LOCATION/caPools/CA_POOL_ID.

  • No hay grupos de AC duplicados en la lista.

  • La cantidad total de grupos de AC no supera los 10.

El clúster no admite mTLS

Recibes un mensaje de error similar al siguiente:

FAILED_PRECONDITION: Invalid resource state for \"tls_config\": mTLS is not
supported for this cluster because it was created before the mTLS feature
was added. Please create a new cluster to use mTLS.

El mensaje de error se produce porque intentas habilitar mTLS en un clúster que se creó antes de que la función estuviera disponible. Como sugiere el mensaje de error, debes crear un clúster nuevo para usar mTLS. No puedes habilitar mTLS en un clúster existente que no sea apto y que se haya creado antes del 24 de junio de 2025.

Fallas de conexión del cliente

Si una aplicación cliente no puede conectarse al extremo de mTLS del clúster, verifica los siguientes problemas de configuración comunes:

  • Dirección de arranque incorrecta: Verifica que estés usando la dirección de arranque correcta. Debes usar la dirección de arranque de mTLS, que termina en 9192 y no en 9092.

  • Certificado de cliente no válido o incorrecto: Verifica que el certificado de cliente sea válido, no haya vencido y se haya emitido desde una CA que resida en uno de los grupos de CA configurados en el clúster.

  • Configuración incorrecta del almacén de claves del cliente: Confirma que la configuración de la aplicación cliente apunte correctamente a sus archivos de almacén de claves y almacén de confianza, y que las contraseñas sean correctas.

  • ACL de Kafka incorrectas: Verifica que hayas creado las ACL de Kafka necesarias para la entidad principal autenticada. Recuerda que la entidad principal es el nombre del sujeto del certificado (o el alias asignado), con el prefijo User:. Por ejemplo, si el nombre del sujeto es test-user, la entidad principal es User:test-user.

Errores en Cloud Logging

Es posible que aparezcan los siguientes errores en los registros del clúster, que puedes ver en Logging. Para obtener más información sobre el registro, consulta Visualiza registros con el Explorador de registros.

El tamaño del almacén de confianza supera el máximo

Verás una entrada de registro similar a la siguiente:

Trust store size X bytes exceeds the maximum allowed size of 1000 KiB
and cannot be updated.

El mensaje de error se produce porque el tamaño total de todos los certificados de la AC en los grupos de AC configurados es mayor que el límite de 1,000 KiB.

Revisa los certificados en tus grupos de CA para reducir el tamaño total. Esto podría implicar quitar certificados grandes o innecesarios, o bien optimizar las cadenas de CA.

No se pudieron recuperar los certificados del grupo de CA

Verás una entrada de registro similar a la siguiente:

Managed Service for Apache Kafka failed to fetch certificates from
CA pool <ca-pool-name>. Error: <error>.

El mensaje de error se produce cuando el agente de servicio de Managed Service para Apache Kafka no puede recuperar los certificados del grupo de CA especificado. La parte del mensaje que indica el error proporciona más detalles. Un motivo común de este error es la falta de permisos de IAM.

Verifica que el agente de servicio de Managed Service para Apache Kafka tenga el rol de lector de grupos de CA (roles/privateca.poolReader) en el proyecto que contiene el grupo de CA. Esto es especialmente importante en las configuraciones de varios proyectos. Para obtener más información sobre los permisos necesarios para configurar mTLS, consulta Roles y permisos necesarios.

Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.