service-catalog/manifests/helm/kafka-cluster/1.0.0/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) 배포 방법

```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
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.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.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 인증을 사용한 클라이언트 설정 예시

```properties
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 상태 확인

```sh
# 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) 로그 확인

```sh
# 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) 토픽 관리

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

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

### 4) 사용자 관리

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