백엔드 데이터 인프라 98편 — Kafka Admin Client 설정 (간결 정리)

이 글은 백엔드 데이터 인프라 시리즈 130편 중 98편이에요. Part 5-4 Configuration 의 마지막 글. 94~97편 으로 broker·topic·producer·consumer 설정을 깊이 풀었다면, 이번 98편은 Admin Client 설정 — 짧지만 운영 자동화에 필수.

Admin Client Config가 짧은 이유

Producer/Consumer 처럼 데이터 흐름이나 튜닝을 다루지 않아서예요. broker 와의 통신, 그리고 운영 명령의 timing 만 관리하면 끝.

총 ~30가지 설정 중에서 자주 건드리는 10가지만 알면 충분해요.

1. 필수 (1개)

bootstrap.servers

bootstrap.servers=kafka1:9092,kafka2:9092,kafka3:9092

여러 broker 명시 (다른 client 와 동일).

2. Timeout (4개)

request.timeout.ms

request.timeout.ms=30000               # 30초 (기본)

한 admin 요청에서 broker 응답을 기다리는 최대 시간이에요.

default.api.timeout.ms

default.api.timeout.ms=60000           # 60초 (기본)

Admin API 메서드 호출의 전체 timeout (retry 포함). request.timeout.ms 보다 상위 개념이에요.

admin.createTopics(topics).all().get();   // 최대 default.api.timeout.ms 까지 대기

특정 호출만 override:

CreateTopicsOptions options = new CreateTopicsOptions().timeoutMs(120000);
admin.createTopics(topics, options).all().get();

connections.max.idle.ms

connections.max.idle.ms=300000          # 5분 (기본)

Idle connection 종료.

socket.connection.setup.timeout.ms · socket.connection.setup.timeout.max.ms

socket.connection.setup.timeout.ms=10000        # 10초
socket.connection.setup.timeout.max.ms=30000    # 30초

TCP(전송 제어 프로토콜) 연결 수립 timeout (exponential backoff).

3. Retries (3개)

retries

retries=2147483647                      # 거의 무한 (기본)

일시적 실패가 나면 자동으로 retry 해요.

retry.backoff.ms

retry.backoff.ms=100                    # 100ms (기본)

Retry 사이 대기.

retry.backoff.max.ms

retry.backoff.max.ms=1000               # 1초 (기본)

Exponential backoff 최대값.

4. Identity·Monitoring (2개)

client.id

client.id=devops-tool

Broker log·메트릭에서 가독성을 챙겨줘요. DevOps script 나 CI/CD(지속 통합·배포) 가 쓸 때 명시해두면 좋아요.

metric.reporters

metric.reporters=org.apache.kafka.common.metrics.JmxReporter

JMX(자바 메트릭 표준)·Prometheus(메트릭 수집 도구) 통합.

5. Security (다른 client 와 동일)

security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-512
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
    username="admin-user" \
    password="strong-password";

ssl.truststore.location=/etc/kafka/ssl/truststore.jks
ssl.truststore.password=trust-pass

113~116편 깊이.

6. DNS·Network 옵션

client.dns.lookup

client.dns.lookup=use_all_dns_ips        # 기본
# 또는
client.dns.lookup=resolve_canonical_bootstrap_servers_only

DNS(도메인 이름 시스템) resolution 정책. use_all_dns_ips = 모든 IP 를 시도해 multi-IP load balancing 효과를 내요.

운영 환경 권장 조합

CI/CD provisioning (Java)

bootstrap.servers=kafka1:9092,kafka2:9092,kafka3:9092

# Identity
client.id=ci-cd-provisioner

# Timeouts (CI/CD 는 빠른 실패 우선)
request.timeout.ms=15000
default.api.timeout.ms=60000

# Retries
retries=3
retry.backoff.ms=1000

# Security
security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-512
sasl.jaas.config=...

Spring Boot Provisioning

spring:
  kafka:
    bootstrap-servers: kafka1:9092,kafka2:9092
    admin:
      properties:
        request.timeout.ms: 15000
        default.api.timeout.ms: 60000
        client.id: app-provisioner
        security.protocol: SASL_SSL
        sasl.mechanism: SCRAM-SHA-512
        sasl.jaas.config: ...

@Bean NewTopic 가 자동으로 이 설정 사용.

DevOps 자동화 패턴 종합

1. Application 시작 시 Topic 자동 생성 (Spring)

@Bean
public NewTopic ordersTopic() {
    return TopicBuilder.name("orders")
            .partitions(3)
            .replicas(2)
            .config("retention.ms", "604800000")
            .build();
}

가장 깔끔. 93편 깊이.

2. Shell Script 기반 (kafka-topics.sh)

#!/bin/bash
kafka-topics.sh --create --topic orders \
    --bootstrap-server localhost:9092 \
    --partitions 3 \
    --replication-factor 3 \
    --if-not-exists

--if-not-exists = 이미 있으면 skip 하는 idempotent 동작이에요.

3. Terraform Kafka Provider

resource "kafka_topic" "orders" {
  name               = "orders"
  partitions         = 3
  replication_factor = 3
  config = {
    "retention.ms"        = "604800000"
    "min.insync.replicas" = "2"
  }
}

GitOps(Git 으로 인프라 관리) 스타일. 코드가 곧 인프라예요.

4. Strimzi (Kubernetes Operator)

apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaTopic
metadata:
  name: orders
spec:
  partitions: 3
  replicas: 3
  config:
    retention.ms: 604800000

Kubernetes 환경에서 가장 자연스러워요. CRD(쿠버네티스 커스텀 리소스) 기반.

한계·실무 함정

1. request.timeout.ms < default.api.timeout.ms 일관성

default.api > request.timeout 권장. retry 시간이 default.api 안에 들어가야 정상 동작해요.

2. Admin 작업 + ACL 권한

99% admin 작업은 ACL(접근 제어 목록) 권한이 필요해요. 116편 ACL 깊이.

3. Cluster 부담

대량의 admin 작업은 controller 에 부담을 줘요. CI/CD 환경에서는 batch 나 throttle 로 흐름을 조절하는 게 안전.

4. Idempotent vs 누락 확인

createTopics 를 이미 있는 topic 에 호출하면 TopicExistsException 이 나요. exception 처리가 필수예요.

try {
    admin.createTopics(...).all().get();
} catch (ExecutionException e) {
    if (!(e.getCause() instanceof TopicExistsException)) {
        throw e;
    }
    // 이미 있음 = 정상
}

또는 CLI 라면 --if-not-exists 로 회피.

Part 5-4 Configuration 마무리

5편 (94~98) 으로 Kafka 의 4가지 설정 영역을 다 풀었어요:

• 94 Broker — node·log·replication·network·security·KRaft 설정
• 95 Topic — per-topic retention·compression·cleanup·min.insync override
• 96 Producer — acks·idempotence·batch·linger·compression·timeout
• 97 Consumer — group·session·heartbeat·max.poll·fetch·assignment
• 98 Admin — bootstrap·timeout·retries·security

Kafka 운영은 설정 튜닝의 학습 곡선이 가장 커요. 기본값을 그대로 따르되, 운영 환경에서 자주 만나는 함정 5~10개만 명시 설정해두는 게 일반적인 시작점이에요.

시험 직전 한 번 더 — Kafka Admin Config 함정 압축 노트

• 필수 = bootstrap.servers
• Timeout = request.timeout.ms (30초)·default.api.timeout.ms (60초) 이 상위 개념
• 특정 호출 override = CreateTopicsOptions().timeoutMs(...)
• connections.max.idle.ms (5분)·socket.connection.setup.timeout.ms
• Retries = 거의 무한 (기본) + retry.backoff.ms
• client.id = 운영 모니터링 가독성, CI/CD script 자주 명시
• Security = 다른 client 와 동일 (113~116편)
• client.dns.lookup=use_all_dns_ips = multi-IP load balancing
• DevOps 자동화 4가지 패턴 = Spring @Bean NewTopic · Shell Script (--if-not-exists) · Terraform · Strimzi (K8s CRD)
• 가장 깔끔 = Spring @Bean NewTopic (애플리케이션 시작 시 자동)
• GitOps = Terraform 또는 Strimzi
• 함정 — default.api > request.timeout 일관성
• 함정 — ACL 권한 부족 → AuthorizationException
• 함정 — 대량 admin = controller 부담, batch/throttle
• 함정 — createTopics 이미 있는 topic = TopicExistsException, exception 처리 또는 --if-not-exists
• Part 5-4 Configuration 5편 종합 — broker (94) + topic (95) + producer (96) + consumer (97) + admin (98)
• 운영 시작 시 = 기본값 + 함정 5~10개만 명시 설정

공식 문서: Kafka Admin Client Configs 에서 자세한 사양을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 93편 — Kafka Admin Client API (Topic·ACL·Consumer Group 관리)
• 94편 — Kafka Broker 설정 30가지 (실무 핵심)
• 95편 — Kafka Topic 설정 (Retention · Compression · Cleanup)
• 96편 — Kafka Producer 설정 20가지 (Batching · Retries · Idempotence)
• 97편 — Kafka Consumer 설정 25가지 (Group · Commit · Fetch)

다음 글:

• 99편 — Kafka 운영 기본 (Topic·Partition·Reassign·Rolling Restart)
• 100편 — Kafka Monitoring (JMX 메트릭 30가지)
• 101편 — Kafka Multi-tenancy (Quota · Naming · ACL 분리)
• 102편 — Kafka 다중 데이터센터 (Stretched · Local + Mirror)
• 103편 — Kafka Geo-Replication (MirrorMaker 2)