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

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

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

  • Clúster

  • Tema

  • Grupo de consumidores

  • LCA

  • Registro de esquemas

  • Contexto (dentro de un registro de esquemas)

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

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

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

Para obtener más información sobre la denominación de recursos Google Cloud generales, consulta Nombres de recursos. La API del registro de esquemas para Managed Service para Apache Kafka se diseñó para que sea compatible con una API de código abierto existente, por lo que algunas convenciones de nomenclatura pueden diferir de los estándares típicos de las APIs.

Formato de asignación de nombres de recursos

A continuación, se indican los formatos de 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:

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

  • Esquema (identificado por ID):

    • En el contexto predeterminado: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • En 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 tema):

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

En las siguientes secciones, se incluye un desglose de cada componente.

ID del proyecto

El valor debe ser el ID o el número del proyecto, disponible en la consola de Google Cloud . 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 admitidas de Managed Service para Apache Kafka. Para ver la lista de ubicaciones disponibles, consulta las ubicaciones de Managed Service para Apache Kafka.

ID

ID es el segmento final de 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:

    • Los IDs de clúster deben tener entre 3 y 255 caracteres.

    • IDs de temas y grupos de consumidores: Cualquier longitud permitida por Apache Kafka. Los nombres de los temas de Apache Kafka tienen un límite de 249 caracteres.

    • ID del registro de esquema: Contiene hasta 255 caracteres.

    • ID de contexto: Contiene hasta 255 caracteres.

    • ID de sujeto: 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 que solo se pueden usar letras minúsculas, números y guiones. Debe comenzar con una letra y no puede terminar con un guion.

    • IDs de temas y grupos 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 del registro de esquema: 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 más +.

    • ID del 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 indican en la sección anterior en los IDs de recursos sin codificación de URL. Sin embargo, debes asegurarte de que los demás caracteres especiales estén codificados o decodificados de forma correcta cuando se usen en las URLs.

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

Si haces referencia a un tema de las bibliotecas cliente de Kafka, no se usa la ruta de acceso completa al recurso. Solo se usa el nombre del tema. Del mismo modo, cuando interactúas con esquemas usando integraciones de clientes de Kafka, como serializadores o deserializadores, sueles usar el nombre del tema en lugar de la ruta de acceso completa al 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 los serializadores y deserializadores, el nombre del tema es fundamental. La estrategia de asignación de nombres de temas 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.

Puedes configurar la estrategia de asignación de nombres de temas estableciendo la propiedad key.subject.name.strategy o value.subject.name.strategy en la configuración de tu 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 los valores del mensaje: orders-value
  • Asunto para las claves de mensajes: orders-key

A continuación, se muestra una lista de las ventajas de usar TopicNameStrategy:

  • Es una estrategia sencilla, por lo que se adapta bien a 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.

A continuación, se incluye una lista de las desventajas de usar TopicNameStrategy:

  • En realidad, cada tema solo puede controlar un tipo de mensaje basado 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 nombre del tema.

Estos son algunos ejemplos:

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

A continuación, se muestra una lista de las ventajas de usar RecordNameStrategy:

  • Dado que el nombre del asunto no está vinculado al tema, puedes enviar diferentes tipos de registros al mismo tema de Kafka. Esto es posible siempre y cuando 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 tema.

A continuación, se incluye una lista de las desventajas de usar RecordNameStrategy:

  • Debes usar el mismo asunto y la misma versión para todos los temas que usen 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

A continuación, se muestra una lista de las ventajas de usar TopicRecordNameStrategy:

  • De forma 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 a another-topic-com.example.project.MyRecord.

A continuación, se incluye una lista de las desventajas de usar TopicRecordNameStrategy:

  • Los nombres de los temas pueden ser 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 en Estados Unidos y otros países.