토리맘의 한글라이즈 프로젝트 logo 토리맘의 한글라이즈 프로젝트

아파치 카프카 공식 레퍼런스를 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.

목차


카프카 설정은 프로퍼티 파일 포맷의 key-value 쌍을 사용한다. 설정 값은 파일로도, 프로그래밍 방식으로도 제공할 수 있다.


3.1 Broker Configs

핵심 설정은 다음과 같다:

토픽 레벨 설정과 기본값은 아래에서 자세히 논한다.

Type: list
Default: ””
Valid Values:  
Importance: medium
Update Mode: per-broker

브로커 설정에 대한 더 자세한 내용은 스칼라 클래스 kafka.server.KafkaConfig에서 확인할 수 있다.

3.1.1 Updating Broker Configs

카프카 1.1 버전부터 일부 브로커 설정은 브로커를 재시작하지 않고도 업데이트할 수 있다. 각 브로커 설정의 업데이트 모드는 브로커 설정에 있는 Update Mode 컬럼을 참고해라.

현재 브로커 id 0에 있는 브로커 설정을 변경하려면 (예를 들어, 로그 클리너 스레드 수) :

> bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-name 0 \
  --alter --add-config log.cleaner.threads=2

현재 브로커 id 0에 있는 다이나믹 브로커 설정을 조회하려면:

> bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-name 0 --describe

재정의한 설정을 제거하고, 브로커 id 0에 정적으로 설정한 값이나 기본값으로 되돌리려면 (예를 들어, 로그 클리너 스레드 수) :

> bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-name 0 \
  --alter --delete-config log.cleaner.threads

일부 설정에 클러스터 전체의 디폴트값을 설정하면, 설정값을 전체 클러스터에서 동일하게 유지할 수 있다. 클러스터 디폴트 업데이트는 클러스터에 있는 모든 브로커에 반영된다. 예를 들어, 모든 브로커의 로그 클리너 스레드를 업데이트하려면:

> bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-default \
  --alter --add-config log.cleaner.threads=2

현재 설정된 클러스터 전체의 디폴트 다이나믹 설정을 조회하려면:

> bin/kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-default --describe

클러스터 수준에서 설정할 수 있는 모든 설정은 브로커별로도 설정할 수 있다 (예를 들어 테스트 용으로). 같은 설정 값을 여러 가지 레벨에서 정의하면, 다음과 같은 우선 순위가 적용된다:

Updating Password Configs Dynamically

동적으로 업데이트한 패스워드 설정 값은 주키퍼에 저장하기 전에 암호화된다. 패스워드 설정의 다이나믹 업데이트를 활성화하려면, server.properties에 브로커 설정 password.encoder.secret을 설정해야 한다. 시크릿은 브로커마다 다를 수 있다.

패스워드 인코딩에 사용하는 시크릿은 브로커의 순차 재시작으로 교체할 수 있다. 암호를 인코딩하는데 사용했던, 현재 주키퍼에 있는 이전 시크릿은 스태틱 브로커 설정 password.encoder.old.secret에 제공해야 하며, 새 시크릿은 password.encoder.secret에 제공해야 한다. 주키퍼에 저장돼 있는 모든 다이나믹 패스워드 설정은 브로커가 시작할 때 새 시크릿으로 다시 인코딩된다.

카프카 1.1.x에선, 패스워드 설정을 변경하는 게 아니더라도, kafka-configs.sh를 사용해 설정을 업데이트할 땐 모든 변경 요청에 동적으로 업데이트한 모든 패스워드 설정을 제공해야 한다. 이 제약은 이후 릴리즈에서 제거됐다.

Updating Password Configs in ZooKeeper Before Starting Brokers

Kafka 2.0.0부터 kafka-configs.sh를 사용하면 브로커를 부트스트랩하기 전에 주키퍼로 다이나믹 브로커 설정을 업데이트할 수 있다. 이렇게 하면 모든 패스워드 설정을 암호화된 형식으로 저장할 수 있으므로, server.properties에 명확한 패스워드가 없어도 된다. alter 커맨드에 패스워드 설정이 하나라도 있다면 반드시 브로커 설정 password.encoder.secret을 지정해야 한다. 다른 암호화 파라미터도 함께 지정할 수 있다. 패스워드 인코더 설정은 주키퍼에 유지되지 않는다. 예를 들어, 브로커 0에서 INTERNAL 리스너에 대한 SSL 키 패스워드를 저장하려면:

> bin/kafka-configs.sh --zookeeper localhost:2182 \
  --zk-tls-config-file zk_tls_config.properties \
  --entity-type brokers --entity-name 0 --alter \
  --add-config 'listener.name.internal.ssl.key.password=key-password,password.encoder.secret=secret,password.encoder.iterations=8192'

listener.name.internal.ssl.key.password 설정은 함께 제공한 인코더 설정을 통해 주키퍼에 암호화된 형태로 보관한다. 인코더 시크릿과 이터레이션은 주키퍼에 유지되지 않는다.

Updating SSL Keystore of an Existing Listener

인증서 손상 위험을 줄이기 위해 브로커에 유효 기간이 짧은 SSL keystore를 설정할 수도 있다. keystore는 브로커를 다시 시작하지 않고도 동적으로 업데이트할 수 있다. 설정명은 리스너 프리픽스 listener.name.{listenerName.}으로 시작해야 한다. 이렇게 해야 특정 리스너의 keystore 설정만 업데이트된다. 개별 브로커 수준에서 단일 alter 요청으로 업데이트할 수 있는 설정은 다음과 같다:

keystore를 수정하려는 리스너가 브로커 간에 사용하는 리스너라면, 해당 리스너에 설정한 truststore가 새 keystore를 신뢰하는 경우에만 업데이트를 허용한다. 브로커는 그외 다른 리스너에선 keystore에 대한 신뢰 여부를 검증하지 않는다. 클라이언트 인증 실패를 방지하려면 이전 인증서를 서명한 같은 인증 기관에서 인증서를 서명받아야 한다.

Updating SSL Truststore of an Existing Listener

인증서를 추가하거나 제거할 때는, 브로커를 다시 시작하지 않고도 브로커 truststore를 동적으로 업데이트할 수 있다. 새 클라이언트 커넥션을 인증할 때는 업데이트된 truststore를 사용한다. 설정명은 리스너 프리픽스 listener.name.{listenerName}.으로 시작해야 한다. 이렇게 해야 특정 리스너의 truststore 설정만 업데이트된다. 개별 브로커 수준에서 단일 alter 요청으로 업데이트할 수 있는 설정은 다음과 같다:

truststore를 수정하려는 리스너가 브로커 간에 사용하는 리스너라면, 새 truststore가 해당 리스너의 기존 keystore를 신뢰하는 경우에만 업데이트를 허용한다. 브로커는 그외 다른 리스너에선 업데이트 전에 신뢰 여부를 검증하지 않는다. 새 truststore에서 클라이언트 인증서 서명에 사용한 CA 인증서를 제거했다면 클라이언트 인증에 실패할 수 있다.

Updating Default Topic Configuration

브로커가 사용할 디폴트 토픽 설정 옵션은 브로커를 다시 시작하지 않아도 업데이트할 수 있다. 토픽별 설정으로 재정의하지 않아도 적용된다. 다음 설정들을 모든 브로커가 사용하는 클러스터 디폴트 레벨로 재정의할 수 있다:

카프카 2.0.0부터는, unclean.leader.election.enable 설정을 동적으로 업데이트하면 컨트롤러에서 자동으로 unclean 리더 선출이 활성화된다. 카프카 1.1.x에선, unclean.leader.election.enable을 바꿔도 새 컨트롤러를 선출할 때만 적용된다. 컨트롤러 재선출은 다음 명령어를 실행하면 강제할 수 있다:

> bin/zookeeper-shell.sh localhost
rmr /controller
Updating Log Cleaner Configs

로그 클리너 설정은 모든 브로커가 사용하는 클러스터 디폴트 레벨에서 동적으로 업데이트할 수 있다. 변경 사항은 다음 회차의 로그 클리닝에 적용된다. 다음 설정들을 업데이트할 수 있다:

Updating Thread Configs

브로커가 사용할 여러 가지 스레드 풀의 크기는 모든 브로커가 사용하는 클러스터 디폴트 레벨에서 동적으로 업데이트할 수 있다. 서비스 중단 없이 설정을 업데이트할 수 있도록 업데이트 범위는 currentSize / 2 ~ currentSize * 2까지로 제한된다.

Updating ConnectionQuota Configs

브로커가 IP/host에 최대로 허용하는 커넥션 수는 모든 브로커가 사용하는 클러스터 디폴트 레벨에서 동적으로 업데이트할 수 있다. 변경 사항은 새 커넥션을 만들 때 적용되며, 기존 커넥션 수도 함께 계산해서 최대치를 제한한다.

Adding and Removing Listeners

리스너는 동적으로 추가하거나 제거할 수 있다. 새 리스너를 추가할 땐, 리스너의 보안 설정은 리스너 프리픽스 listener.name.{listenerName}.을 붙인 설정을 통해 제공해야 한다. 새 리스너가 SASL을 사용한다면, JAAS 설정 프로퍼티 sasl.jaas.config에 listener, 메커니즘 프리픽스를 붙여서 JAAS 설정을 제공해야 한다. 자세한 내용은 카프카 브로커의 JAAS 설정을 참고해라.

카프카 1.1.x에선 브로커 간 리스너는 동적으로 업데이트되지 않을 수도 있다. 브로커 간 리스너를 새 리스너로 업데이트하려면, 새 리스너는 모든 브로커에 브로커 재시작 없이 추가할 수 있을 거다. 그런 다음 inter.broker.listener.name을 업데이트하려면 순차적으로 재시작해야 한다.

새 리스너의 모든 보안 설정 외에, 다음 설정도 개별 브로커 수준에서 동적으로 업데이트할 수 있다.

브로커 간 통신에 사용하는 리스너는 반드시 스태틱 브로커 설정 inter.broker.listener.name이나 security.inter.broker.protocol로 설정해야 한다.


Next :
Topic Configuration
아파치 카프카 공식 문서에 있는 토픽 레벨 설정을 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.

<< >>

TOP