구성 프로바이더

구성 프로바이더 (Configuration Providers)

구성 프로바이더(Configuration Provider)를 쓰면 외부 소스에서 설정 데이터를 불러올 수 있어요. 비밀번호, API 키, 그 밖의 자격 증명(credentials)처럼 민감한 정보를 다룰 때 특히 유용하죠. Kafka 설정 값에 파일·환경변수 같은 외부 데이터를 연결하고 싶을 때 사용하는 기능이에요.

출처: 문서

본문

선택할 수 있는 방법은 두 가지예요.

  • 커스텀 프로바이더 — ConfigProvider 인터페이스를 구현하는 클래스를 만들어 JAR 파일로 패키징해서 사용해요.
  • 내장 프로바이더 — Kafka가 기본 제공하는 프로바이더를 쓰는 거예요.
    • DirectoryConfigProvider
    • EnvVarConfigProvider
    • FileConfigProvider

구성 프로바이더를 사용하려면 설정에서 config.providers 속성으로 지정하면 돼요.

구성 프로바이더 사용하기 (Using Configuration Providers)

구성 프로바이더를 사용하면 파라미터를 전달하고 다양한 소스에서 설정 데이터를 가져올 수 있어요. 프로바이더는 별칭(alias)과 프로바이더를 구현한 완전한 클래스 이름(full-qualified class name)을 쉼표로 구분한 목록으로 지정해요.

config.providers=provider1,provider2
config.providers.provider1.class=com.example.Provider1
config.providers.provider2.class=com.example.Provider2

각 프로바이더는 자신만의 파라미터 집합을 가질 수 있고, 파라미터는 특정 형식으로 전달돼요.

config.providers.<provider_alias>.param.<name>=<value>

ConfigProvider 인터페이스는 모든 구성 프로바이더의 기반이 돼요. 이 인터페이스의 커스텀 구현을 만들어 다양한 소스에서 설정 데이터를 가져올 수 있어요. 구현을 JAR 파일로 패키징해 클래스패스에 추가하고, 설정에서 해당 클래스를 참조하면 돼요.

커스텀 프로바이더 구성 예시:

config.providers=customProvider
config.providers.customProvider.class=com.example.customProvider
config.providers.customProvider.param.param1=value1
config.providers.customProvider.param.param2=value2

DirectoryConfigProvider

DirectoryConfigProvider는 지정된 디렉토리에 저장된 파일들에서 설정 데이터를 가져와요. 파일 하나가 키(key) 하나를 나타내고, 파일 내용이 값(value)이 되는 방식이에요. 여러 설정 파일을 로드하거나 설정 데이터를 개별 파일로 정리할 때 유용해요.

DirectoryConfigProvider가 접근할 수 있는 파일을 제한하려면 allowed.paths 파라미터를 사용해요. 이 파라미터는 프로바이더가 접근할 수 있는 경로 목록을 쉼표로 구분해 받아요. 설정하지 않으면 모든 경로가 허용돼요.

DirectoryConfigProvider 구성 예시:

config.providers=dirProvider
config.providers.dirProvider.class=org.apache.kafka.common.config.provider.DirectoryConfigProvider
config.providers.dirProvider.param.allowed.paths=/path/to/dir1,/path/to/dir2

DirectoryConfigProvider가 제공하는 값을 참조하려면 올바른 플레이스홀더 문법을 사용해요.

${dirProvider:<path_to_file>:<file_name>}

EnvVarConfigProvider

EnvVarConfigProvider는 환경 변수에서 설정 데이터를 가져와요. 지정된 환경 변수에서 직접 읽으므로 특별한 파라미터는 필요 없어요. 주로 컨테이너에서 실행되는 애플리케이션 구성, 예를 들어 시크릿(secret)에서 매핑된 환경 변수로 인증서나 JAAS 구성을 로드할 때 유용해요.

EnvVarConfigProvider가 접근할 수 있는 환경 변수를 제한하려면 allowlist.pattern 파라미터를 사용해요. 이 파라미터는 환경 변수 이름이 일치해야 하는 정규식을 받아요.

EnvVarConfigProvider 구성 예시:

config.providers=envVarProvider
config.providers.envVarProvider.class=org.apache.kafka.common.config.provider.EnvVarConfigProvider
config.providers.envVarProvider.param.allowlist.pattern=^MY_ENVAR1_.*

EnvVarConfigProvider가 제공하는 값을 참조하려면 올바른 플레이스홀더 문법을 사용해요.

${envVarProvider:<enVar_name>}

FileConfigProvider

FileConfigProvider는 단일 properties 파일에서 설정 데이터를 가져와요. 마운트(mount)된 파일에서 설정 데이터를 로드할 때 유용해요.

FileConfigProvider가 접근할 수 있는 파일 경로를 제한하려면 allowed.paths 파라미터를 사용해요. 이 파라미터는 프로바이더가 접근할 수 있는 경로 목록을 쉼표로 구분해 받아요. 설정하지 않으면 모든 경로가 허용돼요.

FileConfigProvider 구성 예시:

config.providers=fileProvider
config.providers.fileProvider.class=org.apache.kafka.common.config.provider.FileConfigProvider
config.providers.fileProvider.param.allowed.paths=/path/to/config1,/path/to/config2

FileConfigProvider가 제공하는 값을 참조하려면 올바른 플레이스홀더 문법을 사용해요.

${fileProvider:<path_and_filename>:<property>}

예시: 파일 참조하기 (Example: Referencing files)

Kafka Connect에서 파일 구성 프로바이더를 사용해 커넥터가 데이터베이스에 인증 자격 증명을 제공하는 예시를 볼게요.

먼저 다음 자격 증명을 담은 connector-credentials.properties 설정 파일을 만들어요.

dbUsername=my-username
dbPassword=my-password

Kafka Connect 설정에 FileConfigProvider를 지정해요.

config.providers=fileProvider
config.providers.fileProvider.class=org.apache.kafka.common.config.provider.FileConfigProvider

그 다음 커넥터 구성에서 파일의 프로퍼티를 참조해요.

database.user=${fileProvider:/path/to/connector-credentials.properties:dbUsername}
database.password=${fileProvider:/path/to/connector-credentials.properties:dbPassword}

런타임에 구성 프로바이더가 properties 파일에서 값을 읽어 추출해요.

더 알아보기 (Learn more)

  • 파일·환경변수 등 외부 소스에서 값을 읽는 세 가지 내장 프로바이더(FileConfigProvider, EnvVarConfigProvider, DirectoryConfigProvider)가 대표적이에요.
  • config.providers 속성으로 프로바이더를 등록하고, ${alias:...} 플레이스홀더로 값을 참조해요.