From 96a1e2421cb2b98ec77ce674c278d42dd35498d5 Mon Sep 17 00:00:00 2001 From: wbsong111 Date: Mon, 8 Sep 2025 11:20:27 +0900 Subject: [PATCH] Add custom-values.yaml, README.md --- charts/kafka/BUILD-README.md | 90 ++++++++++++++ charts/kafka/CUSTOM-README.md | 211 ++++++++++++++++++++++++++++++++ charts/kafka/custom-values.yaml | 62 ++++++++++ 3 files changed, 363 insertions(+) create mode 100644 charts/kafka/BUILD-README.md create mode 100644 charts/kafka/CUSTOM-README.md create mode 100644 charts/kafka/custom-values.yaml diff --git a/charts/kafka/BUILD-README.md b/charts/kafka/BUILD-README.md new file mode 100644 index 0000000..2f90bc2 --- /dev/null +++ b/charts/kafka/BUILD-README.md @@ -0,0 +1,90 @@ +# Kafka 버전 갱신 가이드 + +## 1. git 작업 환경 구성 + +- 서비스 카탈로그 git 다운로드 +``` +$ git clone https://github.com/paasup/service-catalog.git +``` + +- 작업 브랜치로 체크아웃 +``` +$ git checkout -b update-kafka/32.4.3 +``` + +## 2. helm chart 업데이트 + +### 1) 차트 버전 변경 + +- BUILD-README.md, CUSTOM-README.md, custom-values.yaml을 제외한 파일 삭제 + ``` sh + # chart 디렉토리로 이동 + cd ~/service-catalog/charts/kafka + + # 파일 삭제 전 삭제할 파일 목록 확인 + find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -print + + # 파일 삭제 + find . -mindepth 1 \( -name "CUSTOM-README.md" -o -name "BUILD-README.md" -o -name "custom-values.yaml" \) -prune -o -exec rm -rf {} + + ``` + +- bitnami/kafka 차트 다운로드 + ``` sh + # charts 디렉토리로 이동 + cd ~/service-catalog/charts + + # helm repo 추가 + helm repo add bitnami https://charts.bitnami.com/bitnami + helm repo update + + # helm 차트 다운로드 + helm pull bitnami/kafka --version="32.4.3" + + # 차트 변경 + tar xzvf kafka*.tgz + + # 필요 없는 파일 삭제 + rm kafka-*.tgz + ``` + +### 2) 차트 수정 사항 반영 + +- Bitnami Kafka 차트는 기본적으로 KRaft 모드로 동작하며, 별도의 수정 사항 없이 사용 가능합니다. +- custom-values.yaml에서 필요한 설정을 조정하여 사용합니다. + +## 3. git push 및 tag 추가 + +- 갱신작업 진행후 commit +``` +$ git add . +$ git commit -m "update kafka/32.4.3" +``` + +- main 브랜치에 체크아웃 후 merge +``` +$ git checkout main +$ git merge update-kafka/32.4.3 +``` + +- git에 push 후 작업 브랜치 삭제 +``` +$ git push -u origin main +$ git branch -d update-kafka/32.4.3 +``` + +- git tag 추가 후 push +``` +$ git tag kafka/32.4.3 +$ git push origin kafka/32.4.3 +``` + +## 4. 차트 버전 정보 + +- kafka/32.4.3 + - Apache Kafka 4.0.0 기반 Bitnami 차트 + - KRaft 모드 기본 지원 (ZooKeeper 불필요) + - Controller-eligible 노드와 Broker-only 노드 분리 배포 지원 + - SASL 인증 기본 활성화 + - JMX 메트릭 및 Prometheus 모니터링 지원 + - 서비스 배포를 위하여 custom-values.yaml에 정의 + - 차트의 빌드 방법과 배포 방법을 BUILD-README.md, CUSTOM-README.md 문서에 작성 \ No newline at end of file diff --git a/charts/kafka/CUSTOM-README.md b/charts/kafka/CUSTOM-README.md new file mode 100644 index 0000000..ff470bc --- /dev/null +++ b/charts/kafka/CUSTOM-README.md @@ -0,0 +1,211 @@ +# Apache Kafka 배포 + +## 1. 배포 방법 + +### 1) 배포시 주의 사항 +- Apache Kafka 4.0.0은 KRaft 모드로만 동작하며 ZooKeeper가 필요하지 않습니다. +- Controller-eligible 노드와 Broker-only 노드를 분리하여 배포할 수 있습니다. +- SASL 인증이 기본적으로 활성화되어 있으므로 클라이언트 연결 시 인증 정보가 필요합니다. +- 프로덕션 환경에서는 리소스 설정과 영속성 스토리지 설정을 반드시 확인해야 합니다. + +### 2) 배포 방법 +```sh +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 파일의 예시입니다: + +```yaml +# Global 설정 +global: + imageRegistry: "" # paasup.io (오프라인 환경에서 설정) + imagePullSecrets: [] + defaultStorageClass: "" + +# Kafka 이미지 설정 +image: + registry: docker.io + repository: bitnami/kafka + tag: 4.0.0-debian-12-r10 + +# Controller-eligible 노드 설정 (Controller + Broker 역할) +controller: + replicaCount: 3 + controllerOnly: false # true로 설정하면 Controller 전용 노드 + persistence: + enabled: true + size: 8Gi + storageClass: "" + logPersistence: + enabled: false + size: 8Gi + storageClass: "" + resources: {} + resourcesPreset: "small" + +# Broker-only 노드 설정 (선택사항) +broker: + replicaCount: 0 # 필요시 증가 + persistence: + enabled: true + size: 8Gi + storageClass: "" + logPersistence: + enabled: true + size: 8Gi + storageClass: "" + resources: {} + resourcesPreset: "small" + +# 리스너 설정 +listeners: + client: + containerPort: 9092 + protocol: SASL_PLAINTEXT + controller: + containerPort: 9093 + protocol: SASL_PLAINTEXT + interbroker: + containerPort: 9094 + protocol: SASL_PLAINTEXT + +# SASL 인증 설정 +sasl: + enabledMechanisms: PLAIN,SCRAM-SHA-256,SCRAM-SHA-512 + client: + users: ["user1"] + passwords: "" # 자동 생성 또는 별도 설정 + +# 서비스 설정 +service: + type: ClusterIP + ports: + client: 9092 + +# 메트릭 설정 +metrics: + jmx: + enabled: false +``` + +## 3. custom-values.yaml 설정 설명 + +### 1) 전역 설정 +- 오프라인 환경 배포시 사용합니다. + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `global.imageRegistry` | 오프라인 설치 시에 설정.
paasup 설치시에는 "paasup.io"으로 설정 | `""` | +| `global.imagePullSecrets` | Docker 레지스트리 시크릿 이름 배열 | `[]` | +| `global.defaultStorageClass` | 영속성 볼륨을 위한 기본 StorageClass | `""` | + +### 2) Kafka 이미지 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | -------------------------------- | +| `image.registry` | Kafka 이미지 레지스트리 | `docker.io` | +| `image.repository` | Kafka 이미지 리포지토리 | `bitnami/kafka` | +| `image.tag` | Kafka 이미지 태그 | `4.0.0-debian-12-r10` | + +### 3) Controller-eligible 노드 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `controller.replicaCount` | Controller-eligible 노드 수 | `3` | +| `controller.controllerOnly` | true로 설정하면 Controller 전용 노드로 동작
false면 Controller+Broker 역할 | `false` | +| `controller.persistence.enabled` | 데이터 영속성 활성화 | `true` | +| `controller.persistence.size` | 영속성 볼륨 크기 | `8Gi` | +| `controller.persistence.storageClass` | 영속성 볼륨 StorageClass | `""` | +| `controller.logPersistence.enabled` | 로그 영속성 활성화 | `false` | +| `controller.resourcesPreset` | 리소스 프리셋 (none, nano, micro, small, medium, large, xlarge, 2xlarge) | `small` | + +### 4) Broker-only 노드 설정 (선택사항) + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `broker.replicaCount` | Broker 전용 노드 수 (0이면 비활성화) | `0` | +| `broker.persistence.enabled` | 데이터 영속성 활성화 | `true` | +| `broker.persistence.size` | 영속성 볼륨 크기 | `8Gi` | +| `broker.logPersistence.enabled` | 로그 영속성 활성화 | `false` | +| `broker.resourcesPreset` | 리소스 프리셋 | `small` | + +### 5) 리스너 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ------------------- | +| `listeners.client.containerPort` | 클라이언트 연결 포트 | `9092` | +| `listeners.client.protocol` | 클라이언트 리스너 보안 프로토콜 | `SASL_PLAINTEXT` | +| `listeners.controller.containerPort` | Controller 통신 포트 | `9093` | +| `listeners.controller.protocol` | Controller 리스너 보안 프로토콜 | `SASL_PLAINTEXT` | +| `listeners.interbroker.containerPort` | Broker 간 통신 포트 | `9094` | +| `listeners.interbroker.protocol` | Inter-broker 리스너 보안 프로토콜 | `SASL_PLAINTEXT` | + +### 6) SASL 인증 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | -------------------------------- | +| `sasl.enabledMechanisms` | 활성화된 SASL 메커니즘 (쉼표로 구분) | `PLAIN,SCRAM-SHA-256,SCRAM-SHA-512` | +| `sasl.client.users` | 클라이언트 사용자 목록 | `["user1"]` | +| `sasl.client.passwords` | 클라이언트 사용자 비밀번호 (빈 문자열이면 자동 생성) | `""` | + +### 7) 메트릭 설정 + +| Name | 설명 | 기본값 | +| ------------------------- | ------------------------------------------------------------ | ----------- | +| `metrics.jmx.enabled` | JMX 메트릭을 Prometheus로 노출할지 여부 | `false` | + +## 4. 배포 아키텍처 + +### 1) 기본 배포 (Controller + Broker) +- `controller.replicaCount: 3`, `controller.controllerOnly: false` +- 각 노드가 Controller와 Broker 역할을 모두 수행 +- 소규모 환경에 적합 + +### 2) 분리 배포 (Controller 전용 + Broker 전용) +- `controller.replicaCount: 3`, `controller.controllerOnly: true` +- `broker.replicaCount: 3` 이상 +- Controller와 Broker 역할을 분리하여 성능 최적화 +- 대규모 환경에 적합 + +## 5. 클라이언트 연결 + +### 1) 클라이언트 설정 예시 +```properties +bootstrap.servers=kafka:9092 +security.protocol=SASL_PLAINTEXT +sasl.mechanism=PLAIN +sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="user1" password=""; +``` + +### 2) 비밀번호 확인 +```sh +kubectl get secret kafka-user-passwords -o jsonpath='{.data.client-passwords}' | base64 -d +``` + +## 6. 트러블슈팅 + +### 1) 일반적인 문제 +- **Pod 시작 실패**: 리소스 부족 또는 영속성 볼륨 문제 확인 +- **클라이언트 연결 실패**: SASL 인증 정보 및 네트워크 정책 확인 +- **성능 문제**: 리소스 설정 및 JVM 힙 크기 조정 + +### 2) 로그 확인 +```sh +# Kafka 로그 확인 +kubectl logs -n kafka kafka-controller-0 + +# 모든 Kafka 노드 상태 확인 +kubectl get pods -n kafka -l app.kubernetes.io/name=kafka +``` + +### 3) 토픽 관리 +```sh +# 토픽 생성 +kubectl exec -it kafka-controller-0 -n kafka -- kafka-topics.sh --create --topic test-topic --bootstrap-server localhost:9092 --partitions 3 --replication-factor 3 + +# 토픽 목록 확인 +kubectl exec -it kafka-controller-0 -n kafka -- kafka-topics.sh --list --bootstrap-server localhost:9092 \ No newline at end of file diff --git a/charts/kafka/custom-values.yaml b/charts/kafka/custom-values.yaml new file mode 100644 index 0000000..ac16938 --- /dev/null +++ b/charts/kafka/custom-values.yaml @@ -0,0 +1,62 @@ +global: + imageRegistry: "" + imagePullSecrets: [] + defaultStorageClass: "" + +image: + registry: docker.io + repository: bitnami/kafka + tag: 4.0.0-debian-12-r10 + +controller: + replicaCount: 3 + controllerOnly: false + persistence: + enabled: true + size: 8Gi + storageClass: "" + logPersistence: + enabled: false + size: 8Gi + storageClass: "" + resources: {} + resourcesPreset: "small" + +broker: + replicaCount: 0 + persistence: + enabled: true + size: 8Gi + storageClass: "" + logPersistence: + enabled: true + size: 8Gi + storageClass: "" + resources: {} + resourcesPreset: "small" + +listeners: + client: + containerPort: 9092 + protocol: SASL_PLAINTEXT + controller: + containerPort: 9093 + protocol: SASL_PLAINTEXT + interbroker: + containerPort: 9094 + protocol: SASL_PLAINTEXT + +sasl: + enabledMechanisms: PLAIN,SCRAM-SHA-256,SCRAM-SHA-512 + client: + users: ["user1"] + passwords: "" + +service: + type: ClusterIP + ports: + client: 9092 + +metrics: + jmx: + enabled: false