Admin 설정

Admin 설정 (Admin Configs)

Kafka Admin 클라이언트 라이브러리의 설정 항목들을 정리한 문서예요. 토픽·브로커·ACL 같은 Kafka 객체를 관리·점검하는 Admin 클라이언트는 커넥션, 보안(SSL/SASL/OAuth), 재시도 등을 이 설정으로 제어해요.

출처: 문서

본문

아래는 Kafka Admin 클라이언트 라이브러리 설정 항목들이에요.

• bootstrap.controllers — KRaft 컨트롤러 쿼럼에 초기 연결을 설정하는 데 쓰는 host/port 쌍 목록. 형식은 host1:port1,host2:port2,...이어야 해요.
  • 유형: list / 기본값: "" / 중요도: high
• bootstrap.servers — Kafka 클러스터에 초기 연결을 설정하는 데 쓰는 host/port 쌍 목록. 클라이언트가 이 목록으로 부트스트랩해 전체 Kafka 브로커 집합을 발견해요. 목록의 서버 순서는 상관없지만, 어떤 서버가 다운되더라도 복원력을 위해 두 개 이상의 서버를 포함하는 걸 권장해요. 이 목록에 브로커 전체가 포함될 필요는 없어요 — Kafka 클라이언트가 클러스터 연결을 효율적으로 자동 관리·갱신하거든요. 형식은 host1:port1,host2:port2,...이어야 해요.
  • 유형: list / 기본값: "" / 중요도: high
• ssl.key.password — 키 저장소 파일에 있는 개인 키의 비밀번호, 또는 ssl.keystore.key에 지정된 PEM 키의 비밀번호.
  • 유형: password / 기본값: null / 중요도: high
• ssl.keystore.certificate.chain — ssl.keystore.type이 지정하는 형식의 인증서 체인. 기본 SSL 엔진 팩토리는 X.509 인증서 목록이 있는 PEM 형식만 지원해요.
  • 유형: password / 기본값: null / 중요도: high
• ssl.keystore.key — ssl.keystore.type이 지정하는 형식의 개인 키. 기본 SSL 엔진 팩토리는 PKCS#8 키가 있는 PEM 형식만 지원해요. 키가 암호화된 경우 ssl.key.password로 키 비밀번호를 지정해야 해요.
  • 유형: password / 기본값: null / 중요도: high
• ssl.keystore.location — 키 저장소 파일의 위치. 클라이언트에선 선택 사항이며, 클라이언트의 양방향 인증을 위해 사용할 수 있어요.
  • 유형: string / 기본값: null / 중요도: high
• ssl.keystore.password — 키 저장소 파일의 저장소 비밀번호. 클라이언트에선 선택 사항이며 ssl.keystore.location이 구성된 경우에만 필요해요. PEM 형식은 키 저장소 비밀번호를 지원하지 않아요.
  • 유형: password / 기본값: null / 중요도: high
• ssl.truststore.certificates — ssl.truststore.type이 지정하는 형식의 신뢰할 수 있는 인증서. 기본 SSL 엔진 팩토리는 X.509 인증서가 있는 PEM 형식만 지원해요.
  • 유형: password / 기본값: null / 중요도: high
• ssl.truststore.location — 트러스트 저장소 파일의 위치.
  • 유형: string / 기본값: null / 중요도: high
• ssl.truststore.password — 트러스트 저장소 파일의 비밀번호. 비밀번호를 설정하지 않아도 구성된 트러스트 저장소 파일은 여전히 사용되지만, 무결성 검사는 비활성화돼요. PEM 형식은 트러스트 저장소 비밀번호를 지원하지 않아요.
  • 유형: password / 기본값: null / 중요도: high
• client.dns.lookup — 클라이언트가 DNS 조회를 사용하는 방식을 제어해요. use_all_dns_ips로 설정하면 반환된 각 IP 주소에 순서대로 연결해서 성공할 때까지 시도해요. 연결이 끊기면 다음 IP를 사용해요. 모든 IP를 한 번씩 사용한 뒤에는 호스트 이름에서 IP를 다시 해석해요(다만 JVM과 OS 모두 DNS 이름 조회를 캐시해요). resolve_canonical_bootstrap_servers_only로 설정하면 각 부트스트랩 주소를 정규 이름(Canonical name) 목록으로 해석해요. 부트스트랩 단계 이후에는 use_all_dns_ips와 동일하게 동작해요.
  • 유형: string / 기본값: use_all_dns_ips / 유효 값: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] / 중요도: medium
• client.id — 요청을 만들 때 서버에 전달하는 ID 문자열. 서버 측 요청 로깅에 논리적 애플리케이션 이름을 포함해 ip/port를 넘어 요청의 출처를 추적하기 위한 목적이에요.
  • 유형: string / 기본값: "" / 중요도: medium
• connections.max.idle.ms — 이 구성이 지정하는 밀리초 수가 지난 뒤 유휴 연결을 닫아요.
  • 유형: long / 기본값: 300000 (5분) / 중요도: medium
• default.api.timeout.ms — 클라이언트 API의 타임아웃(밀리초)을 지정해요. timeout 파라미터를 지정하지 않은 모든 클라이언트 작업의 기본 타임아웃으로 사용돼요.
  • 유형: int / 기본값: 60000 (1분) / 유효 값: [0,...] / 중요도: medium
• receive.buffer.bytes — 데이터를 읽을 때 사용하는 TCP 수신 버퍼(SO_RCVBUF) 크기. 값이 -1이면 OS 기본값을 사용해요.
  • 유형: int / 기본값: 65536 (64 kibibytes) / 유효 값: [-1,...] / 중요도: medium
• request.timeout.ms — 클라이언트가 요청의 응답을 기다리는 최대 시간을 제어하는 구성. 타임아웃이 지나기 전에 응답을 받지 못하면 클라이언트는 필요하면 요청을 재전송하고, 재시도가 소진되면 요청을 실패 처리해요.
  • 유형: int / 기본값: 30000 (30초) / 유효 값: [0,...] / 중요도: medium
• sasl.client.callback.handler.class — AuthenticateCallbackHandler 인터페이스를 구현하는 SASL 클라이언트 콜백 핸들러 클래스의 완전한 이름.
  • 유형: class / 기본값: null / 중요도: medium
• sasl.jaas.config — JAAS 구성 파일이 사용하는 형식의 SASL 연결용 JAAS 로그인 컨텍스트 파라미터. JAAS 구성 파일 형식은 여기에 설명되어 있어요. 값 형식은 loginModuleClass controlFlag (optionName=optionValue)*;이에요. 브로커의 경우 구성은 리스너 접두사와 소문자 SASL 메커니즘 이름으로 접두사가 붙어야 해요. 예: listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule required;
  • 유형: password / 기본값: null / 중요도: medium
• sasl.kerberos.service.name — Kafka가 실행되는 Kerberos 주체(principal) 이름. Kafka의 JAAS 구성이나 Kafka 구성에 정의할 수 있어요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.login.callback.handler.class — AuthenticateCallbackHandler 인터페이스를 구현하는 SASL 로그인 콜백 핸들러 클래스의 완전한 이름. 브로커의 경우 로그인 콜백 핸들러 구성은 리스너 접두사와 소문자 SASL 메커니즘 이름으로 접두사가 붙어야 해요. 예: listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
  • 유형: class / 기본값: null / 중요도: medium
• sasl.login.class — Login 인터페이스를 구현하는 클래스의 완전한 이름. 브로커의 경우 로그인 구성은 리스너 접두사와 소문자 SASL 메커니즘 이름으로 접두사가 붙어야 해요. 예: listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
  • 유형: class / 기본값: null / 중요도: medium
• sasl.mechanism — 클라이언트 연결에 사용하는 SASL 메커니즘. 보안 공급자가 있는 어떤 메커니즘이든 될 수 있어요. 기본 메커니즘은 GSSAPI예요.
  • 유형: string / 기본값: GSSAPI / 중요도: medium
• sasl.oauthbearer.assertion.algorithm — Apache Kafka 클라이언트가 아이덴티티 제공자에게 보내는 어서션(assertion)을 서명하는 데 사용할 알고리즘. JWT 어서션의 OAuth alg(Algorithm) 헤더 값으로도 사용돼요. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: RS256 / 유효 값: (대소문자 무시) [ES256, RS256] / 중요도: medium
• sasl.oauthbearer.assertion.claim.aud — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 JWT aud(Audience) 클레임. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.claim.iss — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 iss(Issuer) 클레임으로 사용할 값. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.claim.jti.include — JWT 어서션이 JWT용 고유 ID를 생성해 jti(JWT ID) 클레임에 포함할지 결정하는 플래그. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: boolean / 기본값: false / 중요도: medium
• sasl.oauthbearer.assertion.claim.sub — 로컬에서 만든 클라이언트 JWT 어서션에 포함될 sub(Subject) 클레임으로 사용할 값. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.file — 미리 생성된 JWT 어서션이 들어 있는 파일. 내부 구현은 파일 내용을 캐시해서 접근할 때마다 파일을 로드하는 성능 손실을 피해요. 캐싱 메커니즘은 파일 변경을 감지해 수정 시 파일을 다시 로드할 수 있게 해줘요. 이로써 Kafka 클라이언트를 재시작하지 않고도 "라이브" 어서션 교체가 가능해요. 파일은 직렬화된 3부분 JWT 형식으로 어서션을 담아요: 헤더 섹션은 alg(Algorithm), typ(Type, 항상 리터럴 JWT) 같은 값이 담긴 base 64로 인코딩된 JWT 헤더고, 페이로드 섹션은 aud(Audience), iss(Issuer), sub(Subject) 같은 base 64로 인코딩된 JWT 클레임 집합이며, 서명 섹션은 개인 키로 서명된 헤더·페이로드 섹션의 연결입니다. JWT·JWS 형식의 자세한 내용은 RFC 7519과 RFC 7515를 참고해요. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 다른 모든 sasl.oauthbearer.assertion.* 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.private.key.file — 아이덴티티 제공자에게 보내는 JWT 어서션을 서명하는 데 사용하는, 표준 PEM 형식의 개인 키가 들어 있는 파일. 내부 구현은 파일 내용을 캐시해서 매번 접근할 때마다 파일을 로드하는 성능 손실을 피해요. 캐싱 메커니즘은 파일 변경을 감지해 수정 시 다시 로드할 수 있게 해줘요. 이로써 Kafka 클라이언트를 재시작하지 않고도 "라이브" 개인 키 교체가 가능해요. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.private.key.passphrase — sasl.oauthbearer.assertion.private.key.file이 지정하는 개인 키 파일을 복호화하는 선택적 구문(passphrase). 참고: 런타임에 개인 키 파일이 변경됐는데 이전과 다른 구문으로 만들어졌다면, 클라이언트는 구문이 이제 오래되어(새 값과 불일치) 개인 키 파일에 접근하지 못해요. 그래서 개인 키 구문을 쓸 때는 매번 같은 구문을 쓰거나, 보안을 강화하려면 새 구문 구성으로 Kafka 클라이언트를 재시작해요. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.assertion.template.file — JWT 어서션을 만들 때 사용할 JWT 헤더/페이로드 클레임을 담은 파일을 지정하는 선택적 구성. 모든 아이덴티티 제공자가 같은 클레임 집합을 요구하지는 않아요 — 어떤 제공자는 특정 클레임을 요구하고, 어떤 제공자는 금지할 수도 있어요. 최대한 유연하게 하기 위해 이 구성은 JWT에 포함할 정적 헤더 값과 클레임을 사용자가 제공할 수 있게 해줘요. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.id — 토큰을 요청하는 클라이언트를 식별하는 ID(OAuth 아이덴티티 제공자에서 정의). 이 클라이언트 ID는 이전에 sasl.jaas.config 구성에 clientId 키로 저장됐었어요. 하위 호환성을 위해 clientId JAAS 옵션을 여전히 쓸 수 있지만, 이는 비권장(deprecated)이며 향후 버전에서 제거될 예정이에요. 우선순위: 구성의 sasl.oauthbearer.client.credentials.client.id → JAAS의 clientId.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.client.credentials.client.secret — 토큰을 요청하는 클라이언트의 시크릿(아이덴티티 제공자에 따라 사용자 정의 또는 미리 할당). 이 클라이언트 시크릿은 이전에 sasl.jaas.config 구성에 clientSecret 키로 저장됐었어요. 하위 호환성을 위해 clientSecret JAAS 옵션을 여전히 쓸 수 있지만, 비권장이며 향후 버전에서 제거될 예정이에요. 우선순위: 구성의 sasl.oauthbearer.client.credentials.client.secret → JAAS의 clientSecret.
  • 유형: password / 기본값: null / 중요도: medium
• sasl.oauthbearer.jwks.endpoint.url — 제공자의 JWKS(JSON Web Key Set)를 가져올 수 있는 OAuth/OIDC 제공자 URL. URL은 HTTP(S) 기반이거나 파일 기반일 수 있어요. HTTP(S) 기반이면 브로커 시작 시 구성된 URL로 OAuth/OIDC 제공자에서 JWKS 데이터를 가져와요. 그 당시의 모든 키가 브로커에 캐시되고 들어오는 요청에 사용돼요. 아직 캐시에 없는 kid 헤더 클레임 값을 가진 JWT에 대한 인증 요청을 받으면 JWKS 엔드포인트를 필요 시 다시 조회해요. 다만 브로커는 sasl.oauthbearer.jwks.endpoint.refresh.ms 밀리초마다 URL을 폴링해서, 키를 포함한 JWT 요청을 받기 전에 향후 키로 캐시를 갱신해요. 파일 기반이면 브로커는 시작 시 구성된 위치에서 JWKS 파일을 로드해요. JWT에 JWKS 파일에 없는 kid 헤더 값이 포함된 경우 브로커는 JWT를 거부하고 인증이 실패해요.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.jwt.retriever.class — 아이덴티티 제공자에게 토큰을 요청하는 데 사용하는 JwtRetriever 구현 클래스의 완전한 이름. 기본 구성 값은 이전 Apache Kafka 버전과 하위 호환을 유지하는 클래스를 나타내요. 기본 구현은 구성을 사용해 어떤 구체적 구현을 만들지 결정해요. 제공되는 다른 구현: org.apache.kafka.common.security.oauthbearer.ClientCredentialsJwtRetriever, org.apache.kafka.common.security.oauthbearer.DefaultJwtRetriever, org.apache.kafka.common.security.oauthbearer.FileJwtRetriever, org.apache.kafka.common.security.oauthbearer.JwtBearerJwtRetriever.
  • 유형: class / 기본값: org.apache.kafka.common.security.oauthbearer.DefaultJwtRetriever / 중요도: medium
• sasl.oauthbearer.jwt.validator.class — 아이덴티티 제공자의 JWT를 검증하는 데 사용하는 JwtValidator 구현 클래스의 완전한 이름. 기본 검증기(org.apache.kafka.common.security.oauthbearer.DefaultJwtValidator)는 이전 Apache Kafka 버전과 하위 호환을 유지해요. 기본 검증기는 구성을 사용해 어떤 구체적 구현을 만들지 결정해요. 내장 JwtValidator 구현: org.apache.kafka.common.security.oauthbearer.BrokerJwtValidator, org.apache.kafka.common.security.oauthbearer.ClientJwtValidator, org.apache.kafka.common.security.oauthbearer.DefaultJwtValidator.
  • 유형: class / 기본값: org.apache.kafka.common.security.oauthbearer.DefaultJwtValidator / 중요도: medium
• sasl.oauthbearer.scope — 클라이언트 애플리케이션이 리소스/API에 부여받는 접근 수준이며 토큰 요청에 포함돼요. 제공하면 아이덴티티 제공자에 구성된 하나 이상의 scope와 일치해야 해요. 이 scope는 이전에 sasl.jaas.config 구성에 scope 키로 저장됐었어요. 하위 호환성을 위해 scope JAAS 옵션을 여전히 쓸 수 있지만, 비권장이며 향후 버전에서 제거될 예정이에요. 우선순위: 구성의 sasl.oauthbearer.scope → JAAS의 scope.
  • 유형: string / 기본값: null / 중요도: medium
• sasl.oauthbearer.token.endpoint.url — OAuth/OIDC 아이덴티티 제공자 URL. HTTP(S) 기반이면 sasl.oauthbearer.jwt.retriever.class의 구성에 따라 로그인하기 위해 요청할 발급자(issuer)의 토큰 엔드포인트 URL이에요. 파일 기반이면 OAuth/OIDC 아이덴티티 제공자가 발급한 접근 토큰(직렬화된 JWT 형태)을 담은 파일을 지정해서 인가에 사용해요.
  • 유형: string / 기본값: null / 중요도: medium
• security.protocol — 브로커와 통신할 때 사용하는 프로토콜.
  • 유형: string / 기본값: PLAINTEXT / 유효 값: (대소문자 무시) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] / 중요도: medium
• send.buffer.bytes — 데이터를 보낼 때 사용하는 TCP 송신 버퍼(SO_SNDBUF) 크기. 값이 -1이면 OS 기본값을 사용해요.
  • 유형: int / 기본값: 131072 (128 kibibytes) / 유효 값: [-1,...] / 중요도: medium
• socket.connection.setup.timeout.max.ms — 클라이언트가 소켓 연결이 설정되기를 기다리는 최대 시간. 연결 설정 타임아웃은 각 연속 연결 실패마다 지수적으로 증가해 이 최대값까지 올라가요. 연결 폭풍을 피하려고 타임아웃에 0.2의 무작위화 요인이 적용돼 계산값의 20% 아래부터 20% 위 사이의 무작위 범위가 돼요.
  • 유형: long / 기본값: 30000 (30초) / 중요도: medium
• socket.connection.setup.timeout.ms — 클라이언트가 소켓 연결이 설정되기를 기다리는 시간. 타임아웃이 지나기 전에 연결이 만들어지지 않으면 클라이언트는 소켓 채널을 닫아요. 이 값은 초기 백오프 값이며 각 연속 연결 실패마다 지수적으로 증가해 socket.connection.setup.timeout.max.ms 값까지 올라가요.
  • 유형: long / 기본값: 10000 (10초) / 중요도: medium
• ssl.enabled.protocols — SSL 연결에 활성화된 프로토콜 목록. 기본값은 TLSv1.2,TLSv1.3이에요. 즉 클라이언트와 서버는 둘 다 TLSv1.3을 지원하면 TLSv1.3을 선호하고, 그렇지 않으면(둘 다 최소 TLSv1.2를 지원한다고 가정) TLSv1.2로 폴백해요. 이 기본값은 대부분의 용도에 적합해요. 이 구성이 빈 목록으로 설정되면 Kafka는 기본 SSLEngine에서 기본으로 활성화된 프로토콜을 사용하는데, JVM 버전에 따라 추가 프로토콜이 포함될 수 있어요. TLS 버전 협상 동작에 어떤 영향을 미칠 수 있는지 이해하려면 ssl.protocol 구성 문서도 참고해요.
  • 유형: list / 기본값: TLSv1.2,TLSv1.3 / 중요도: medium
• ssl.keystore.type — 키 저장소 파일의 파일 형식. 클라이언트에선 선택 사항이에요. 기본 ssl.engine.factory.class가 현재 지원하는 값은 [JKS, PKCS12, PEM]이에요.
  • 유형: string / 기본값: JKS / 중요도: medium
• ssl.protocol — SSLContext를 생성할 때 사용하는 SSL 프로토콜. 기본값은 TLSv1.3으로 대부분의 용도에 적합해요. 기본값의 일반적인 대안은 TLSv1.2예요. 이 구성의 허용 값은 JVM에 따라 달라요. 이 구성과 ssl.enabled.protocols의 기본값을 쓰는 클라이언트는 서버가 TLSv1.3을 지원하지 않으면 TLSv1.2로 다운그레이드해요. 다만 이 구성이 TLSv1.2로 설정되면, ssl.enabled.protocols 값 중 하나이고 서버가 TLSv1.3만 지원해도 클라이언트는 TLSv1.3을 사용하지 않아요.
  • 유형: string / 기본값: TLSv1.3 / 중요도: medium
• ssl.provider — SSL 연결에 사용하는 보안 공급자 이름. 기본값은 JVM의 기본 보안 공급자예요.
  • 유형: string / 기본값: null / 중요도: medium
• ssl.truststore.type — 트러스트 저장소 파일의 파일 형식. 기본 ssl.engine.factory.class가 현재 지원하는 값은 [JKS, PKCS12, PEM]이에요.
  • 유형: string / 기본값: JKS / 중요도: medium
• config.providers — ConfigProvider 인터페이스를 구현하는 클래스의 쉼표로 구분된 별칭 이름. 외부 소스(비밀번호, API 키, 기타 자격 증명)에서 구성 데이터를 로드할 수 있게 해줘요. 예를 들어 Configuration Providers를 참고해요.
  • 유형: list / 기본값: "" / 중요도: low
• enable.metrics.push — 클러스터에 이 클라이언트와 일치하는 클라이언트 지표 구독이 있는 경우, 클라이언트 지표를 클러스터로 푸시할지 여부.
  • 유형: boolean / 기본값: false / 중요도: low
• metadata.max.age.ms — 파티션 리더십 변경을 보지 못했더라도 새 브로커나 파티션을 능동적으로 발견하기 위해 메타데이터 갱신을 강제하는 시간(밀리초).
  • 유형: long / 기본값: 300000 (5분) / 유효 값: [0,...] / 중요도: low
• metadata.recovery.rebootstrap.trigger.ms — metadata.recovery.strategy=rebootstrap로 구성된 클라이언트가 이 간격 동안 마지막으로 알려진 메타데이터의 어떤 브로커에서도 메타데이터를 얻지 못하면, 클라이언트가 bootstrap.servers 구성을 사용해 부트스트랩 과정을 반복해요.
  • 유형: long / 기본값: 300000 (5분) / 유효 값: [0,...] / 중요도: low
• metadata.recovery.strategy — 클라이언트가 아는 브로커 중 아무것도 사용할 수 없을 때 어떻게 복구할지 제어해요. none으로 설정하면 클라이언트가 실패해요. rebootstrap으로 설정하면 bootstrap.servers를 사용해 부트스트랩 과정을 반복해요. 리부트스트랩은 클라이언트가 브로커와 통신하는 빈도가 너무 낮아서 메타데이터를 갱신하기 전에 브로커 집합이 완전히 바뀔 수 있을 때 유용해요. 마지막으로 알려진 브로커들이 동시에 사용할 수 없어 보일 때 메타데이터 복구가 트리거돼요. 브로커는 연결이 끊어지고 진행 중인 재시도가 없을 때 사용할 수 없는 것으로 보여요. reconnect.backoff.ms·reconnect.backoff.max.ms를 늘리고 socket.connection.setup.timeout.ms·socket.connection.setup.timeout.max.ms를 줄이는 것을 고려해요. metadata.recovery.rebootstrap.trigger.ms 밀리초 동안 어떤 브로커에도 연결을 설정할 수 없거나 서버가 리부트스트랩을 요청하면 리부트스트랩이 트리거돼요.
  • 유형: string / 기본값: rebootstrap / 유효 값: (대소문자 무시) [REBOOTSTRAP, NONE] / 중요도: low
• metric.reporters — 지표 리포터로 사용할 클래스 목록. org.apache.kafka.common.metrics.MetricsReporter 인터페이스를 구현하면 새 지표 생성 시 알림을 받을 클래스를 끼워 넣을 수 있어요. 커스텀 리포터를 설정할 때 org.apache.kafka.common.metrics.JmxReporter가 필요하면 목록에 명시적으로 추가해야 해요.
  • 유형: list / 기본값: org.apache.kafka.common.metrics.JmxReporter / 중요도: low
• metrics.num.samples — 지표를 계산하기 위해 유지하는 샘플 수.
  • 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: low
• metrics.recording.level — 지표의 최고 기록 수준. info, debug, trace 세 단계가 있어요. INFO는 시스템 성능·건강 모니터링에 필요한 필수 지표만 기록해 최소 오버헤드를 원하는 프로덕션 환경에 적합해요. DEBUG는 대부분의 지표를 기록해 디버깅·튜닝에 유용한 개발·테스트 환경에 좋아요. TRACE는 가능한 모든 지표를 기록해 심층 분석이 필요한 통제된 환경에 가장 좋지만 상당한 오버헤드를 도입할 수 있어요.
  • 유형: string / 기본값: INFO / 유효 값: [INFO, DEBUG, TRACE] / 중요도: low
• metrics.sample.window.ms — 지표 샘플이 계산되는 시간 창.
  • 유형: long / 기본값: 30000 (30초) / 유효 값: [0,...] / 중요도: low
• reconnect.backoff.max.ms — 반복적으로 연결 실패한 브로커에 재연결할 때 기다리는 최대 시간(밀리초). 제공되면 호스트별 백오프가 각 연속 연결 실패마다 지수적으로 증가해 이 최대값까지 올라가요. 백오프 증가를 계산한 뒤 연결 폭풍을 피하려고 20%의 무작위 지터가 추가돼요.
  • 유형: long / 기본값: 1000 (1초) / 유효 값: [0,...] / 중요도: low
• reconnect.backoff.ms — 주어진 호스트에 재연결을 시도하기 전에 기다리는 기본 시간. 호스트에 빡빡한 루프로 계속 연결하는 걸 피해요. 이 백오프는 클라이언트가 브로커에 하는 모든 연결 시도에 적용돼요. 초기 백오프 값이며 각 연속 연결 실패마다 지수적으로 증가해 reconnect.backoff.max.ms 값까지 올라가요.
  • 유형: long / 기본값: 50 / 유효 값: [0,...] / 중요도: low
• retries — MAX_VALUE나 0으로 설정하고, 클라이언트가 요청을 얼마나 오래 재시도할지 제어하는 해당 타임아웃 파라미터를 사용하는 걸 권장해요. 0보다 큰 값을 설정하면 잠재적으로 일시적인 오류로 실패한 요청을 클라이언트가 재전송해요. 0으로 설정하면 일시적 오류가 재시도되지 않고 애플리케이션으로 전파되어 처리돼요.
  • 유형: int / 기본값: 2147483647 / 유효 값: [0,...,2147483647] / 중요도: low
• retry.backoff.max.ms — 반복적으로 실패한 브로커에 요청을 재시도할 때 기다리는 최대 시간(밀리초). 제공되면 클라이언트별 백오프가 각 실패 요청마다 지수적으로 증가해 이 최대값까지 올라가요. 재시도 시 모든 클라이언트가 동기화되는 걸 막으려고 0.2 요인의 무작위 지터가 백오프에 적용돼, 백오프가 계산값의 20% 아래부터 20% 위 사이 범위에 들어가요. retry.backoff.ms가 retry.backoff.max.ms보다 높게 설정되면 retry.backoff.max.ms가 처음부터 지수 증가 없이 상수 백오프로 사용돼요.
  • 유형: long / 기본값: 1000 (1초) / 유효 값: [0,...] / 중요도: low
• retry.backoff.ms — 주어진 토픽 파티션에 실패한 요청을 재시도하기 전에 기다리는 시간. 특정 실패 시나리오에서 빡빡한 루프로 요청을 계속 보내는 걸 피해요. 초기 백오프 값이며 각 실패 요청마다 지수적으로 증가해 retry.backoff.max.ms 값까지 올라가요.
  • 유형: long / 기본값: 100 / 유효 값: [0,...] / 중요도: low
• sasl.kerberos.kinit.cmd — Kerberos kinit 명령 경로.
  • 유형: string / 기본값: /usr/bin/kinit / 중요도: low
• sasl.kerberos.min.time.before.relogin — 갱신 시도 사이의 로그인 스레드 수면 시간.
  • 유형: long / 기본값: 60000 / 중요도: low
• sasl.kerberos.ticket.renew.jitter — 갱신 시간에 더하는 무작위 지터 비율.
  • 유형: double / 기본값: 0.05 / 중요도: low
• sasl.kerberos.ticket.renew.window.factor — 로그인 스레드는 마지막 갱신 이후 티켓 만료까지의 시간의 지정된 윈도우 요인에 도달할 때까지 수면하고, 그때 티켓을 갱신하려 시도해요.
  • 유형: double / 기본값: 0.8 / 중요도: low
• sasl.login.connect.timeout.ms — 외부 인증 제공자 연결 타임아웃(밀리초)의 (선택적) 값. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: int / 기본값: null / 중요도: low
• sasl.login.read.timeout.ms — 외부 인증 제공자 읽기 타임아웃(밀리초)의 (선택적) 값. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: int / 기본값: null / 중요도: low
• sasl.login.refresh.buffer.seconds — 자격 증명을 갱신할 때 만료 전에 유지하는 버퍼 시간(초). 갱신이 버퍼 초 수보다 만료에 가깝게 일어나야 한다면 갱신을 앞당겨 버퍼 시간을 가능한 한 유지해요. 허용 값은 0~3600(1시간)이고, 지정하지 않으면 기본값 300(5분)이 사용돼요. 이 값과 sasl.login.refresh.min.period.seconds의 합이 자격 증명의 남은 수명을 초과하면 둘 다 무시돼요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: short / 기본값: 300 / 유효 값: [0,...,3600] / 중요도: low
• sasl.login.refresh.min.period.seconds — 로그인 갱신 스레드가 자격 증명을 갱신하기 전에 기다리는 원하는 최소 시간(초). 허용 값은 0~900(15분)이고, 지정하지 않으면 기본값 60(1분)이 사용돼요. 이 값과 sasl.login.refresh.buffer.seconds의 합이 자격 증명의 남은 수명을 초과하면 둘 다 무시돼요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: short / 기본값: 60 / 유효 값: [0,...,900] / 중요도: low
• sasl.login.refresh.window.factor — 로그인 갱신 스레드는 자격 증명 수명에 상대적인 지정된 윈도우 요인에 도달할 때까지 수면하고, 그때 자격 증명을 갱신하려 시도해요. 허용 값은 0.5(50%)~1.0(100%) 포함이고, 지정하지 않으면 기본값 0.8(80%)이 사용돼요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: double / 기본값: 0.8 / 유효 값: [0.5,...,1.0] / 중요도: low
• sasl.login.refresh.window.jitter — 로그인 갱신 스레드의 수면 시간에 더하는, 자격 증명 수명에 상대적인 최대 무작위 지터. 허용 값은 0~0.25(25%) 포함이고, 지정하지 않으면 기본값 0.05(5%)가 사용돼요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: double / 기본값: 0.05 / 유효 값: [0.0,...,0.25] / 중요도: low
• sasl.login.retry.backoff.max.ms — 외부 인증 제공자에 대한 로그인 시도 사이의 최대 대기(밀리초)의 (선택적) 값. 로그인은 sasl.login.retry.backoff.ms 설정에 기반한 초기 대기로 지수 백오프 알고리즘을 사용하고, sasl.login.retry.backoff.max.ms 설정이 지정하는 최대 대기 길이까지 시도 사이 대기가 두 배로 늘어나요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: long / 기본값: 10000 (10초) / 중요도: low
• sasl.login.retry.backoff.ms — 외부 인증 제공자에 대한 로그인 시도 사이의 초기 대기(밀리초)의 (선택적) 값. 로그인은 sasl.login.retry.backoff.ms 설정에 기반한 초기 대기로 지수 백오프 알고리즘을 사용하고, 시도 사이 대기가 최대 대기 길이까지 두 배로 늘어나요. 현재 OAUTHBEARER에만 적용돼요.
  • 유형: long / 기본값: 100 / 중요도: low
• sasl.oauthbearer.assertion.claim.exp.seconds — JWT가 유효한 미래의 초 수. JWT가 생성될 때 현재 시스템 시간을 기준으로 exp(Expiration) 클레임을 결정하는 데 사용돼요. 공식은 간단해요: x = 클라이언트의 현재 타임스탬프(초), y = 이 구성의 값일 때 exp = x + y. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: int / 기본값: 300 / 유효 값: [0,...,86400] / 중요도: low
• sasl.oauthbearer.assertion.claim.nbf.seconds — JWT가 유효한 과거의 초 수. JWT가 생성될 때 현재 시스템 시간을 기준으로 nbf(Not Before) 클레임을 결정하는 데 사용돼요. 공식은 간단해요: x = 클라이언트의 현재 타임스탬프(초), y = 이 구성의 값일 때 nbf = x - y. 참고: sasl.oauthbearer.assertion.file 값이 제공되면 이 구성은 무시돼요.
  • 유형: int / 기본값: 60 / 유효 값: [0,...,3600] / 중요도: low
• sasl.oauthbearer.clock.skew.seconds — OAuth/OIDC 아이덴티티 제공자와 브로커 사이의 시간 차이를 허용할 (선택적) 값(초).
  • 유형: int / 기본값: 30 / 중요도: low
• sasl.oauthbearer.expected.audience — 브로커가 JWT가 예상 audience 중 하나에 대해 발급됐는지 검증하는 데 사용할 (선택적) 쉼표로 구분된 설정. JWT에서 표준 OAuth aud 클레임을 검사하고, 이 값이 설정되면 브로커가 JWT의 aud 클레임 값에 정확히 일치하는 값이 있는지 확인해요. 일치하지 않으면 브로커는 JWT를 거부하고 인증이 실패해요.
  • 유형: list / 기본값: "" / 중요도: low
• sasl.oauthbearer.expected.issuer — 브로커가 JWT가 예상 발급자에 의해 생성됐는지 검증하는 데 사용할 (선택적) 설정. JWT에서 표준 OAuth iss 클레임을 검사하고, 이 값이 설정되면 JWT의 iss 클레임과 정확히 일치하는지 확인해요. 일치하지 않으면 브로커는 JWT를 거부하고 인증이 실패해요.
  • 유형: string / 기본값: null / 중요도: low
• sasl.oauthbearer.header.urlencode — OAuth 클라이언트가 RFC6749에 따라 인가 헤더에서 client_id와 client_secret을 URL 인코딩하게 할지 여부를 활성화하는 (선택적) 설정. 자세한 내용은 여기를 참고해요. 하위 호환성을 위해 기본값은 false로 설정돼요.
  • 유형: boolean / 기본값: false / 중요도: low
• sasl.oauthbearer.jwks.endpoint.refresh.ms — JWT 서명을 검증하는 데 쓰는 키가 담긴 JWKS(JSON Web Key Set) 캐시를 갱신하는 사이에 브로커가 기다리는 (선택적) 값(밀리초).
  • 유형: long / 기본값: 3600000 (1시간) / 중요도: low
• sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms — 외부 인증 제공자에서 JWKS(JSON Web Key Set)를 가져오는 시도 사이의 최대 대기(밀리초)의 (선택적) 값. JWKS 조회는 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 설정에 기반한 초기 대기로 지수 백오프 알고리즘을 사용하고, 시도 사이 대기가 최대 대기 길이까지 두 배로 늘어나요.
  • 유형: long / 기본값: 10000 (10초) / 중요도: low
• sasl.oauthbearer.jwks.endpoint.retry.backoff.ms — 외부 인증 제공자에서 JWKS(JSON Web Key Set) 조회 시도 사이의 초기 대기(밀리초)의 (선택적) 값. JWKS 조회는 이 설정에 기반한 초기 대기로 지수 백오프 알고리즘을 사용하고, 시도 사이 대기가 최대 대기 길이까지 두 배로 늘어나요.
  • 유형: long / 기본값: 100 / 중요도: low
• sasl.oauthbearer.scope.claim.name — scope의 OAuth 클레임은 흔히 scope로 불리지만, OAuth/OIDC 제공자가 그 클레임에 다른 이름을 쓰면 이 (선택적) 설정으로 JWT 페이로드 클레임에 포함할 scope의 다른 이름을 제공할 수 있어요.
  • 유형: string / 기본값: scope / 중요도: low
• sasl.oauthbearer.sub.claim.name — subject의 OAuth 클레임은 흔히 sub로 불리지만, OAuth/OIDC 제공자가 그 클레임에 다른 이름을 쓰면 이 (선택적) 설정으로 JWT 페이로드 클레임에 포함할 subject의 다른 이름을 제공할 수 있어요.
  • 유형: string / 기본값: sub / 중요도: low
• security.providers — 각각 보안 알고리즘을 구현하는 공급자를 반환하는, 구성 가능한 creator 클래스 목록. 이 클래스들은 org.apache.kafka.common.security.auth.SecurityProviderCreator 인터페이스를 구현해야 해요.
  • 유형: string / 기본값: null / 중요도: low
• ssl.cipher.suites — 암호 스위트 목록. TLS/SSL 네트워크 프로토콜을 사용한 네트워크 연결의 보안 설정을 협상하는 데 사용하는 인증·암호화·MAC·키 교환 알고리즘의 명명된 조합이에요. 기본적으로 사용 가능한 모든 암호 스위트가 지원돼요.
  • 유형: list / 기본값: "" / 중요도: low
• ssl.endpoint.identification.algorithm — 서버 인증서로 서버 호스트 이름을 검증하는 엔드포인트 식별 알고리즘.
  • 유형: string / 기본값: https / 중요도: low
• ssl.engine.factory.class — SSLEngine 객체를 제공하는 org.apache.kafka.common.security.auth.SslEngineFactory 유형의 클래스. 기본값은 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory예요. 또는 org.apache.kafka.common.security.ssl.CommonNameLoggingSslEngineFactory로 설정하면 mTLS 클라이언트가 브로커에 인증할 때 사용하는 만료된 SSL 인증서의 공통 이름(common name)을 INFO 로그 레벨로 기록해요. 참고로 이건 클라이언트가 제공한 인증서 체인을 검사하는 추가 코드 때문에 mTLS 클라이언트에서 브로커로의 새 연결 설정 시 약간의 지연을 일으켜요. 또한 이 구현은 표준 Java 트러스트스토어에 기반한 커스텀 트러스트스토어를 사용하므로 표준 트러스트스토어만큼 성숙하지 않아 보안 위험이 될 수 있다고 간주될 수 있어요.
  • 유형: class / 기본값: null / 중요도: low
• ssl.keymanager.algorithm — SSL 연결을 위해 키 매니저 팩토리가 사용하는 알고리즘. 기본값은 Java 가상 머신에 구성된 키 매니저 팩토리 알고리즘.
  • 유형: string / 기본값: SunX509 / 중요도: low
• ssl.secure.random.implementation — SSL 암호화 작업에 사용할 SecureRandom PRNG 구현.
  • 유형: string / 기본값: null / 중요도: low
• ssl.trustmanager.algorithm — SSL 연결을 위해 트러스트 매니저 팩토리가 사용하는 알고리즘. 기본값은 Java 가상 머신에 구성된 트러스트 매니저 팩토리 알고리즘.
  • 유형: string / 기본값: PKIX / 중요도: low

더 알아보기 (Learn more)

• Admin 클라이언트는 bootstrap.servers(또는 KRaft에선 bootstrap.controllers)로 시작점을 잡아요.
• 보안 관련 항목(SSL/SASL/OAuth)이 많아서, TLS를 쓴다면 ssl.*, OAUTHBEARER 인증을 쓴다면 sasl.oauthbearer.*를 중심으로 확인하면 돼요.