Lineamientos para asignarles nombres a los recursos de Google Cloud Managed Service para Apache Kafka

Un Google Cloud recurso es cualquier componente que creas o usas dentro de el Google Cloud. Estos recursos forman los componentes básicos de tus aplicaciones y sistemas que se ejecutan en la plataforma.

Los recursos de Managed Service para Apache Kafka incluyen lo siguiente:

  • Clúster

  • Tema

  • Grupo de consumidores

  • ACL

  • Registro de esquemas

  • Contexto (dentro de un registro de esquemas)

  • Asunto (dentro de un registro de esquemas o contexto)

  • Versión (versiones de un esquema en un asunto)

  • Esquema (identificado por ID, asociado con uno o varios asuntos y versiones)

Para obtener más información sobre la asignación de nombres de recursos generales Google Cloud , consulta Nombres de recursos. La API de registro de esquemas para Managed Service para Apache Kafka se diseñó para la compatibilidad con una API de código abierto existente, por lo que algunas convenciones de nombres podrían diferir de los estándares típicos de la API.

Formato de asignación de nombres de recursos

Estos son los formatos para los diferentes recursos:

  • Clúster: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

  • Tema: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}

  • Grupo de consumidores: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}

  • LCA: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}

  • Registro de esquemas: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

  • Contexto: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}

  • Asunto:

    • Dentro del contexto predeterminado: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
    • Dentro de un contexto específico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

  • Esquema (identificado por ID):

    • Dentro del contexto predeterminado: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • Dentro de un contexto específico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

  • Versión (identificada por el número de versión en un asunto):

    • Dentro del contexto predeterminado: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
    • Dentro de un contexto específico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

A continuación, se incluye un desglose de cada componente en las siguientes secciones.

ID del proyecto

El valor debe ser el ID del proyecto o el número del proyecto, disponible en la Google Cloud consola. Por ejemplo, my-cool-project es un ID del proyecto, mientras que 123456789123 es un número del proyecto.

Ubicación

El valor debe ser una de las ubicaciones compatibles de Managed Service para Apache Kafka. Para ver la lista de ubicaciones disponibles, consulta Ubicaciones de Managed Service para Apache Kafka.

ID

ID es el segmento final en la ruta del recurso. Las variables como {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID} y {SUBJECT_ID} deben cumplir con los siguientes lineamientos:

  • No comenzar con la cadena goog

  • Comenzar con una letra

  • Restricciones de longitud:

    • IDs de clúster: Contienen entre 3 y 53 caracteres.

    • IDs de tema y grupo de consumidores: Cualquier longitud permitida por Apache Kafka. Los nombres de temas de Apache Kafka están limitados a 249 caracteres.

    • ID de registro de esquemas: Contiene hasta 255 caracteres.

    • ID de contexto: Contiene hasta 255 caracteres.

    • ID de asunto: Contiene hasta 255 bytes UTF-8.

  • Restricciones de caracteres:

    • IDs de clúster: Deben coincidir con la regex ^[a-z]([-a-z0-9]*[a-z0-9])?. Esto significa letras minúsculas, números y guiones. Debe comenzar con una letra y no puede terminar en un guion.

    • IDs de tema y grupo de consumidores: Kafka realiza la validación. Los caracteres permitidos son `[a-zA-Z0-9.-], que incluye caracteres alfanuméricos ASCII, puntos (.), guiones bajos () y guiones (-).

    • ID de registro de esquemas: Letras (mayúsculas o minúsculas), números y guiones bajos _.

    • ID de contexto: Letras (mayúsculas o minúsculas), números y los siguientes caracteres especiales: guiones -, puntos ., guiones bajos _, virgulillas ~, porcentajes % o signos de suma +.

    • ID de asunto: Letras (mayúsculas o minúsculas), números y los siguientes caracteres especiales: guiones -, puntos ., guiones bajos _, virgulillas ~, porcentajes % o signos de suma +.

Caracteres especiales

Puedes usar los caracteres especiales que se enumeran en la sección anterior en los IDs de recursos sin codificación de URL. Sin embargo, debes asegurarte de que cualquier otro carácter especial esté codificado o decodificado de forma correcta cuando se use en URLs.

Por ejemplo, mi-tópico es un ID no válido si ó no es un carácter permitido para ese tipo de ID de recurso específico. Sin embargo, mi-topico sería válido si solo se permiten letras latinas básicas. Este formato es importante cuando se realizan llamadas de REST.

Si haces referencia a un tema desde las bibliotecas cliente de Kafka, no se usa la ruta de acceso completa del recurso. Solo se usa el nombre del tema. Del mismo modo, cuando interactúas con esquemas mediante integraciones de clientes de Kafka, como serializadores o deserializadores, por lo general, usas el nombre del asunto en lugar de la ruta de acceso completa del recurso.

Estrategias de asignación de nombres de asuntos

Cuando se trabaja con el registro de esquemas, en especial con las integraciones de clientes de Kafka, como serializadores y deserializadores, el nombre del asunto es fundamental. La estrategia de asignación de nombres de asuntos determina cómo se registra y recupera un esquema del registro de esquemas. Las diferentes estrategias ofrecen distintos niveles de flexibilidad y control sobre la evolución del esquema.

Para configurar la estrategia de asignación de nombres de asuntos, establece la propiedad key.subject.name.strategy o value.subject.name.strategy en la configuración del cliente de Kafka.

TopicNameStrategy

Esta es la estrategia predeterminada para las bibliotecas cliente de Kafka de código abierto.

El nombre del asunto se deriva directamente del nombre del tema de Kafka, al que se le agrega key para las claves de mensajes o value para los valores de mensajes. Si auto.register.schema se establece en true, los clientes productores usan topicName-value o topicName-key para un tema llamado topicName.

Estos son algunos ejemplos:

  • Nombre del tema: orders
  • Asunto para valores de mensajes: orders-value
  • Asunto para claves de mensajes: orders-key

La siguiente es una lista de ventajas de usar TopicNameStrategy:

  • Es una estrategia sencilla, lo que la hace adecuada para muchos casos de uso.

  • Los esquemas están vinculados directamente a un tema, lo que te permite desarrollar los tipos de registros dentro de un solo tema de forma independiente.

La siguiente es una lista de desventajas de usar TopicNameStrategy:

  • Cada tema solo puede controlar de manera efectiva un tipo de mensaje que se basa en el esquema de valores. Esto se debe a que el nombre del asunto está fijo al nombre del tema. Si necesitas enviar diferentes tipos de registros al mismo tema, esta estrategia no funcionará.

RecordNameStrategy

Esta estrategia usa el nombre de clase completamente calificado del registro de Avro o Protobuf como el nombre del asunto.

Estos son algunos ejemplos:

  • Nombre del esquema de Avro: com.example.data.Customer
  • Nombre del mensaje de Protobuf: com.example.data.Order
  • Asunto para el esquema customer: com.example.data.Customer
  • Asunto para el esquema order: com.example.data.Order

La siguiente es una lista de ventajas de usar RecordNameStrategy:

  • Como el nombre del asunto no está vinculado al tema, puedes enviar diferentes tipos de registros al mismo tema de Kafka. Esto es posible siempre que cada tipo de registro tenga su propio nombre completamente calificado único y el esquema correspondiente registrado.

  • Se puede usar un esquema para un tipo de registro específico, como com.example.common.Address, en varios temas, y su evolución se administra de forma centralizada en un solo asunto.

La siguiente es una lista de desventajas de usar RecordNameStrategy:

  • Debes usar el mismo asunto y la misma versión para todos los temas que usan un tipo de registro en particular. Esto puede ser restrictivo si necesitas diferentes versiones del mismo tipo de registro en diferentes temas.

TopicRecordNameStrategy

Esta estrategia combina aspectos de TopicNameStrategy y RecordNameStrategy.

El nombre del asunto es una combinación del nombre del tema de Kafka y el nombre de clase completamente calificado del registro, con el formato TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

Estos son algunos ejemplos:

  • Tema: user-events

  • Nombre completamente calificado: com.example.events.PageView

  • Nombre del asunto para esta combinación: user-events-com.example.events.PageView

  • Otro tema: product-interactions

  • Nombre completamente calificado: com.example.events.PageView

  • Nombre del asunto para esta combinación: product-interactions-com.example.events.PageView

La siguiente es una lista de ventajas de usar TopicRecordNameStrategy:

  • De manera similar a RecordNameStrategy, puedes enviar diferentes tipos de registros al mismo tema.

  • A diferencia de RecordNameStrategy, esta estrategia te permite desarrollar el esquema para un tipo de registro específico de forma independiente dentro de cada tema. Esto significa que my-topic-com.example.project.MyRecord puede evolucionar de manera diferente que another-topic-com.example.project.MyRecord.

La siguiente es una lista de desventajas de usar TopicRecordNameStrategy:

  • Los nombres de los asuntos pueden volverse bastante largos debido a la combinación del nombre del tema y el nombre del registro completamente calificado.
Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados de Estados Unidos y otros países.