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 asignación de nombres de recursos Google Cloud generales, consulta Nombres de recursos. La API del registro de esquemas de 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:

    • Dentro del 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):

    • Dentro del 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 asunto):

    • Dentro del 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, disponibles 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 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 del 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 se pueden usar letras en minúscula, 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 incluyen 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 +

ID de la LCA

El campo acl_id define el patrón de recursos al que se aplican las entradas de la LCA. Todas las entradas de la LCA se aplican al patrón de recursos codificado en el ID de la LCA.

acl_id debe estructurarse de una de las siguientes maneras:

  • Para las LCA en el clúster, usa este comando:

    • cluster

  • Para las LCA en un solo recurso dentro del clúster, haz lo siguiente:

    • topic/{RESOURCE_NAME}
    • consumerGroup/{RESOURCE_NAME}
    • transactionalId/{RESOURCE_NAME}

  • Para las LCA de todos los recursos que coinciden con un prefijo, haz lo siguiente:

    • topicPrefixed/{RESOURCE_NAME}
    • consumerGroupPrefixed/{RESOURCE_NAME}
    • transactionalIdPrefixed/{RESOURCE_NAME}

  • Para LCA en todos los recursos de un tipo determinado (comodín):

    • allTopics (representa a topic/*)
    • allConsumerGroups (representa a consumerGroup/*)
    • allTransactionalIds (representa a transactionalId/*)

{RESOURCE_NAME}: Es el nombre del recurso específico.

Ejemplos:

  • Para otorgar permisos sobre un tema específico my-topic, haz lo siguiente: topic/my-topic
  • Para otorgar permisos sobre todos los temas que comiencen con test-, haz lo siguiente: topicPrefixed/test-
  • Para otorgar permisos en el clúster, haz lo siguiente: cluster
  • Para otorgar permisos en cualquier grupo, haz lo siguiente: allConsumerGroups
  • Para otorgar permisos en un ID de transacción específico tx-id, haz lo siguiente: transactionalId/tx-id

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 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 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 configura como 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 incluye 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:

  • 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 incluye 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.

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

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 incluye una lista de las ventajas de usar TopicRecordNameStrategy:

  • Al igual que con 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.