네, 알겠습니다. 첫 번째 글인 ‘ConfigMap 기반 워크플로우’를 워드프레스에 바로 게시할 수 있는 전문가용 기술 문서 형식으로 작성해 드리겠습니다.
Kafka Connect와 커스텀 SMT의 GitOps 통합 관리 (1): ConfigMap 기반 워크플로우
Kafka Connect와 커스텀 SMT(Single Message Transform)를 운영할 때 핵심 과제는 소스 코드(SMT), 설정(Connector JSON), 인프라(Connect Pod)의 생명주기를 일관성 있게 관리하는 것입니다. GitOps는 이 문제를 해결하기 위한 강력한 패러다임으로, Git을 단일 진실 공급원(Single Source of Truth)으로 삼아 모든 변경 사항을 선언적으로 관리합니다.
이번 문서에서는 Kubernetes ConfigMap을 활용하여 커스텀 SMT JAR 파일을 Kafka Connect 클러스터에 배포하고, 전체 프로세스를 자동화하는 구체적인 GitOps 워크플로우를 제시합니다.
통합 관리 목표
본 워크플로우의 목표는 다음과 같습니다.
- 커넥터 설정(JSON): 모든 커넥터 구성을 Git에서 버전 관리합니다.
- Kafka Connect 인프라: Helm 차트를 통해 선언적으로 배포 및 관리합니다.
- 커스텀 SMT: 소스 코드 빌드부터 클러스터 배포 및 적용까지 완전 자동화합니다.
- 전체 흐름: Git, CI/CD, Helm, REST API를 연동하여 통합된 관리 체계를 구축합니다.
GitOps 디렉토리 구조
효율적인 관리를 위해 모든 리소스를 하나의 Git 저장소에 아래와 같은 표준 구조로 구성합니다.
kafka-connect-gitops/
├── helm/
│ └── kafka-connect-values.yaml # Helm 배포 설정
├── connectors/
│ ├── mongo-source.json # MongoDB 소스 커넥터
│ └── s3-sink.json # S3 싱크 커넥터
├── smt/
│ ├── build.gradle # Gradle 빌드 스크립트
│ └── custom-smt/
│ └── src/main/java/.../CustomSMT.java
├── plugins/
│ └── kafka-connect-custom-smt.jar # CI가 생성한 SMT 아티팩트
├── scripts/
│ ├── build-smt.sh
│ ├── apply-connectors.sh
│ └── deploy-smt-and-restart.sh
├── .gitlab-ci.yml # GitLab CI/CD 파이프라인
└── README.md이 구조는 인프라(Helm), 비즈니스 로직(SMT), 애플리케이션 설정(Connectors)을 명확히 분리하여 가독성과 유지보수성을 높입니다.
ConfigMap을 활용한 SMT 배포 전략
이 전략의 핵심은 커스텀 SMT JAR 파일을 Kubernetes ConfigMap에 바이너리 데이터로 저장하고, 이를 Kafka Connect Pod에 볼륨으로 마운트하는 것입니다.
1. Helm 설정 (helm/kafka-connect-values.yaml)
먼저, Kafka Connect Helm 차트의 values.yaml 파일을 수정하여 ConfigMap을 볼륨으로 마운트하고, 해당 경로를 Kafka의 plugin.path에 추가합니다.
# plugin.path에 커스텀 SMT가 마운트될 경로를 추가합니다.
pluginPaths: "/opt/kafka/plugins,/opt/kafka/custom-smt"
# ConfigMap을 볼륨으로 마운트하기 위한 설정입니다.
extraVolumeMounts:
- name: custom-smt-volume
mountPath: /opt/kafka/custom-smt
extraVolumes:
- name: custom-smt-volume
configMap:
# CI/CD 파이프라인이 생성하고 관리할 ConfigMap의 이름입니다.
name: kafka-custom-smt2. 자동화 스크립트
CI/CD 파이프라인에서 실행될 스크립트는 SMT 빌드와 배포를 자동화합니다.
SMT 빌드 스크립트 (scripts/build-smt.sh)
Gradle을 사용하여 SMT 소스 코드를 빌드하고 JAR 파일을 생성합니다.
#!/bin/bash
set -e
# smt 디렉토리로 이동하여 빌드 실행
cd smt
./gradlew clean shadowJar
# 빌드된 JAR 파일을 상위 plugins 디렉토리로 복사
JAR_PATH=$(find . -name "*.jar" | grep build/libs)
cp "$JAR_PATH" ../plugins/kafka-connect-custom-smt.jar
echo "✅ SMT JAR 빌드 완료 → plugins/"SMT 배포 및 재시작 스크립트 (scripts/deploy-smt-and-restart.sh)
빌드된 JAR 파일로 ConfigMap을 멱등성(idempotent)을 보장하며 생성/업데이트하고, 변경 사항을 적용하기 위해 Kafka Connect Deployment의 롤링 재시작을 트리거합니다.
#!/bin/bash
set -e
NAMESPACE=kafka
JAR_FILE=plugins/kafka-connect-custom-smt.jar
CONFIGMAP_NAME=kafka-custom-smt
echo "🧩 커스텀 SMT ConfigMap 생성/업데이트 중..."
# --dry-run과 apply를 사용하여 선언적으로 ConfigMap을 관리합니다.
kubectl create configmap $CONFIGMAP_NAME \
--from-file=custom-smt.jar=$JAR_FILE \
-n $NAMESPACE \
--dry-run=client -o yaml | kubectl apply -f -
echo "🔄 Kafka Connect 재시작 (롤링 업데이트)"
kubectl rollout restart deployment/kafka-connect -n $NAMESPACECI/CD 파이프라인 통합 (.gitlab-ci.yml)
마지막으로, 위 모든 과정을 GitLab CI/CD 파이프라인으로 통합합니다. smt 또는 connectors 디렉토리에 변경이 발생하면 파이프라인이 자동으로 실행되어 빌드와 배포를 수행합니다.
stages:
- build
- deploy
build-smt:
stage: build
image: gradle:8-jdk17
script:
- chmod +x scripts/build-smt.sh
- ./scripts/build-smt.sh
artifacts:
# 빌드된 JAR 파일을 다음 스테이지에서 사용할 수 있도록 아티팩트로 저장
paths:
- plugins/kafka-connect-custom-smt.jar
deploy-kafka-connect:
stage: deploy
image: bitnami/kubectl:latest
script:
- chmod +x scripts/deploy-smt-and-restart.sh
- chmod +x scripts/apply-connectors.sh
# SMT 배포 및 커넥트 재시작
- ./scripts/deploy-smt-and-restart.sh
# 커넥터 설정 적용
- ./scripts/apply-connectors.sh
rules:
# main 브랜치에서 smt 또는 connectors 디렉토리 변경 시에만 실행
- if: '$CI_COMMIT_BRANCH == "main"'
changes:
- smt/**/*
- connectors/**/*이 워크플로우를 통해 SMT 소스 코드 변경부터 실제 Kafka Connect 클러스터 반영까지의 전 과정이 자동화됩니다.
