service-catalog/charts/kafka-cluster/CUSTOM-README.md

Apache Kafka 배포 (Strimzi Operator 기반)

1. 배포 방법

1) 배포시 주의 사항

• Apache Kafka 4.0.0은 KRaft 모드로만 동작하며 ZooKeeper가 필요하지 않습니다.
• Controller와 Broker 노드를 분리하여 배포합니다.
• OAuth 2.0 인증이 활성화되어 있으므로 Keycloak 설정이 필요합니다.
• Kafka Connect가 기본적으로 활성화되어 있습니다.
• 프로덕션 환경에서는 리소스 설정과 영속성 스토리지 설정을 반드시 확인해야 합니다.

2) 배포 방법

git clone https://github.com/paasup/service-catalog.git
cd charts/kafka
helm upgrade kafka ./ -f custom-values.yaml --install -n kafka --create-namespace

2. custom-values.yaml 예시

다음은 배포 시 사용할 수 있는 custom-values.yaml 파일의 예시입니다:

kafka:
  version: "4.0.0"
  metadataVersion: "4.0"
  timezone: "Asia/Seoul"

controller:
  replicas: 3
  storage:
    size: 50Gi
    class: longhorn
  resources: {}

broker:
  replicas: 3
  storage:
    size: 50Gi
    class: longhorn
  resources: {}

config:
  offsetsTopicReplicationFactor: 3
  transactionStateLogReplicationFactor: 3
  transactionStateLogMinIsr: 2
  defaultReplicationFactor: 3
  minInsyncReplicas: 2
  autoCreateTopicsEnable: false
  numPartitions: 3
  deleteTopicEnable: true

oauth:
  enabled: true
  keycloakUrl: "https://keycloak.example.com"
  keycloakRealm: "your-realm"
  keycloakClientId: "kafka-client"

kafkaConnect:
  enabled: true
  image: paasup/kafka-connect:0.2
  replicas: 1

entityOperator:
  topicOperator: {}
  userOperator: {}

connectTopics:
  partitions: 1
  replicas: 3
  config:
    cleanupPolicy: compact
    retentionMs: 604800000
    segmentBytes: 1073741824

logging:
  kafka:
    rootLoggerLevel: INFO
  connect:
    rootLoggerLevel: INFO

3. custom-values.yaml 설정 설명

1) Kafka 기본 설정

Name	설명	기본값
kafka.version	Kafka 버전	4.0.0
kafka.metadataVersion	Kafka 메타데이터 버전	4.0
kafka.timezone	Kafka 클러스터 타임존	Asia/Seoul

2) Controller 노드 설정

Name	설명	기본값
controller.replicas	Controller 노드 수	3
controller.storage.size	Controller 영속성 볼륨 크기	50Gi
controller.storage.class	Controller 영속성 볼륨 StorageClass	longhorn
controller.resources	Controller 리소스 제한 설정	{}

3) Broker 노드 설정

Name	설명	기본값
broker.replicas	Broker 노드 수	3
broker.storage.size	Broker 영속성 볼륨 크기	50Gi
broker.storage.class	Broker 영속성 볼륨 StorageClass	longhorn
broker.resources	Broker 리소스 제한 설정	{}

4) Kafka 클러스터 설정

Name	설명	기본값
config.offsetsTopicReplicationFactor	__consumer_offsets 토픽의 복제 팩터	3
config.transactionStateLogReplicationFactor	트랜잭션 상태 로그의 복제 팩터	3
config.transactionStateLogMinIsr	트랜잭션 상태 로그의 최소 동기화 복제본 수	2
config.defaultReplicationFactor	새 토픽의 기본 복제 팩터	3
config.minInsyncReplicas	쓰기 작업에 필요한 최소 동기화 복제본 수	2
config.autoCreateTopicsEnable	토픽 자동 생성 활성화 여부	false
config.numPartitions	새 토픽의 기본 파티션 수	3
config.deleteTopicEnable	토픽 삭제 활성화 여부	true

5) OAuth 2.0 인증 설정

Name	설명	기본값
oauth.enabled	OAuth 2.0 인증 활성화 여부	true
oauth.keycloakUrl	Keycloak 서버 URL	https://keycloak.example.com
oauth.keycloakRealm	Keycloak Realm 이름	your-realm
oauth.keycloakClientId	Keycloak Client ID	kafka-client

6) Kafka Connect 설정

Name	설명	기본값
kafkaConnect.enabled	Kafka Connect 활성화 여부	true
kafkaConnect.image	Kafka Connect 이미지	paasup/kafka-connect:0.2
kafkaConnect.replicas	Kafka Connect 워커 수	1

7) Entity Operator 설정

Name	설명	기본값
entityOperator.topicOperator	Topic Operator 설정	{}
entityOperator.userOperator	User Operator 설정	{}

8) Kafka Connect 내부 토픽 설정

Name	설명	기본값
connectTopics.partitions	Connect 내부 토픽의 파티션 수	1
connectTopics.replicas	Connect 내부 토픽의 복제 팩터	3
connectTopics.config.cleanupPolicy	로그 정리 정책 (compact/delete)	compact
connectTopics.config.retentionMs	로그 보관 기간 (밀리초, 7일)	604800000
connectTopics.config.segmentBytes	로그 세그먼트 크기 (바이트, 1GB)	1073741824

9) 로깅 설정

Name	설명	기본값
logging.kafka.rootLoggerLevel	Kafka 루트 로거 레벨	INFO
logging.connect.rootLoggerLevel	Kafka Connect 루트 로거 레벨	INFO

4. 배포 아키텍처

1) Controller와 Broker 분리 배포

• controller.replicas: 3 - Controller 전용 노드 3개
• broker.replicas: 3 - Broker 전용 노드 3개
• Controller와 Broker 역할을 분리하여 성능 최적화
• 대규모 프로덕션 환경에 적합

2) 고가용성 설정

• 복제 팩터 3으로 데이터 손실 방지
• 최소 동기화 복제본 2로 일관성 보장
• 각 노드에 50Gi 영속성 스토리지 할당

5. 클라이언트 연결

1) OAuth 2.0 인증을 사용한 클라이언트 설정 예시

bootstrap.servers=kafka-kafka-bootstrap:9092
security.protocol=SASL_PLAINTEXT
sasl.mechanism=OAUTHBEARER
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  oauth.client.id="kafka-client" \
  oauth.client.secret="<client-secret>" \
  oauth.token.endpoint.uri="https://keycloak.example.com/realms/your-realm/protocol/openid-connect/token";
sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler

2) Keycloak 설정 확인

Keycloak에서 다음 설정을 확인하세요:

• Realm: your-realm
• Client ID: kafka-client
• Client Secret 생성 및 확인
• Service Account 활성화

6. Kafka Connect 사용

1) Connector 상태 확인

# Kafka Connect 로그 확인
kubectl logs -n kafka -l strimzi.io/cluster=kafka-connect

# Connector 목록 확인
kubectl get kafkaconnectors -n kafka

7. 트러블슈팅

1) 일반적인 문제

• Pod 시작 실패: Longhorn 스토리지 클래스 확인 및 리소스 부족 여부 확인
• OAuth 인증 실패: Keycloak URL, Realm, Client ID 설정 확인
• Kafka Connect 연결 실패: Connect 내부 토픽 생성 및 권한 확인
• 성능 문제: 리소스 설정 및 파티션 수 조정

2) 로그 확인

# Kafka Controller 로그 확인
kubectl logs -n kafka kafka-kafka-controller-0

# Kafka Broker 로그 확인
kubectl logs -n kafka kafka-kafka-broker-0

# Kafka Connect 로그 확인
kubectl logs -n kafka -l strimzi.io/cluster=kafka-connect

3) 토픽 관리

# 토픽 목록 확인
kubectl get kafkatopics -n kafka

# 토픽 상세 정보 확인
kubectl describe kafkatopic test-topic -n kafka

4) 사용자 관리

# 사용자 목록 확인
kubectl get kafkausers -n kafka