Avro Schema Registry 호환성 이슈 정리

1. 이슈 개요

Kafka 환경에서 Avro + Schema Registry를 사용하는 시스템에서
Producer가 새로운 필드를 포함한 메시지를 전송하는 과정에서
메시지 전송이 실패하는 문제가 발생했다.

표면적으로는 Kafka 전송 오류처럼 보였지만,
근본 원인은 Schema Registry의 호환성 정책(Compatibility Policy) 위반이었다.

---

2. 증상

• Kafka Producer 메시지 전송 실패

• 애플리케이션 로그에 다음과 같은 오류 발생

  • InvalidConfigurationException
  • Schema being registered is incompatible with an earlier schema
  • HTTP Status: 409 (Conflict)

오류 상세 메시지에는 다음 문구가 반복적으로 나타났다.

• READER_FIELD_MISSING_DEFAULT_VALUE
• “new schema has fields missing default value that are not present in old schema”

---

3. 시스템 구성 예시

• Kafka Topic: sample_event_topic
• Schema Subject: sample_event_topic-value
• Avro + Schema Registry 사용
• Schema Registry 호환성 정책: BACKWARD

기존 Avro Schema(v1):

{
  "type": "record",
  "name": "SampleEvent",
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "url", "type": "string" }
  ]
}

---

4. Schema Registry 호환성 정책 설명

Schema Registry는 스키마 변경으로 인해 과거 또는 미래 데이터가 깨지는 것을 방지하기 위해
호환성 정책을 제공한다.

주요 호환성 정책

정책	의미
BACKWARD	새 스키마가 이전 스키마로 작성된 데이터를 읽을 수 있어야 함
FORWARD	이전 스키마가 새 스키마로 작성된 데이터를 읽을 수 있어야 함
FULL	BACKWARD + FORWARD 모두 만족
NONE	호환성 검사 없음

운영 환경에서는 보통 BACKWARD 또는 FULL 정책이 사용된다.

---

BACKWARD 호환성의 핵심 규칙

BACKWARD 정책에서는 다음 규칙이 매우 중요하다.

새로 추가되는 필드는 반드시 default 값을 가져야 한다

이유는 다음과 같다.

• 과거에 저장된 데이터에는 새 필드가 존재하지 않음
• 새 스키마가 과거 데이터를 읽을 때 해당 필드 값을 채워야 함
• default 값이 없으면 값을 채울 수 없어 호환성 위반이 발생

---

5. 문제 발생 원인

기존 스키마에 여러 필드를 추가한 새로운 스키마를 등록하려고 했으나,

• 새 필드들이 기존 스키마에는 존재하지 않았고
• default 값이 정의되지 않았기 때문에

Schema Registry에서 BACKWARD 호환성 위반으로 판단하여
스키마 등록을 거부하였다.

이로 인해 Kafka Producer는 메시지를 정상적으로 전송하지 못했다.

---

6. 데이터 관점에서 확인된 특징

실제 전송 데이터를 확인해보면 다음과 같은 패턴이 있었다.

• 값이 없는 경우

  • 문자열 타입 → ""
  • 숫자 타입 → 0

즉, 데이터 생성 단계에서 이미
null 대신 기본값을 채워 넣는 정책이 적용되고 있었다.

이러한 데이터 특성은 Avro 스키마에서 default 값을 명시하는 방식과 잘 맞는다.

---

7. 해결 방법

신규 필드에 default 값 명시

새로 추가되는 모든 필드에 타입에 맞는 default 값을 정의하였다.

예시:

{ "name": "userAgent", "type": "string", "default": "" }
{ "name": "status", "type": "int", "default": 0 }

이렇게 수정한 결과:

• 과거 데이터는 default 값으로 자동 보완됨
• BACKWARD 호환성 조건 충족
• Schema Registry 스키마 등록 성공
• Kafka 메시지 전송 정상화

---

8. 정리

• 이번 이슈는 Kafka 자체 문제가 아니라 Schema Registry 호환성 정책 문제

• Avro 스키마에서 필드 추가는 매우 신중해야 함

• BACKWARD 정책 환경에서는:

  • 필드 추가 = default 값 필수

• 데이터 생성 로직과 Avro 스키마 정책을 일관되게 유지하는 것이 중요

---

9. 핵심 요약

BACKWARD 호환성 환경에서 default 없는 필드 추가는 곧 장애다.