service-catalog/manifests/helm/kafka/32.4.3/CUSTOM-README.md

# 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`    | 오프라인 설치 시에 설정. <br />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 전용 노드로 동작<br />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="<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