Google Cloud Managed Service for Apache Kafka リソースの命名ガイドライン

Google Cloud リソースは、 Google Cloud内で作成または使用するコンポーネントです。これらのリソースは、プラットフォームで実行されるアプリケーションとシステムの構成要素となります。

Managed Service for Apache Kafka のリソースには、次のものがあります。

  • クラスタ

  • トピック

  • コンシューマー グループ

  • ACL

  • スキーマ レジストリ

  • コンテキスト（スキーマ レジストリ内）

  • サブジェクト（スキーマ レジストリまたはコンテキスト内）

  • バージョン（サブジェクトのスキーマのバージョン）

  • スキーマ（ID で識別され、1 つまたは複数のサブジェクトとバージョンに関連付けられている）

一般的な Google Cloud リソースの命名について詳しくは、リソース名をご覧ください。Managed Service for Apache Kafka のスキーマ レジストリ API は、既存のオープンソース API との互換性を考慮して設計されているため、一部の命名規則が一般的な API 標準と異なる場合があります。

リソース名の形式

さまざまなリソースの形式は次のとおりです。

  • クラスタ: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

  • トピック: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}

  • コンシューマー グループ: 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}

  • スキーマ レジストリ: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

  • コンテキスト: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}

  • 件名:

    • デフォルトのコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
    • 特定のコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

  • スキーマ（ID で識別）:

    • デフォルトのコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • 特定のコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

  • バージョン（件名のバージョン番号で識別）:

    • デフォルトのコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
    • 特定のコンテキスト内: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

以降のセクションでは、各コンポーネントについて詳しく説明します。

プロジェクト ID

値は、 Google Cloud コンソールから取得可能なプロジェクト ID またはプロジェクト番号にする必要があります。たとえば、my-cool-project はプロジェクト ID で、123456789123 はプロジェクト番号です。

場所

値は、サポートされている Managed Service for Apache Kafka のロケーションのいずれかにする必要があります。使用可能なロケーションのリストについては、Managed Service for Apache Kafka のロケーションをご覧ください。

ID

ID は、リソースパスの最後のセグメントです。{CLUSTER_ID}、{TOPIC_ID}、{CONSUMER_GROUP_ID}、{SCHEMA_REGISTRY_ID}、{CONTEXT_ID}、{SUBJECT_ID} などの変数は、次のガイドラインに準拠する必要があります。

  • 文字列 goog で始めないこと。

  • 先頭には英字を使用してください

  • 長さの制約:

    • クラスタ ID: 3 ～ 255 文字の長さであること。

    • トピック、コンシューマー グループ ID: Apache Kafka で許可されている任意の長さ。Apache Kafka トピック名は 249 文字に制限されています。

    • スキーマ レジストリ ID: 最大 255 文字。

    • コンテキスト ID: 255 文字以内。

    • サブジェクト ID: 最大 255 UTF-8 バイト。

  • 文字の制約:

    • クラスタ ID: 正規表現 ^[a-z]([-a-z0-9]*[a-z0-9])? に一致する必要があります。つまり、小文字、数字、ハイフンを使用できます。先頭は英小文字にする必要があります。末尾をハイフンにすることはできません。

    • トピック、コンシューマー グループ ID: 検証は Kafka によって行われます。使用できる文字は `[a-zA-Z0-9.-]` で、ASCII 英数字、ピリオド（.）、アンダースコア（）、ダッシュ（-）が含まれます。

    • スキーマ レジストリ ID: 文字（大文字または小文字）、数字、アンダースコア _。

    • コンテキスト ID: 文字（大文字または小文字）、数字、特殊文字（ダッシュ -、ピリオド .、アンダースコア _、チルダ ~、パーセント %、プラス記号 +）。

    • サブジェクト ID: 英字（大文字または小文字）、数字、特殊文字（ダッシュ -、ピリオド .、アンダースコア _、チルダ ~、パーセント %、プラス記号 +）。

ACL ID

acl_id は、ACL エントリが適用されるリソース パターンを定義します。ACL のすべての ACL エントリは、ACL ID でエンコードされたリソース パターンに適用されます。

acl_id は、次のいずれかの構造にする必要があります。

  • クラスタの ACL の場合:

    • cluster

  • クラスタ内の単一リソースの ACL の場合:

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

  • プレフィックスに一致するすべてのリソースの ACL の場合:

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

  • 特定タイプ（ワイルドカード）のすべてのリソースの ACL の場合:

    • allTopics（topic/* を表す）
    • allConsumerGroups（consumerGroup/* を表す）
    • allTransactionalIds（transactionalId/* を表す）

{RESOURCE_NAME}: 特定のリソースの名前。

例:

  • 特定のトピック my-topic に対する権限を付与するには: topic/my-topic
  • test- で始まるすべてのトピックに対する権限を付与するには: topicPrefixed/test-
  • クラスタ自体に権限を付与するには: cluster
  • 任意のグループに権限を付与するには: allConsumerGroups
  • 特定のトランザクション ID tx-id に対する権限を付与するには: transactionalId/tx-id

特殊文字

前のセクションに記載されている特殊文字は、URL エンコードなしでリソース ID に使用できます。ただし、URL で使用する場合、その他すべての特殊文字が適切にエンコードまたはデコードされることを確認する必要があります。

たとえば、ó が特定のリソース ID タイプの許可された文字でない場合、mi-tópico は無効な ID です。ただし、基本ラテン文字のみが許可されている場合は、mi-topico は有効になります。この形式は、REST 呼び出しを行う場合に重要です。

Kafka クライアント ライブラリからトピックを参照している場合、完全なリソースパスは使用されません。トピック名自体のみが使用されます。同様に、シリアライザーやデシリアライザーなどの Kafka クライアント統合を使用してスキーマを操作する場合は、通常、完全なリソースパスではなくサブジェクト名を使用します。

サブジェクトの命名戦略

スキーマ レジストリ、特にシリアライザーやデシリアライザーなどの Kafka クライアント統合を使用する場合は、サブジェクト名が重要になります。サブジェクト命名戦略は、スキーマ レジストリからスキーマを登録して取得する方法を決定します。戦略によって、スキーマの進化に対する柔軟性と制御のレベルが異なります。

サブジェクト命名戦略は、Kafka クライアント構成で key.subject.name.strategy プロパティまたは value.subject.name.strategy プロパティを設定することで構成できます。

TopicNameStrategy

これは、オープンソースの Kafka クライアント ライブラリのデフォルトの戦略です。

サブジェクト名は Kafka トピック名から直接派生し、メッセージキーの場合は key、メッセージ値の場合は value が付加されます。auto.register.schema が true に設定されている場合、プロデューサー クライアントは topicName という名前のトピックに topicName-value または topicName-key を使用します。

次に例を示します。

  • トピック名: orders
  • メッセージ値のサブジェクト: orders-value
  • メッセージキーの件名: orders-key

TopicNameStrategy を使用するメリットは次のとおりです。

  • これはシンプルな戦略であり、多くのユースケースに適しています。

  • スキーマはトピックに直接関連付けられているため、単一のトピック内のレコード タイプを個別に進化させることができます。

TopicNameStrategy を使用するデメリットは次のとおりです。

  • 各トピックは、値スキーマに基づく 1 種類のメッセージのみを効果的に処理できます。これは、サブジェクト名がトピック名に固定されているためです。同じトピックに異なるタイプのレコードを送信する必要がある場合、この戦略は機能しません。

RecordNameStrategy

この戦略では、Avro または Protobuf レコードの完全修飾クラス名がサブジェクト名として使用されます。

次に例を示します。

  • Avro スキーマ名: com.example.data.Customer
  • Protobuf メッセージ名: com.example.data.Order
  • customer スキーマのサブジェクト: com.example.data.Customer
  • order スキーマのサブジェクト: com.example.data.Order

RecordNameStrategy を使用するメリットは次のとおりです。

  • サブジェクト名がトピックに関連付けられていないため、同じ Kafka トピックに異なるタイプのレコードを送信できます。各レコードタイプに独自の完全修飾名と、対応するスキーマが登録されている限り、これは可能です。

  • com.example.common.Address などの特定のレコード タイプのスキーマは複数のトピックで使用でき、その進化は単一のサブジェクトで一元的に管理されます。

RecordNameStrategy を使用するデメリットは次のとおりです。

  • 特定のレコードタイプを使用するすべてのトピックで、同じサブジェクトとバージョンを使用する必要があります。異なるトピックで同じレコード タイプの異なるバージョンが必要な場合は、この制限が厳しくなる可能性があります。

TopicRecordNameStrategy

この戦略は、TopicNameStrategy と RecordNameStrategy の両方の側面を組み合わせたものです。

サブジェクト名は、Kafka トピック名とレコードの完全修飾クラス名を組み合わせたもので、TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME の形式で指定します。

次に例を示します。

  • トピック: user-events

  • 完全修飾名: com.example.events.PageView

  • この組み合わせのサブジェクト名: user-events-com.example.events.PageView

  • 別のトピック: product-interactions

  • 完全修飾名: com.example.events.PageView

  • この組み合わせのサブジェクト名: product-interactions-com.example.events.PageView

TopicRecordNameStrategy を使用するメリットは次のとおりです。

  • RecordNameStrategy と同様に、同じトピックにさまざまなタイプのレコードを送信できます。

  • RecordNameStrategy とは異なり、この戦略では、各トピック内で特定のレコード タイプのスキーマを個別に進化させることができます。つまり、my-topic-com.example.project.MyRecord は another-topic-com.example.project.MyRecord とは異なる方法で進化する可能性があります。

TopicRecordNameStrategy を使用するデメリットは次のとおりです。

  • トピック名と完全修飾レコード名の組み合わせにより、サブジェクト名が長くなることがあります。
Apache Kafka® は、Apache Software Foundation または米国その他の諸国における関連会社の商標です。