> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 스키마 관리를 위해 ClickPipes를 스키마 레지스트리와 통합하는 방법을 설명합니다.

# Kafka ClickPipe용 스키마 레지스트리

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

ClickPipes는 Avro 및 Protobuf로 인코딩된 레코드 값과 [구조화된 Kafka 키](/ko/integrations/clickpipes/kafka/reference#structured-message-keys)를 디코딩할 수 있도록 스키마 레지스트리 통합을 지원합니다.

<div id="supported-schema-registries">
  ## Kafka ClickPipes에서 지원하는 스키마 레지스트리
</div>

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

* [Confluent 호환 레지스트리](#confluent-compatible-registries): Confluent 스키마 레지스트리와 API 호환되는 모든 레지스트리로, Confluent 스키마 레지스트리 및 Redpanda 스키마 레지스트리 등이 포함됩니다. Avro와 Protobuf를 지원합니다.
* [AWS Glue 스키마 레지스트리](#aws-glue-schema-registry): 일반적으로 Amazon MSK에서 AWS Glue SerDe를 사용해 직렬화한 Avro 데이터용입니다.

ClickPipes는 아직 Azure 스키마 레지스트리를 지원하지 않습니다. 지원이 필요하면 [팀에 문의하십시오](https://clickhouse.com/company/contact?loc=clickpipes).

<div id="confluent-compatible-registries">
  ## Confluent 호환 레지스트리
</div>

<div id="schema-registry-configuration">
  ### 구성
</div>

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

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`)

<div id="network-connectivity">
  ### 네트워크 연결
</div>

ClickPipes는 지정한 URL을 통해 HTTPS로 스키마 레지스트리에 연결합니다. 스키마 레지스트리가 공개적으로 액세스 가능할 필요는 없습니다.

Kafka 브로커에 [reverse private endpoint](/ko/integrations/clickpipes/networking/aws-privatelink) (AWS PrivateLink 또는 GCP Private Service Connect)를 통해 연결하는 경우, 스키마 레지스트리도 동일한 비공개 연결을 사용할 수 있습니다. ClickPipes는 reverse private endpoint의 Private DNS를 통해 레지스트리 호스트명을 확인하므로, 브로커와 함께 비공개로 호스팅되는 레지스트리도 해당 호스트명이 reverse private endpoint의 비공개 IP 주소로 확인되기만 하면 연결할 수 있습니다(엔드포인트의 Private DNS 지원 또는 [사용자 지정 Private DNS 매핑](/ko/integrations/clickpipes/networking/aws-privatelink#custom-private-dns)을 통해).

다음 사항에 유의하십시오:

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

<div id="how-schema-registries-work">
  ### 작동 방식
</div>

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를 사용할 수 있지만, 값과 동일한 레지스트리 제품군 및 직렬화 형식을 사용해야 합니다. 해석된 키 스키마는 캐시되며 스키마 변경 사항은 자동으로 감지됩니다.

<div id="aws-glue-schema-registry">
  ## AWS Glue 스키마 레지스트리
</div>

프로듀서가 AWS Glue SerDe를 사용해 Avro를 직렬화하는 경우(예: Amazon MSK 토픽에서 `AWSKafkaAvroSerializer` 사용), ClickPipes는 AWS Glue 스키마 레지스트리에서 해당 스키마를 직접 확인할 수 있습니다. Glue는 Confluent-compatible registries와 wire 형식 및 API가 다르므로 별도로 구성합니다.

AWS Glue 스키마 레지스트리 구성은 현재 ClickHouse Cloud 콘솔에서만 사용할 수 있습니다. ClickPipes API 또는 Terraform 프로바이더를 통한 구성은 지원되지 않습니다.

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

<div id="schema-registry-configuration">
  ### 구성
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/zkBy8QRjLpx6BosZ/images/integrations/data-ingestion/clickpipes/cp_glue_schema_registry.png?fit=max&auto=format&n=zkBy8QRjLpx6BosZ&q=85&s=188dff783fd121f404db0b330328c22b" alt="AWS Glue가 선택된 스키마 레지스트리 패널" size="lg" border width="1634" height="836" data-path="images/integrations/data-ingestion/clickpipes/cp_glue_schema_registry.png" />

| 필드         | 필수 여부 | 설명                                                                                 | 예시                                                         |
| ---------- | ----- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 레지스트리 유형   | 예     | **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를 한 번 호출해 캐시합니다. 스키마 진화는 자동으로 처리됩니다. 스트림 중간에 레코드가 새 스키마 버전으로 전환되면 처음 발견될 때 해석됩니다.

<div id="glue-iam-setup">
  ### IAM 설정
</div>

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

<div id="glue-iam-option-a">
  #### 옵션 A: 브로커의 IAM 아이덴티티 재사용
</div>

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

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

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

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

<div id="glue-iam-option-b">
  #### 옵션 B: 전용 레지스트리 역할 사용
</div>

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/1eeX3TpI5_hf7pMs/images/cloud/security/secures3_arn.webp?fit=max&auto=format&n=1eeX3TpI5_hf7pMs&q=85&s=eca2429eafa40e68c69b990183f3be59" alt="서비스 역할 ID (IAM)" size="lg" border width="1222" height="254" data-path="images/cloud/security/secures3_arn.webp" />
  </Step>

  <Step title="레지스트리 IAM 역할 생성" id="create-registry-iam-role">
    AWS 계정에서 IAM 역할을 생성합니다. 역할 이름은 **반드시** `ClickHouseAccessRole-`로 시작해야 합니다.

    **신뢰 정책 구성**

    `{ClickHouse_IAM_ARN}`을 이전 단계에서 복사한 값으로 바꿉니다.

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

    **권한 정책 구성**

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "ClickPipesGlueSchemaRegistryRead",
          "Effect": "Allow",
          "Action": ["glue:GetSchemaVersion"],
          "Resource": "*"
        }
      ]
    }
    ```
  </Step>

  <Step title="ClickPipe 구성" id="configure-clickpipe-registry-role">
    마법사의 **IAM 역할 ARN** 필드에 새 역할의 ARN을 붙여 넣습니다.
  </Step>
</Steps>

<Note>
  **IAM 리소스 범위.** 이 예시는 모두 `"*"`에 대한 `glue:GetSchemaVersion` 권한을 부여하는 [AWS의 deserializer 관련 문서화된 정책](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs-serde.html)과 [`AWSGlueSchemaRegistryReadonlyAccess` 관리형 정책](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSGlueSchemaRegistryReadonlyAccess.html)을 따릅니다. ClickPipes는 해석된 각 스키마가 구성한 **레지스트리 이름**에 속하는지 별도로 확인하며, 다른 레지스트리의 버전은 거부합니다.
</Note>

<div id="glue-troubleshooting">
  ### 문제 해결
</div>

| 오류                                                                                           | 원인 및 해결 방법                                                                                                                             |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `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는 지원되지 않습니다.                                                                      |

<div id="glue-limitations">
  ### 제한 사항
</div>

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

<div id="schema-mapping">
  ## 스키마 매핑
</div>

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

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