Linee guida per assegnare un nome a una risorsa Google Cloud Managed Service per Apache Kafka

Una risorsa Google Cloud è qualsiasi componente che crei o utilizzi all'interno di Google Cloud. Queste risorse costituiscono i blocchi di base delle tue applicazioni e dei tuoi sistemi in esecuzione sulla piattaforma.

Le risorse in Managed Service per Apache Kafka includono quanto segue:

  • Cluster

  • Argomento

  • Gruppo di consumer

  • ACL

  • Registro di schema

  • Contesto (all'interno di un registro di schema)

  • Soggetto (all'interno di un registro di schema o contesto)

  • Versione (versioni di uno schema in un argomento)

  • Schema (identificato dall'ID, associato a uno o più soggetti e versioni)

Per saperne di più sulla denominazione delle risorse Google Cloud generali, vedi Nomi delle risorse. L'API Schema Registry per Managed Service per Apache Kafka è stata progettata per essere compatibile con un'API open source esistente, quindi alcune convenzioni di denominazione potrebbero differire dagli standard API tipici.

Formato di denominazione delle risorse

Ecco i formati per le diverse risorse:

  • Cluster: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

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

  • Gruppo di consumatori: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}

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

  • Registro di schema: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

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

  • Oggetto:

    • Nel contesto predefinito: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
    • In un contesto specifico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

  • Schema (identificato dall'ID):

    • Nel contesto predefinito: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • In un contesto specifico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

  • Versione (identificata dal numero di versione sotto un argomento):

    • Nel contesto predefinito: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
    • In un contesto specifico: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

Nelle sezioni successive viene fornita un'analisi dettagliata di ogni componente.

ID progetto

Il valore deve essere l'ID o il numero del progetto, disponibile nella console Google Cloud . Ad esempio, my-cool-project è un ID progetto, mentre 123456789123 è un numero di progetto.

Località

Il valore deve essere una delle località di Managed Service per Apache Kafka supportate. Per un elenco di località disponibili, consulta le località di Managed Service per Apache Kafka.

ID

ID è l'ultimo segmento del percorso della risorsa. Le variabili come {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID} e {SUBJECT_ID} devono rispettare le seguenti linee guida:

  • Non iniziare con la stringa goog

  • Inizia con una lettera

  • Vincoli di lunghezza:

    • ID cluster: contengono da 3 a 255 caratteri.

    • ID argomento, gruppo di consumatori: qualsiasi lunghezza consentita da Apache Kafka. I nomi degli argomenti Apache Kafka non possono superare 249 caratteri.

    • ID registro schema: contiene fino a 255 caratteri.

    • ID contesto: contiene fino a 255 caratteri.

    • ID soggetto: contiene fino a 255 byte UTF-8.

  • Vincoli di caratteri:

    • ID cluster: devono corrispondere all'espressione regolare ^[a-z]([-a-z0-9]*[a-z0-9])?. ovvero lettere minuscole, numeri e trattini. Deve iniziare con una lettera e non può terminare con un trattino.

    • ID argomento e gruppo di consumer: la convalida viene eseguita da Kafka. I caratteri consentiti sono `[a-zA-Z0-9.-], che include caratteri alfanumerici ASCII, punti (.), trattini bassi () e trattini (-).

    • ID registro di schema: lettere (maiuscole o minuscole), numeri e trattini bassi _.

    • ID contesto: lettere (maiuscole o minuscole), numeri e i seguenti caratteri speciali: trattini -, punti ., trattini bassi _, tildi ~, percentuali % o segni più +.

    • ID soggetto: lettere (maiuscole o minuscole), numeri e i seguenti caratteri speciali: trattini -, punti ., trattini bassi _, tildi ~, percentuali % o segni più +.

ID ACL

Il campo acl_id definisce il pattern di risorsa a cui si applicano le voci ACL. Tutte le voci ACL nell'ACL si applicano al pattern di risorse codificato nell'ID ACL.

acl_id deve essere strutturato come uno dei seguenti:

  • Per gli ACL sul cluster:

    • cluster

  • Per gli ACL su una singola risorsa all'interno del cluster:

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

  • Per gli ACL su tutte le risorse che corrispondono a un prefisso:

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

  • Per gli ACL su tutte le risorse di un determinato tipo (jolly):

    • allTopics (rappresenta topic/*)
    • allConsumerGroups (rappresenta consumerGroup/*)
    • allTransactionalIds (rappresenta transactionalId/*)

{RESOURCE_NAME}: il nome della risorsa specifica.

Esempi:

  • Per concedere le autorizzazioni su un argomento specifico my-topic: topic/my-topic
  • Per concedere le autorizzazioni per tutti gli argomenti che iniziano con test-: topicPrefixed/test-
  • Per concedere le autorizzazioni sul cluster stesso: cluster
  • Per concedere le autorizzazioni per qualsiasi gruppo: allConsumerGroups
  • Per concedere le autorizzazioni per un ID transazionale specifico tx-id: transactionalId/tx-id

Caratteri speciali

Puoi utilizzare i caratteri speciali elencati nella sezione precedente negli ID risorsa senza codifica URL. Tuttavia, devi assicurarti che qualsiasi altro carattere speciale sia codificato o decodificato correttamente quando viene utilizzato negli URL.

Ad esempio, mi-tópico è un ID non valido se ó non è un carattere consentito per quel tipo specifico di ID risorsa. Tuttavia, mi-topico sarebbe valido se fossero consentite solo le lettere latine di base. Questo formato è importante quando effettui chiamate REST.

Se fai riferimento a un argomento dalle librerie client Kafka, il percorso completo della risorsa non viene utilizzato. Viene utilizzato solo il nome dell'argomento. Allo stesso modo, quando interagisci con gli schemi utilizzando integrazioni client Kafka come serializzatori o deserializzatori, in genere utilizzi il nome del soggetto anziché il percorso completo della risorsa.

Strategie di denominazione dei soggetti

Quando lavori con il registro di schema, in particolare con le integrazioni del client Kafka come i serializzatori e i deserializzatori, il nome del soggetto è fondamentale. La strategia di denominazione dell'argomento determina come uno schema viene registrato e recuperato dal registro degli schemi. Le diverse strategie offrono vari livelli di flessibilità e controllo sull'evoluzione dello schema.

Puoi configurare la strategia di denominazione dell'argomento impostando la proprietà key.subject.name.strategy o value.subject.name.strategy nella configurazione del client Kafka.

TopicNameStrategy

Questa è la strategia predefinita per le librerie client Kafka open source.

Il nome del soggetto deriva direttamente dal nome dell'argomento Kafka, a cui viene aggiunto key per le chiavi dei messaggi o value per i valori dei messaggi. Se auto.register.schema è impostato su true, i client produttori utilizzano topicName-value o topicName-key per un argomento denominato topicName.

Ecco alcuni esempi:

  • Nome argomento: orders
  • Oggetto per i valori del messaggio: orders-value
  • Oggetto per le chiavi dei messaggi: orders-key

Di seguito è riportato un elenco di vantaggi dell'utilizzo di TopicNameStrategy:

  • Si tratta di una strategia semplice, adatta a molti casi d'uso.

  • Gli schemi sono collegati direttamente a un argomento, il che ti consente di evolvere i tipi di record all'interno di un singolo argomento in modo indipendente.

Di seguito è riportato un elenco di svantaggi dell'utilizzo di TopicNameStrategy:

  • Ogni argomento può gestire in modo efficace un solo tipo di messaggio in base allo schema dei valori. Questo perché il nome del soggetto è fisso rispetto al nome dell'argomento. Se devi inviare diversi tipi di record allo stesso argomento, questa strategia non funzionerà.

RecordNameStrategy

Questa strategia utilizza il nome di classe completo del record Avro o Protobuf come nome del soggetto.

Ecco alcuni esempi:

  • Nome schema Avro: com.example.data.Customer
  • Nome del messaggio Protobuf: com.example.data.Order
  • Oggetto per lo schema customer: com.example.data.Customer
  • Oggetto per lo schema order: com.example.data.Order

Di seguito è riportato un elenco di vantaggi dell'utilizzo di RecordNameStrategy:

  • Poiché il nome del soggetto non è collegato all'argomento, puoi inviare diversi tipi di record allo stesso argomento Kafka. Ciò è possibile a condizione che ogni tipo di record abbia il proprio nome completo univoco e lo schema corrispondente registrato.

  • Uno schema per un tipo di record specifico, ad esempio com.example.common.Address, può essere utilizzato in più argomenti e la sua evoluzione viene gestita centralmente in un unico argomento.

Di seguito è riportato un elenco di svantaggi dell'utilizzo di RecordNameStrategy:

  • Devi utilizzare lo stesso oggetto e la stessa versione per tutti gli argomenti che utilizzano un particolare tipo di record. Questo può essere restrittivo se hai bisogno di versioni diverse dello stesso tipo di record in argomenti diversi.

TopicRecordNameStrategy

Questa strategia combina aspetti di TopicNameStrategy e RecordNameStrategy.

Il nome del soggetto è una combinazione del nome dell'argomento Kafka e del nome completo della classe del record, formattato come TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

Ecco alcuni esempi:

  • Argomento: user-events

  • Nome completo: com.example.events.PageView

  • Nome del soggetto per questa combinazione: user-events-com.example.events.PageView

  • Un altro argomento: product-interactions

  • Nome completo: com.example.events.PageView

  • Nome del soggetto per questa combinazione: product-interactions-com.example.events.PageView

Di seguito è riportato un elenco di vantaggi dell'utilizzo di TopicRecordNameStrategy:

  • Come per RecordNameStrategy, puoi inviare diversi tipi di record allo stesso argomento.

  • A differenza di RecordNameStrategy, questa strategia ti consente di evolvere lo schema per un tipo di record specifico in modo indipendente all'interno di ogni argomento. Ciò significa che my-topic-com.example.project.MyRecord può evolvere in modo diverso rispetto a another-topic-com.example.project.MyRecord.

Di seguito è riportato un elenco di svantaggi dell'utilizzo di TopicRecordNameStrategy:

  • I nomi dei soggetti possono diventare piuttosto lunghi a causa della combinazione del nome dell'argomento e del nome completo del record.
Apache Kafka® è un marchio registrato di Apache Software Foundation o delle sue affiliate negli Stati Uniti e/o in altri paesi.