Spring Cloud Azure Kafka 지원

적용 대상: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Spring Cloud Azure Kafka 지원은 Spring 애플리케이션이 OAuth 자격 증명 또는 연결 문자열을 사용하여 Azure Event Hubs 인증하고 연결하는 데 도움이 됩니다. 이 문서에서는 지원되는 인증 유형, 구성 옵션, 종속성 및 사용 시나리오에 대해 설명합니다.

지원되는 Kafka 버전

현재 버전의 스타터는 Apache Kafka Clients 2.0.0과 호환되며 Java 8 이상에서 사용됩니다.

지원되는 인증 유형

스타터는 다음 인증 유형을 지원합니다:

일반 연결 문자열 인증
- 직접 연결 문자열 인증
- ARM 기반 연결 문자열 인증
OAuth 자격 증명 인증
- 관리 ID 인증
- 사용자 이름/암호 인증
- 서비스 주체 인증
- DefaultAzureCredential 인증

작동 방식

OAuth 자격 증명 인증

이 섹션에서는 Spring Cloud Azure OAuth 인증의 전체 워크플로에 대해 설명합니다.

Spring Cloud Azure 먼저 애플리케이션 인증 구성에 따라 다음 유형의 자격 증명 중 하나를 빌드합니다.

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

애플리케이션이 이러한 유형의 자격 증명 중 하나를 사용하지 않는 경우 애플리케이션은 자격 증명 체인 DefaultAzureTokenCredential 을 사용하여 애플리케이션 속성, 환경 변수, 관리 ID 또는 IDE에서 자격 증명을 가져옵니다. 자세한 내용은 Spring Cloud Azure 인증참조하세요.

일반 연결 문자열 인증

연결 문자열 인증 모드의 경우 연결 문자열 인증을 직접 사용하거나 Azure Resource Manager를 사용하여 연결 문자열을 검색할 수 있습니다. 사용량에 대한 자세한 내용은 연결 문자열 인증 섹션에 대한 기본 사용을 참조하세요.

메모

버전 4.3.0부터 연결 문자열 인증은 OAuth 인증을 위해 더 이상 사용되지 않습니다.

구성

OAuth 인증에서 Kafka 지원을 사용하는 경우 구성 가능한 속성

Spring Cloud Azure for Kafka는 다음 두 가지 수준의 구성 옵션을 지원합니다.

Event Hubs Kafka 속성용 Spring Cloud Azure.
spring.cloud.azure 접두사가 있는 credential 및 profile의 전역 인증 구성 옵션입니다.
Kafka 관련 수준 구성. Kafka 수준 구성은 접두사가 다른 common, consumer, producer또는 admin 범위에 대한 Spring Boot 및 Spring Cloud Stream 바인더에도 사용할 수 있습니다.

전역 속성은 com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties통해 노출됩니다. Kafka 관련 속성은 org.springframework.boot.autoconfigure.kafka.KafkaProperties(Spring Boot) 및 org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties(Spring Cloud Stream 바인더)를 통해 노출됩니다.

다음 목록에는 지원되는 모든 구성 옵션이 나와 있습니다.

Event Hubs용 Spring Cloud Azure Kafka 속성
- 속성: spring.cloud.azure.eventhubs.kafka.enabled
- 설명: Kafka용 Azure Event Hubs에 대한 자격 증명 무료 연결을 사용하도록 설정할지 여부는 기본값이 true.
Spring Cloud Azure 전역 인증 구성 옵션
- 접두사: spring.cloud.azure
- 지원되는 옵션: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*
전역 구성 옵션의 전체 목록은전역 구성 속성을 참조하세요.
Spring Boot Kafka 일반 구성
- 접두사: spring.kafka.properties.azure
- 예: spring.kafka.properties.azure.credential.*
Spring Kafka 소비자 구성 옵션
- 접두사: spring.kafka.consumer.properties.azure
- 예: spring.kafka.consumer.properties.azure.credential.*
Spring Kafka 생산자 구성 옵션
- 접두사: spring.kafka.producer.properties.azure
- 예: spring.kafka.producer.properties.azure.credential.*
Spring Kafka 관리 구성 옵션
- 접두사: spring.kafka.admin.properties.azure
- 예: spring.kafka.admin.properties.azure.credential.*
Spring Cloud Stream Kafka 바인더 일반 구성
- 접두사: spring.cloud.stream.kafka.binder.configuration.azure
- 예: spring.cloud.stream.kafka.binder.configuration.azure.credential.*
Spring Cloud Stream Kafka Binder 컨슈머 구성
- 접두사: spring.cloud.stream.kafka.binder.consumer-properties.azure
- 예: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*
Spring Cloud Stream Kafka Binder 프로듀서 설정
- 접두사: spring.cloud.stream.kafka.binder.producer-properties.azure
- 예: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*
Spring Cloud Stream Kafka Binder 관리자 구성
- 접두사: 지원되지 않습니다. Spring Boot Kafka 일반 또는 관리자 구성을 사용합니다.

다음 표에서는 Spring Boot Kafka 일반 구성 옵션을 보여줍니다.

이름	설명
`spring.kafka.properties.azure.credential.client-certificate-password`	인증서 파일의 암호입니다.
`spring.kafka.properties.azure.credential.client-certificate-path`	Azure에서 서비스 주체 인증을 수행할 때 사용할 PEM 인증서 파일의 경로입니다.
`spring.kafka.properties.azure.credential.client-id`	Azure에서 서비스 주체 인증을 수행할 때 사용할 클라이언트 ID입니다. 레거시 속성입니다.
`spring.kafka.properties.azure.credential.client-secret`	Azure에서 서비스 주체 인증을 수행할 때 사용할 클라이언트 암호입니다. 레거시 속성입니다.
`spring.kafka.properties.azure.credential.managed-identity-enabled`	관리 ID가 Azure로 인증되도록 설정할지 여부입니다. `true` `client-id` 설정되면 클라이언트 ID는 사용자가 할당한 관리 ID 클라이언트 ID입니다. 기본값은 `false`.
`spring.kafka.properties.azure.credential.password`	Azure에서 사용자 이름/암호 인증을 수행할 때 사용할 암호입니다.
`spring.kafka.properties.azure.credential.username`	Azure에서 사용자 이름/암호 인증을 수행할 때 사용할 사용자 이름입니다.
`spring.kafka.properties.azure.profile.environment.active-directory-endpoint`	연결할 Microsoft Entra 엔드포인트입니다.
`spring.kafka.properties.azure.profile.tenant-id`	Azure 리소스에 대한 테넌트 ID입니다. `tenant-id` 허용되는 값은 `common`, `organizations`, `consumers`또는 테넌트 ID입니다.

메모

다양한 수준의 구성 옵션은 다음 규칙을 적용합니다. 더 구체적인 구성 옵션은 일반적인 옵션보다 우선 순위가 높습니다. 예를 들어:

Spring Kafka 일반 구성 옵션은 전역 옵션을 대체합니다.
Spring Kafka 소비자 구성 옵션은 일반적인 옵션을 대체합니다.
Spring Kafka 생산자 구성 옵션은 일반적인 옵션을 대체합니다.
Spring Kafka 관리 구성 옵션은 일반적인 옵션을 대체합니다.
Spring Cloud Stream Kafka 바인더 옵션은 동일한 패턴을 따릅니다.

일반 연결 문자열 인증과 함께 Kafka 지원을 사용하는 경우 구성 가능한 속성

다음 표에서는 Kafka용 Spring Boot Event Hubs 일반 구성 옵션을 보여 줍니다.

재산	설명
`spring.cloud.azure.eventhubs.kafka.enabled`	Azure Event Hubs Kafka 지원을 사용하도록 설정할지 여부입니다. 기본값은 `true`.
`spring.cloud.azure.eventhubs.connection-string`	Azure Event Hubs 연결 문자열입니다. 연결 문자열을 직접 제공하려는 경우 이 값을 제공합니다.
`spring.cloud.azure.eventhubs.namespace`	Azure Event Hubs 네임스페이스. Azure Resource Manager를 통해 연결 정보를 검색하려는 경우 이 값을 제공합니다.
`spring.cloud.azure.eventhubs.resource.resource-group`	Azure Event Hubs 네임스페이스의 리소스 그룹입니다. Azure Resource Manager를 통해 연결 정보를 검색하려는 경우 이 값을 제공합니다.
`spring.cloud.azure.profile.subscription-id`	구독 ID입니다. Azure Resource Manager를 통해 연결 정보를 검색하려는 경우 이 값을 제공합니다.

종속성 설정

프로젝트에 다음 종속성을 추가합니다. 이 종속성은 프로젝트에 spring-boot-starter 종속성을 자동으로 포함합니다.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

메모

이전 종속성과 함께 BOM spring-cloud-azure-dependencies 을 추가해야 합니다. 자세한 내용은 Spring Cloud Azure 개발자 가이드 시작 섹션을 참조하세요.

기본 사용량

다음 섹션에서는 클래식 Spring Boot 애플리케이션 사용 시나리오를 보여 줍니다.

OAuth 인증 사용

Spring Cloud Azure Kafka에 제공하는 OAuth 인증을 사용하는 경우 이전 구성을 사용하여 특정 자격 증명을 구성할 수 있습니다. 또는 자격 증명을 구성하지 않도록 선택할 수 있습니다. 이 경우 Spring Cloud Azure 환경에서 자격 증명을 로드합니다. 이 섹션에서는 Azure CLI 환경 또는 Azure Spring Apps 호스팅 환경에서 자격 증명을 로드하는 방법을 설명합니다.

메모

보안 주체를 사용하여 Azure 리소스에 액세스하기 위한 Microsoft Entra ID 인증하고 권한을 부여하도록 선택한 경우 보안 주체가 Azure 리소스에 액세스할 수 있는 충분한 권한이 있는지 확인하려면 Microsoft Entra ID 섹션을 사용하여 액세스 권한 부여 섹션을 참조하세요.

다음 섹션에서는 OAuth 인증과 함께 다양한 Spring 에코시스템 라이브러리를 사용하는 시나리오에 대해 설명합니다.

Spring Kafka 애플리케이션 지원

이 섹션에서는 Spring Kafka 또는 Spring Integration Kafka 라이브러리를 사용하는 Spring Boot 애플리케이션의 사용 시나리오에 대해 설명합니다.

종속성 설정

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<!-- Using Spring Kafka library only-->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:2.8.6-->
</dependency>
<!-- Using Spring Integration library only -->
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:5.5.12-->
</dependency>

구성 업데이트

OAuth 인증을 사용하려면 다음 예제와 같이 Event Hubs 엔드포인트를 지정합니다.

spring.kafka.bootstrap-servers=<NAMESPACENAME>.servicebus.windows.net:9093

Spring Cloud Stream 바인더 Kafka 애플리케이션 지원

이 섹션에서는 Spring Cloud Stream 바인더 Kafka 라이브러리를 사용하는 Spring Boot 애플리케이션의 사용 시나리오에 대해 설명합니다.

종속성 설정

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-stream-kafka</artifactId>
    <version>{version}</version><!--Need to be set, for example:3.2.3-->
</dependency>

구성

OAuth 인증을 사용하려면 다음 예제와 같이 Event Hubs 엔드포인트를 지정합니다.

spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093

메모

버전을 4.3.0사용하는 경우 전체 OAuth 인증 워크플로를 사용하도록 속성을 설정합니다 spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration . 단일 Kafka 바인더 애플리케이션에서는 기본적으로 kafka-binder-name가 kafka입니다. 구성 AzureKafkaSpringCloudStreamConfiguration은 KafkaBinderConfigurationProperties에 대한 OAuth 보안 매개 변수를 지정합니다. 이 구성은 Azure ID를 사용하도록 설정하는 데 사용됩니다KafkaOAuth2AuthenticateCallbackHandler.

이후 4.4.0버전의 경우 이 속성은 각 Kafka 바인더 환경에 대해 자동으로 추가되므로 수동으로 추가할 필요가 없습니다.

OAuth 인증에 관리 ID 사용

관리되는 ID를 사용하려면 서비스에 대해 관리되는 ID를 사용하도록 설정하고 Azure Event Hubs Data Sender 및 Azure Event Hubs Data Receiver 역할을 할당합니다. 자세한 내용은 액세스 권한대한 Azure 역할 할당 참조하세요.
application.yml 파일에서 다음 속성을 구성합니다.
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
중요하다

사용자가 할당한 관리 ID를 사용하는 경우 사용자 할당 관리 ID 클라이언트 ID를 사용하여 속성을 spring.cloud.azure.credential.client-id 추가합니다.

샘플

GitHub의 azure-spring-boot-samples 리포지토리를 참조하세요.

연결 문자열 인증 사용

연결 문자열 인증을 직접 사용하거나 Azure Resource Manager를 사용하여 연결 문자열을 검색할 수 있습니다.

Spring Cloud Azure 5.x
Spring Cloud Azure 4.x

메모

버전 5.0.0부터 Spring Cloud Stream 프레임워크에서 연결 문자열 인증을 사용하는 경우에도 연결 문자열 작동하도록 하려면 다음 속성이 필요합니다. <kafka-binder-name> 값은 Kafka 바인더 이름을 사용자 지정하지 않는 경우여야 합니다kafka.spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

사용하는 버전 spring-cloud-dependencies 이 2022.0.0면 예외 java.lang.IllegalStateException: kafka_context has not been refreshed yet가 발생합니다. 이 문제를 해결하려면 상위 버전으로 업그레이드합니다.

메모

버전 4.3.0부터 연결 문자열 인증은 OAuth 인증을 위해 더 이상 사용되지 않습니다.

버전 4.5.0부터 Spring Cloud Stream 프레임워크에서 연결 문자열 인증을 사용하는 경우 연결 문자열 작동하도록 하려면 다음 속성이 필요합니다. <kafka-binder-name> 값은 Kafka 바인더 이름을 사용자 지정하지 않는 경우여야 합니다kafka.spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

종속성 설정

Kafka용 Azure Event Hubs를 사용하도록 Apache Kafka 애플리케이션을 마이그레이션하려는 경우 다음 종속성을 추가합니다.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter</artifactId>
</dependency>

Azure Resource Manager 사용하여 연결 문자열 검색하려면 다음 종속성을 추가합니다.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>

구성

Event Hubs 연결 문자열을 직접 사용

Kafka용 Event Hubs에 연결하는 가장 간단한 방법은 연결 문자열을 사용하는 것입니다. 다음 속성을 추가하기만 하면됩니다.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

Azure Resource Manager를 사용하여 연결 문자열 검색

애플리케이션에서 연결 문자열을 구성하지 않으려면 Azure Resource Manager를 사용하여 연결 문자열을 검색할 수 있습니다. Azure Resource Manager를 사용하여 인증하려면 Azure CLI 또는 Visual Studio Code 또는 Intellij IDEA와 같은 다른 로컬 개발 도구에 저장된 자격 증명을 사용할 수도 있습니다. 또는 애플리케이션이 Azure Cloud에 배포된 경우 관리 ID를 사용할 수 있습니다. 보안 주체에 리소스 메타데이터를 읽을 수 있는 충분한 권한이 있는지만 확인하세요.

메모

Azure Resource Manager를 사용하여 연결 문자열을 검색하려면 다음 속성을 추가하기만 하면됩니다.

spring:
  cloud:
    azure:
      profile:
        subscription-id: ${AZURE_SUBSCRIPTION_ID}
      eventhubs:
        namespace: ${AZURE_EVENTHUBS_NAMESPACE}
        resource:
          resource-group: ${AZURE_EVENTHUBS_RESOURCE_GROUP}

샘플

GitHub의 azure-spring-boot-samples 리포지토리를 참조하세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-14

Spring Cloud Azure Kafka 지원

지원되는 Kafka 버전

지원되는 인증 유형

작동 방식

OAuth 자격 증명 인증

일반 연결 문자열 인증

구성

OAuth 인증에서 Kafka 지원을 사용하는 경우 구성 가능한 속성

일반 연결 문자열 인증과 함께 Kafka 지원을 사용하는 경우 구성 가능한 속성

종속성 설정

기본 사용량

OAuth 인증 사용

Spring Kafka 애플리케이션 지원

종속성 설정

구성 업데이트

Spring Cloud Stream 바인더 Kafka 애플리케이션 지원

종속성 설정

구성

OAuth 인증에 관리 ID 사용

샘플

연결 문자열 인증 사용

종속성 설정

구성

Event Hubs 연결 문자열을 직접 사용

Azure Resource Manager를 사용하여 연결 문자열 검색

샘플

피드백

추가 리소스