Kafka Schema Registry 구축 - EKS에 Apicurio Registry 설치하기

Kafka 스키마 레지스트리란 무엇인가?
앞선 글에서 스키마 레지스트리가 무엇인지, 왜 필요한지 살펴보았습니다.

이번 글에서는 실제로 Apicurio Registry를 EKS 환경에 설치하고 내부적으로 어떻게 동작이 되는지 알아보겠습니다.

---

사전 준비

• EKS 클러스터
• ArgoCD 설치 및 Git 레포지터리 연결
• Kafka 클러스터 (Strimzi 등)

---

1. Apicurio Operator 설치

Apicurio Registry는 Kubernetes Operator 방식으로 동작합니다.

Operator를 먼저 설치해야 이후 Registry 인스턴스를 CRD로 생성할 수 있습니다.

1-1. Operator YAML 준비

저는 공식 Github에서 제공하는 apicurio-registry-operator-3.1.7.yaml 다운로드하여 Operator 설치를 진행하였습니다.

Apicurio Registry v3.0부터 Operator 코드가 기존의 분리된 apicurio-registry-operator 레포에서
메인 apicurio-registry 레포로 통합되었습니다. v3.x 설치 시 아래 경로를 사용해야 합니다.

Apicurio operator YAML 파일이 있는 Github 주소

파일을 열어보면 다음 리소스들이 포함되어 있습니다.

리소스	이름	설명
CustomResourceDefinition	apicurioregistries3	Registry 인스턴스를 CRD로 관리
ServiceAccount	apicurio-registry-operator	Operator가 사용하는 서비스 계정
ClusterRole	apicurio-registry-operator-clusterrole	필요한 권한 정의
ClusterRoleBinding	apicurio-registry-operator-clusterrolebinding	ClusterRole을 ServiceAccount에 바인딩
Deployment	apicurio-registry-operator	Operator 파드

1-2. 문제 발견 — PLACEHOLDER_NAMESPACE

파일을 보면 네임스페이스가 하드코딩되지 않고 PLACEHOLDER_NAMESPACE로 되어 있는 부분이 있습니다.

# ClusterRoleBinding
subjects:
- kind: ServiceAccount
  name: apicurio-registry-operator
  namespace: PLACEHOLDER_NAMESPACE   # ← 교체 필요

# Deployment
metadata:
  namespace: PLACEHOLDER_NAMESPACE   # ← 교체 필요

이 값들은 실제 사용하려는 네임스페이스로 교체해야 합니다.

저 같은 경우 ArgoCD + Kustomize 환경에서 배포를 하기 때문에 YAML에서 직접 수정하지 않고 kustomization.yaml로 처리합니다.

1-3. kustomization.yaml 작성

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - apicurio-operator.yaml        # operator.yaml
  - kafka-schema-registry.yaml    # apicurio-registry.yaml
namespace: apicurio

patches:
  - patch: |-
      - op: replace
        path: /subjects/0/namespace
        value: apicurio
    target:
      kind: ClusterRoleBinding
      name: apicurio-registry-operator-clusterrolebinding

kustomization.yaml 구성 설명

namespace: apicurio는 Kustomize의 Namespace Transformer를 트리거하여 namespace 리소스의 metadata.namespace를 일괄 교체합니다.

단, ClusterRoleBinding은 cluster-scoped 리소스라 metadata.namespace가 존재하지 않고,

내부의 subjects[].namespace는 Namespace Transformer가 자동으로 처리하지 않습니다.

이 때문에 patches를 사용해 JSON Patch 방식으로 해당 필드를 명시적으로 교체합니다.

리소스	처리 방식
Deployment	namespace: apicurio로 자동 처리
ServiceAccount	namespace: apicurio로 자동 처리
ClusterRoleBinding subjects	명시적 patch 필요

이제 Github Repository에 operator.yaml, kustomization.yaml 을 Push 하고
해당 레포지터리를 ArgoCD와 연결을 시켜주면 operator 배포가 완료 됩니다.

2. Apicurio Registry 배포

Operator가 정상적으로 작동하면, ApicurioRegistry3 CRD로 실제 Registry 인스턴스를 생성합니다.

2-1. Apicurio Registry YAML 작성 (스토리지 설정)

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry3
metadata:
  name: apicurio-registry-kafkasql
  namespace: apicurio
spec:
  app:
    storage:
      type: kafkasql
      kafkasql:
        bootstrapServers: <kafka boostrap/broker 주소>

각 필드를 살펴보면 다음과 같습니다.

• spec.app.storage.type: kafkasql: Registry의 백엔드 스토리지를 Kafka로 사용하겠다는 설정입니다. 스키마 데이터가 Kafka 토픽에 저장됩니다.
• spec.app.storage.kafkasql.bootstrapServers: Registry가 연결할 Kafka 브로커 주소입니다. 클러스터 내부 DNS 형식(<service>.<namespace>.svc.cluster.local)으로 작성합니다.

2-2. Apicurio Registry YAML 작성 (Ingress 설정)

Apicurio Registry는 API 서버(app)와 UI(ui) 두 컴포넌트로 구성되며, 각각 별도의 Ingress를 설정할 수 있습니다.

아래 예시는 AWS EKS 환경에서 AWS Load Balancer Controller(ALB)를 사용하는 경우입니다.
nginx, traefik 등 다른 Ingress Controller를 사용하는 경우 ingressClassName과 annotations를 해당 환경에 맞게 변경하면 됩니다.

spec:
  app:
    ingress:
      host: <api-도메인>
      ingressClassName: alb
      annotations:
        alb.ingress.kubernetes.io/scheme: internet-facing
        alb.ingress.kubernetes.io/target-type: ip
        alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
        alb.ingress.kubernetes.io/certificate-arn: <ACM 인증서 ARN>
        alb.ingress.kubernetes.io/ssl-redirect: '443'
        alb.ingress.kubernetes.io/group.name: <ALB 그룹명>
  ui:
    env:
      - name: REGISTRY_API_URL
        value: "https://<api-도메인>/apis/registry/v3"
    ingress:
      host: <ui-도메인>
      ingressClassName: alb
      annotations:
        # app과 동일한 ALB annotations 사용

• spec.app.ingress: Registry REST API 엔드포인트에 대한 Ingress 설정입니다.
• spec.ui.ingress: Registry 웹 UI에 대한 Ingress 설정입니다.
• spec.ui.env[REGISTRY_API_URL]: UI가 API를 호출할 주소를 지정합니다. app.ingress.host와 동일한 도메인으로 맞춰줘야 UI에서 스키마 목록이 정상적으로 로드됩니다.

2-3. kustomization.yaml에 추가

앞서 1-3 과정에서 작성한 kustomization.yaml의 resources에 추가합니다.

resources:
  - apicurio-operator.yaml
  - kafka-schema-registry.yaml # 앞서 작성한 Apicurio Registry.yaml 파일

3. 동작 확인

정상적으로 설치가 완료가 되었다면, Ingress로 노출 시킨 UI 주소로 접속 하면 아래와 같이 웹 UI가 나오게 됩니다.

---

마무리

이렇게 Kafka 스키마 레지스트리로 사용할 Apicurio Registry 설치를 해보았습니다.

다음 글에서는 스키마 레지스트리를 사용하여 어떻게 동작시키는 지에 대해 알아보겠습니다.