Kafkaトピック命名規則: 運用しやすいネーミング実務と試験対策

トピック名は変更不可で長期に残り続けます。最初の設計が運用コストと信頼性を左右します。

本稿はKafka/Confluentの安定仕様に基づき、検索性・権限設計・監査対応を意識した命名パターンを提示します。資格試験（CCDAK / CCAAK）で問われやすい公式制約も併せて確認します。

なぜトピック命名が運用を左右するか

命名は運用の入口です。良い命名は、監査ログやメトリクスの集約、ACL/RBACのプレフィックス設計、インシデント時の探索効率を高めます。逆に場当たり的な命名は、権限の破綻・重複トピック・誤配信の温床になります。

CCDAK/CCAAKでは、公式の命名制約（許容文字や大文字小文字の扱い、名前変更不可）や、スキーマ登録の既定動作（TopicNameStrategy）の理解が頻出です。実務でも、これらを前提にトークン化（ドメイン、エンティティ、イベント種別、環境、リージョン、バージョン）しておくと、環境拡張や組織変更にも強い設計になります。

• 探索性: 一貫した接頭辞でメトリクスやログを集約しやすい
• 権限設計: PREFIXED ACLやRBACで安全に委譲できる
• 監査対応: ビジネス文脈（ドメイン/エンティティ/環境）が名前から読める
• 移行容易性: バージョンや環境のトークンで並行稼働が可能

悪例と良例

# 悪例（意味不明/環境不明/記号混在）
orders
kafkaTopic1
sales:order|created

# 良例（ドメイン.エンティティ.イベント.環境.リージョン.版）
sales.order.created.prod.eu-west-1.v1
risk.credit_decision.approved.stg.ap-northeast-1.v2

Kafka公式の制約と落とし穴

Kafkaのトピック名は安定仕様として、使用可能文字が限定され、大文字小文字は区別されます。名前の変更はできません。これらはバージョン間で長く維持されている基本動作です（Kafka公式ドキュメント/Confluent Docs参照）。

よくある誤解として、ドットの階層に意味はありません（フォルダ構造になりません）。またスラッシュやコロンなどの記号は使用できません。長さ上限は実装に依存しますが、一般的に数百文字以内（多くの環境で約249文字）です。運用上は100文字以内を目安にし、ツール連携や可観測性のラベル制限に余裕を残すのが無難です。

• 許容文字: 英数字、ピリオド（.）、アンダースコア（_）、ハイフン（-）
• 大文字小文字は区別される（Orders と orders は別）
• 作成後に名前は変更不可。新トピック作成と移行が必要
• 階層は存在しない（a.b と a/b のような意味差はない）
• 長さは実装依存だが長すぎる名前は避ける（監視・UIの制約も考慮）

最小バリデーションの例（正規表現）

# 許容文字の簡易チェック（例）
# ^[A-Za-z0-9._-]+$ に一致するか確認
# さらに、先頭や末尾の区切り、連続した区切りを禁止する場合はポリシーで拡張
pattern = r'^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?

      

        
        NicheeLab を読み込み中…
      
    
  #x27;

# テスト例
valid = [
  'sales.order.created.prod.eu-west-1.v1',
  'etl_job.status._tmp-123'  # ルールに応じて許可/禁止を決める
]
invalid = [
  'sales/order',  # スラッシュ不可
  'order:created',  # コロン不可
  ' order',         # 先頭空白不可
  '注文',           # 非ASCII不可（標準Kafkaの仕様）
]

推奨パターンと区切り文字の使い分け

運用のしやすさを最優先に、以下の順でトークン化するのを推奨します。org.domain.entity.kind.env.region.version。kind は event, snapshot, command, dlq などのデータ種別です。env は dev/stg/prod など、region はクラウドやデータセンターの識別子、version は互換性の破れを伴う変更時に用います。

区切り文字はドットを階層的な論理分割、ハイフンを人が読む語の連結、アンダースコアを固定トークンや機械的接尾辞に使い分けると実務で扱いやすくなります。

• org は任意（複数組織/テナントをまたぐ場合に有効）
• domain と entity はビジネス語彙をそのまま使い、検索しやすく
• kind は event/snapshot/command/dlq など限定的ボキャブラリに統一
• env は dev/stg/prod の省略形に固定し、余計なバリエーションを作らない
• region はクラウドの一般的表記（例: ap-northeast-1, eu-west-1 等）
• version は v1, v2 とし、後方互換が切れる時のみインクリメント

推奨命名の分解例

パターン例と推奨正規表現

# 例
sales.order.created.prod.eu-west-1.v1
risk.credit_decision.snapshot.stg.ap-northeast-1.v2
common.schema.changelog.dev.us-central1.v1

# 厳しめの社内ルール例（先頭/末尾の区切り禁止、連続区切り禁止、ドット区切りで7トークン）
# ^(?!.*[._-]{2})[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*\.[A-Za-z0-9]+\.[A-Za-z0-9]+\.(event|snapshot|command|dlq)\.(dev|stg|prod)\.[A-Za-z0-9-]+\.(v[0-9]+)$

環境・リージョン・バージョンの扱い

環境は必ずトークン化し、誤配信を防ぎます。プロデューサー/コンシューマーの設定ミスを早期に検知でき、監視ラベルの切り分けにも有効です。リージョンはDRやマルチサイト運用での識別に不可欠です。

バージョンは互換性が破れた場合のみ上げ、古いトピックを段階的に廃止します。新旧を並行運用し、コンシューマーから順に移行するのが安全です。トピック名は変更できないため、v1 と v2 は別トピックとして共存させます。

• env は dev/stg/prod など固定値。prod を省略しない
• region はクラウド表記に準拠（例: ap-northeast-1）
• version は vN。セマンティックに乱用しない（スキーマ互換性と連動）
• 並行運用期間を用意し、ACL/メトリクス/アラートも併せて移行

作成例（CLI）

# 例: kafka-topics（ブローカーに応じてツール名やオプションは調整）
# sales.order.created.prod.eu-west-1.v1 を3パーティション/複製係数3で作成
kafka-topics --bootstrap-server broker:9092 \
  --create --topic sales.order.created.prod.eu-west-1.v1 \
  --partitions 3 --replication-factor 3

# v2 を併存させる
kafka-topics --bootstrap-server broker:9092 \
  --create --topic sales.order.created.prod.eu-west-1.v2 \
  --partitions 6 --replication-factor 3

スキーマ管理とセキュリティ命名連携

Confluent Schema Registry の既定の Subject Naming Strategy は TopicNameStrategy で、<topic>-value の形式でサブジェクトが作成されます。つまり、トピック命名はスキーマのサブジェクト体系にも直結します。命名を揃えることで、スキーマ互換性の検証や監査の粒度を揃えられます。

ACL/RBAC は PREFIXED 設定と相性が良く、共通接頭辞を持つトピック群に対して役割を安全に委譲できます。命名規則はセキュリティ設計と一体で考えるべきです。

• TopicNameStrategy では <topic>-value / <topic>-key が作られる
• 共通接頭辞（例: sales.order.）で PREFIXED ACL を設計しやすい
• dlq など機能的トピックも命名規則に含め、権限の抜け漏れを防止

ACL の例（概念）

# 例: sales.order.* に対してコンシューム権限を委譲（実際のCLIは環境に合わせて調整）
# kafka-acls --bootstrap-server broker:9092 \
#   --add --allow-principal User:svc-analytics \
#   --operation Read --topic "sales.order." --resource-pattern-type prefixed

# スキーマサブジェクトのイメージ（TopicNameStrategy）
# トピック: sales.order.created.prod.eu-west-1.v1
# サブジェクト: sales.order.created.prod.eu-west-1.v1-value

ガバナンスと自動化: 破綻しないための仕組み化

命名規則は文書化して終わりではなく、自動チェックに組み込みます。PR時にリント、作成前にゲートし、カタログで所有者やライフサイクルを管理します。変更審査のワークフローを用意すると、重複や衝突を未然に防げます。

可観測性では、トピック名からラベルを抽出してダッシュボードを自動生成する仕組みが効果的です。アラート名にトークンを反映させ、担当チームへの自動ルーティングも容易になります。

• プリコミット/CIリントで命名を強制
• トピック作成用のサービスカタログに必須メタデータ（所有者、RTO/RPO、PII種別等）を紐付け
• モニタリングでトークンをラベル化し、ダッシュボード/アラートをテンプレ化

シンプルな命名リンター（Bash + grep）

#!/usr/bin/env bash
# 会社ルール: org.domain.entity.kind.env.region.version
name="$1"
regex='^[A-Za-z0-9]+\.[A-Za-z0-9]+\.[A-Za-z0-9]+\.(event|snapshot|command|dlq)\.(dev|stg|prod)\.[A-Za-z0-9-]+\.(v[0-9]+)

      

        
        NicheeLab を読み込み中…
      
    
  #x27;
if [[ "$name" =~ $regex ]]; then
  echo "OK: $name"
  exit 0
else
  echo "NG: $name (規則違反)" >&2
  exit 1
fi

問題で確認

よくある質問