Kafka ClickPipe 向けスキーマレジストリ

​

ストリーミング ClickPipes でサポートされるスキーマレジストリ

• Confluent 互換レジストリ: Confluent スキーマレジストリ自体や Redpanda Schema Registry など、Confluent スキーマレジストリと API 互換性のあるレジストリです。Avro と Protobuf をサポートします。
• AWS Glue Schema Registry: 通常 Amazon MSK から取得される、AWS Glue SerDe でシリアル化された Avro データ用です。

​

Confluent 互換レジストリ

​

設定

1. スキーマの subject への完全なパスを指定します (例: https://registry.example.com/subjects/events)
   • 必要に応じて、URL に /versions/[version] を追加することで特定のバージョンを参照できます (追加しない場合、ClickPipes は最新バージョンを取得します) 。
2. スキーマ ID への完全なパスを指定します (例: https://registry.example.com/schemas/ids/1000)
3. スキーマレジストリのルート URL を指定します (例: https://registry.example.com)

​

ネットワーク接続

• スキーマレジストリの URL には https:// を使用する必要があります。
• レジストリのホスト名がプライベートアドレスに解決される場合は、ClickPipe 用に選択された reverse private endpoint 経由で到達可能である必要があります。そうでないと、Setup 中の接続チェックは失敗します。

​

仕組み

• レコード値にスキーマ ID が埋め込まれている場合は、それを使ってスキーマを取得します。
• レコード値にスキーマ ID が埋め込まれていない場合は、ClickPipe の設定で指定されたスキーマ ID または subject 名を使ってスキーマを取得します。
• レコード値に埋め込みのスキーマ ID がなく、かつ ClickPipe の設定でスキーマ ID も subject 名も指定されていない場合、スキーマは取得されず、ClickPipes のエラーテーブルに SOURCE_SCHEMA_ERROR が記録され、そのメッセージはスキップされます。
• レコード値がスキーマに準拠していない場合、ClickPipes のエラーテーブルに DATA_PARSING_ERROR が記録され、そのメッセージはスキップされます。
• Protobuf スキーマのみ: ClickPipes は、依存関係として定義された import 済みのスキーマを読み込みます。外部参照を含む Avro スキーマは、現時点ではサポートされていません。

​

AWS Glue Schema Registry

​

設定

​

IAM の設定

​

オプション A: ブローカーの IAM ID を再利用する

• IAM ロール: MSK 用に設定されたロールの権限ポリシーにステートメントを追加します。
• IAM 認証情報: アクセスキーに関連付けられた IAM プリンシパルの権限ポリシーにステートメントを追加します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClickPipesGlueSchemaRegistryRead",
      "Effect": "Allow",
      "Action": ["glue:GetSchemaVersion"],
      "Resource": "*"
    }
  ]
}

​

オプション B: 専用のレジストリロールを使用する

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "{ClickHouse_IAM_ARN}"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClickPipesGlueSchemaRegistryRead",
      "Effect": "Allow",
      "Action": ["glue:GetSchemaVersion"],
      "Resource": "*"
    }
  ]
}

​

トラブルシューティング

​

制限事項

• Kafka は Avro のみをサポートします。Glue SerDe 経由の JSON Schema および Protobuf はサポートされていません。
• Kinesis は AWS Glue Schema Registry を介して AvroConfluent と Protobuf をサポートします。アップロードした Protobuf スキーマをスキーマレジストリと併用することはできません。

​

スキーママッピング

• スキーマに、ClickHouse の宛先マッピングに含まれていないフィールドがある場合、そのフィールドは無視されます。
• スキーマに、ClickHouse の宛先マッピングで定義されているフィールドがない場合、ClickHouse のカラムには 0 や空文字列などの「ゼロ」値が設定されます。なお、DEFAULT 式はサポートされていません。
• スキーマのフィールドと ClickHouse のカラムに互換性がない場合、その行/メッセージの挿入は失敗し、その失敗は ClickPipes のエラーテーブルに記録されます。なお、いくつかの暗黙的な変換 (たとえば数値型同士) はサポートされていますが、すべてがサポートされるわけではありません (たとえば、Avro のレコードフィールドを Int32 の ClickHouse カラムに挿入することはできません) 。