Kafka ClickPipe용 스키마 레지스트리

ClickPipes는 Avro 및 Protobuf로 인코딩된 레코드 값과 구조화된 Kafka 키를 디코딩할 수 있도록 스키마 레지스트리 통합을 지원합니다.

Kafka ClickPipes에서 지원하는 스키마 레지스트리

Kafka ClickPipes는 두 가지 유형의 스키마 레지스트리를 지원합니다.

Confluent 호환 레지스트리: Confluent 스키마 레지스트리와 API 호환되는 모든 레지스트리로, Confluent 스키마 레지스트리 및 Redpanda 스키마 레지스트리 등이 포함됩니다. Avro와 Protobuf를 지원합니다.
AWS Glue 스키마 레지스트리: 일반적으로 Amazon MSK에서 AWS Glue SerDe를 사용해 직렬화한 Avro 데이터용입니다.

ClickPipes는 아직 Azure 스키마 레지스트리를 지원하지 않습니다. 지원이 필요하면 팀에 문의하십시오.

Confluent 호환 레지스트리

구성

ClickPipes를 구성하는 동안 스키마 레지스트리와 통합하려면 다음 방법 중 하나를 사용해야 합니다:

스키마 subject의 전체 경로를 제공합니다(예: https://registry.example.com/subjects/events)
- 필요에 따라 URL에 /versions/[version]을 추가하여 특정 버전을 참조할 수 있습니다(그렇지 않으면 ClickPipes가 최신 버전을 가져옵니다).
스키마 ID의 전체 경로를 제공합니다(예: https://registry.example.com/schemas/ids/1000)
스키마 레지스트리 루트 URL을 제공합니다(예: https://registry.example.com)

네트워크 연결

ClickPipes는 지정한 URL을 통해 HTTPS로 스키마 레지스트리에 연결합니다. 스키마 레지스트리가 공개적으로 액세스 가능할 필요는 없습니다. Kafka 브로커에 reverse private endpoint (AWS PrivateLink 또는 GCP Private Service Connect)를 통해 연결하는 경우, 스키마 레지스트리도 동일한 비공개 연결을 사용할 수 있습니다. ClickPipes는 reverse private endpoint의 Private DNS를 통해 레지스트리 호스트명을 확인하므로, 브로커와 함께 비공개로 호스팅되는 레지스트리도 해당 호스트명이 reverse private endpoint의 비공개 IP 주소로 확인되기만 하면 연결할 수 있습니다(엔드포인트의 Private DNS 지원 또는 사용자 지정 Private DNS 매핑을 통해). 다음 사항에 유의하십시오:

스키마 레지스트리 URL은 https://를 사용해야 합니다.
레지스트리 호스트명이 비공개 주소로 확인되는 경우, ClickPipe에 선택된 reverse private endpoint를 통해 연결할 수 있어야 합니다. 그렇지 않으면 Setup 중 연결 확인이 실패합니다.

작동 방식

ClickPipes는 구성된 스키마 레지스트리에서 스키마를 동적으로 가져와 적용합니다.

레코드 값에 스키마 ID가 포함되어 있으면 이를 사용해 스키마를 가져옵니다.
레코드 값에 스키마 ID가 포함되어 있지 않으면 ClickPipe 구성에 지정된 스키마 ID 또는 subject 이름을 사용해 스키마를 가져옵니다.
레코드 값이 내장된 스키마 ID 없이 작성되었고 ClickPipe 구성에도 스키마 ID 또는 subject 이름이 지정되지 않은 경우, 스키마를 가져오지 않으며 해당 메시지는 건너뜁니다. 이때 ClickPipes 오류 테이블에 SOURCE_SCHEMA_ERROR가 기록됩니다.
레코드 값이 스키마를 준수하지 않으면 해당 메시지는 건너뜁니다. 이때 ClickPipes 오류 테이블에 DATA_PARSING_ERROR가 기록됩니다.
Protobuf 스키마에만 해당: ClickPipes는 종속성으로 정의된 가져온 스키마를 모두 로드합니다. 외부 참조가 있는 Avro 스키마는 아직 지원되지 않습니다.

_key.id와 같은 필드의 매핑이 구성되면 ClickPipes는 Kafka 키에 포함된 스키마 ID를 레코드 값과 독립적으로 해석합니다. 키는 다른 스키마 ID를 사용할 수 있지만, 값과 동일한 레지스트리 제품군 및 직렬화 형식을 사용해야 합니다. 해석된 키 스키마는 캐시되며 스키마 변경 사항은 자동으로 감지됩니다.

AWS Glue 스키마 레지스트리

프로듀서가 AWS Glue SerDe를 사용해 Avro를 직렬화하는 경우(예: Amazon MSK 토픽에서 AWSKafkaAvroSerializer 사용), ClickPipes는 AWS Glue 스키마 레지스트리에서 해당 스키마를 직접 확인할 수 있습니다. Glue는 Confluent-compatible registries와 wire 형식 및 API가 다르므로 별도로 구성합니다. AWS Glue 스키마 레지스트리 구성은 현재 ClickHouse Cloud 콘솔에서만 사용할 수 있습니다. ClickPipes API 또는 Terraform 프로바이더를 통한 구성은 지원되지 않습니다.

Avro만 지원합니다. AWS Glue 레지스트리는 Avro 형식만 지원합니다. Glue SerDe는 JSON과 Protobuf도 프레이밍할 수 있지만, ClickPipes에서는 지원하지 않으며 파이프를 생성할 때 거부됩니다.

구성

ClickPipe 생성 마법사의 Kafka 연결 단계에서 스키마 레지스트리를 활성화하고 레지스트리 유형을 AWS Glue로 설정하십시오:

필드	필수 여부	설명	예시
레지스트리 유형	예	AWS Glue를 선택합니다	`AWS Glue`
AWS 리전	예	Glue 레지스트리가 위치한 리전입니다. 레지스트리의 리전과 정확히 일치해야 합니다.	`us-east-1`
레지스트리 이름	예	Glue 레지스트리의 이름입니다. 다른 레지스트리로 해석되는 스키마는 거부되므로, ClickPipes가 스키마 버전을 해석할 때 오타가 확인됩니다.	`my-glue-registry`
IAM 역할 ARN	조건부	레지스트리 액세스 전용 역할입니다. 브로커가 IAM 인증을 사용하는 경우에는 선택 사항이며, 그렇지 않으면 필수입니다.	`arn:aws:iam::123456789012:role/ClickHouseAccessRole-glue`

구성할 레지스트리 URL은 없습니다. Glue SerDe에서 생성되는 모든 레코드에는 해당 스키마 버전의 ID가 포함됩니다. ClickPipes는 glue:GetSchemaVersion을 사용해 이를 해석하고, 고유한 스키마 버전마다 API를 한 번 호출해 캐시합니다. 스키마 진화는 자동으로 처리됩니다. 스트림 중간에 레코드가 새 스키마 버전으로 전환되면 처음 발견될 때 해석됩니다.

IAM 설정

환경에 맞는 두 옵션 중 하나를 사용하십시오. Amazon MSK에서는 일반적으로 옵션 A를 사용합니다.

옵션 A: 브로커의 IAM 아이덴티티 재사용

Kafka ClickPipe가 이미 IAM을 통해 MSK에 인증하는 경우, ClickPipes는 동일한 IAM 아이덴티티를 사용하여 레지스트리를 읽습니다. IAM 역할 ARN 필드는 비워 두고 아이덴티티의 권한에 다음 문을 추가하십시오:

IAM 역할: MSK에 구성된 역할의 권한 정책에 해당 문을 추가하십시오.
IAM credentials: 액세스 키와 연결된 IAM 주체의 권한 정책에 해당 문을 추가하십시오.

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

역할 기반 인증에는 신뢰 정책를 변경할 필요가 없습니다. MSK에 구성된 신뢰 관계가 이미 이 액세스를 허용합니다. IAM 자격 증명은 역할 신뢰 정책를 사용하지 않습니다.

옵션 B: 전용 레지스트리 역할 사용

브로커가 IAM 인증(SASL/SCRAM, SASL/PLAIN, mTLS)을 사용하지 않거나 레지스트리가 브로커와 다른 AWS 계정에 있는 경우 이 옵션을 사용합니다.

AWS 배포에만 해당합니다. 이 옵션은 서비스의 AWS IAM 역할을 사용하므로 AWS에 배포된 ClickHouse Cloud 서비스가 필요합니다. 서비스가 GCP 또는 Azure에서 실행되고 브로커가 IAM 인증을 사용하지 않는 경우에는 전용 레지스트리 역할을 구성할 수 없습니다.

ClickHouse 서비스 IAM 역할 ARN 가져오기

서비스를 열고 설정 탭을 선택합니다. Network security information 섹션까지 스크롤한 후 arn:aws:iam::123456789012:role/CH-S3-example-service-Role 형식의 ARN인 Service role ID (IAM) 값을 복사합니다. 아래에서는 이 값을 {ClickHouse_IAM_ARN}으로 지칭합니다. AWS에 배포된 각 ClickHouse 서비스에는 고유한 역할이 있으므로 이 값은 서비스마다 다릅니다.

레지스트리 IAM 역할 생성

AWS 계정에서 IAM 역할을 생성합니다. 역할 이름은 반드시 ClickHouseAccessRole-로 시작해야 합니다.신뢰 정책 구성{ClickHouse_IAM_ARN}을 이전 단계에서 복사한 값으로 바꿉니다.

{
  "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": "*"
    }
  ]
}

ClickPipe 구성

마법사의 IAM 역할 ARN 필드에 새 역할의 ARN을 붙여 넣습니다.

IAM 리소스 범위. 이 예시는 모두 "*"에 대한 glue:GetSchemaVersion 권한을 부여하는 AWS의 deserializer 관련 문서화된 정책과 AWSGlueSchemaRegistryReadonlyAccess 관리형 정책을 따릅니다. ClickPipes는 해석된 각 스키마가 구성한 레지스트리 이름에 속하는지 별도로 확인하며, 다른 레지스트리의 버전은 거부합니다.

문제 해결

오류	원인 및 해결 방법
`access denied retrieving schema version …: check the IAM role grants glue:GetSchemaVersion`	레지스트리 액세스에 사용되는 IAM 아이덴티티에 `glue:GetSchemaVersion` 권한이 없습니다. 역할 기반 접근에서는 역할의 신뢰 정책에 서비스 역할 ID가 지정되지 않았을 수도 있습니다. 위의 IAM 설정을 다시 확인하십시오.
`… is not authorized to perform: sts:AssumeRole on resource: …`	신뢰 정책에 잘못된 주체가 지정되어 있습니다. 오류에는 역할 수임을 시도한 정확한 역할이 포함됩니다. 신뢰 정책에 해당 값을 사용하십시오.
`schema version … not found in Glue schema registry`	레코드가 구성된 계정 또는 리전에 존재하지 않는 스키마 버전을 참조합니다. AWS 리전이 레지스트리의 리전과 일치하는지 확인하십시오.
`schema version … belongs to Glue registry "X", but the pipe is configured for registry "Y"`	producer가 파이프에 지정된 레지스트리와 다른 레지스트리에 스키마를 등록하고 있습니다. 레지스트리 이름을 수정하거나 producer가 올바른 레지스트리를 사용하도록 설정하십시오.
`the AWS Glue schema registry only supports the Avro format`	Glue 파이프는 Avro만 지원합니다. Glue SerDe를 통한 JSON 및 Protobuf는 지원되지 않습니다.

제한 사항

Avro만 지원됩니다. Glue SerDe를 통한 JSON Schema 및 Protobuf 형식은 지원되지 않습니다.
Kafka 소스만 지원됩니다. Kinesis ClickPipes에서는 Glue 레지스트리를 사용할 수 없습니다.

스키마 매핑

다음 규칙은 Confluent 호환 레지스트리와 AWS Glue 스키마 레지스트리 모두에 적용됩니다. 이 규칙은 가져온 값 스키마와 ClickHouse 대상 테이블 간의 매핑에 적용되며, _key. 접두사가 있는 구조화된 키에서 매핑된 레코드 또는 메시지 필드에도 적용됩니다.

스키마에 ClickHouse 대상 매핑에 포함되지 않은 필드가 있으면 해당 필드는 무시됩니다.
스키마에 ClickHouse 대상 매핑에 정의된 필드가 없으면 ClickHouse 컬럼은 0 또는 빈 문자열과 같은 “제로” 값으로 채워집니다. DEFAULT 표현식은 지원되지 않습니다.
스키마 필드와 ClickHouse 컬럼이 호환되지 않으면 해당 행/메시지의 삽입이 실패하고, 이 실패는 ClickPipes 오류 테이블에 기록됩니다. 일부 암시적 변환(예: 숫자 타입 간 변환)은 지원되지만, 모든 경우가 지원되는 것은 아닙니다(예: Avro 레코드 필드는 Int32 ClickHouse 컬럼에 삽입할 수 없습니다).

ClickPipes for Object Storage

ClickPipes for Postgres

ClickPipes for Kafka

ClickPipes for Kinesis

ClickPipes for GCP Pub/Sub

ClickPipes for MySQL

ClickPipes for MongoDB

ClickPipes for BigQuery

프로그래밍 방식 액세스

네트워킹

기타

Kafka ClickPipe용 스키마 레지스트리

Kafka ClickPipes에서 지원하는 스키마 레지스트리

Confluent 호환 레지스트리

구성

네트워크 연결

작동 방식

AWS Glue 스키마 레지스트리

구성

IAM 설정

옵션 A: 브로커의 IAM 아이덴티티 재사용

옵션 B: 전용 레지스트리 역할 사용

문제 해결

제한 사항

스키마 매핑

​Kafka ClickPipes에서 지원하는 스키마 레지스트리

​Confluent 호환 레지스트리

​구성

​네트워크 연결

​작동 방식

​AWS Glue 스키마 레지스트리

​구성

​IAM 설정

​옵션 A: 브로커의 IAM 아이덴티티 재사용

​옵션 B: 전용 레지스트리 역할 사용

​문제 해결

​제한 사항

​스키마 매핑

Kafka ClickPipes에서 지원하는 스키마 레지스트리

Confluent 호환 레지스트리

구성

네트워크 연결

작동 방식

AWS Glue 스키마 레지스트리

구성

IAM 설정

옵션 A: 브로커의 IAM 아이덴티티 재사용

옵션 B: 전용 레지스트리 역할 사용

문제 해결

제한 사항

스키마 매핑