Spring Cloud Azure Kafka 지원

아티클
10/23/2023

이 문서는 버전 4.14.0 ✔️ 버전 5.8.0에 적용됩니다. ✔️

버전 4.3.0부터 Kafka용 Spring Cloud Azure는 Azure Event Hubs를 인증하고 연결하는 다양한 유형의 자격 증명을 지원합니다.

지원되는 Kafka 버전

현재 버전의 시작은 Java 8 이상을 사용하여 Apache Kafka Clients 2.0.0과 호환되어야 합니다.

지원되는 인증 유형

다음 인증 유형이 지원됩니다.

일반 연결 문자열 인증
- 직접 연결 문자열 인증
- 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가진 전역 인증 구성 옵션 credentialprofile 입니다.
Kafka 관련 수준 구성. Kafka 수준 구성은 접두사는 서로 다른 , consumerproducer또는 admin 범위에 대한 commonSpring Boot 및 Spring Cloud Stream 바인더에도 사용할 수 있습니다.

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

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

Event Hubs Kafka 속성용 Spring Cloud Azure.
- 속성: 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` 값은 , `commonorganizations`, `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 인증 사용

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

참고 항목

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

다음 섹션에서는 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사용하는 경우 기본적으로 단일 Kafka 바인더 애플리케이션에서 전체 OAuth 인증 워크플로 kafka-binder-namekafka 를 사용하도록 속성을 설정하는 spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration 것을 잊지 마세요. 구성 AzureKafkaSpringCloudStreamConfiguration 은 Azure ID를 사용하도록 설정하는 데 사용되는 KafkaOAuth2AuthenticateCallbackHandler OAuth 보안 매개 변수KafkaBinderConfigurationProperties를 지정합니다.

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

샘플

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

연결 문자열 인증 사용

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

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

참고 항목

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

4.5.0 버전부터 Spring Cloud Stream 프레임워크에서 연결 문자열 인증을 사용하는 경우 kafka 바인더 이름에 대한 사용자 지정 구성이 없는 경우 값 <kafka-binder-name> 이 있어야 하는 연결 문자열 적용되도록 kafka 하려면 다음 속성이 필요합니다.

spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

참고 항목

5.0.0 버전부터 Spring Cloud Stream 프레임워크에서 연결 문자열 인증을 사용하는 경우 Kafka 바인더 이름에 대한 사용자 지정 구성이 없을 때 값 <kafka-binder-name> 이 있어야 하는 연결 문자열 적용할 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발생합니다. 이 문제를 해결하려면 상위 버전으로 업그레이드합니다.

종속성 설정

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 리소스에 액세스하기 위해 Microsoft Entra ID로 인증하고 권한을 부여하도록 선택한 경우 Microsoft Entra ID를 사용하여 액세스 권한 부여 섹션을 참조하여 보안 주체에게 Azure 리소스에 액세스할 수 있는 충분한 권한이 부여되었는지 확인합니다.

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 리포지토리를 참조하세요.

다음을 통해 공유

Spring Cloud Azure Kafka 지원

지원되는 Kafka 버전

지원되는 인증 유형

작동 방법

OAuth 자격 증명 인증

일반 연결 문자열 인증

구성

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

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

종속성 설정

기본 사용법

OAuth 인증 사용

Spring Kafka 애플리케이션 지원

종속성 설정

구성 업데이트

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

종속성 설정

구성

샘플

연결 문자열 인증 사용

종속성 설정

구성

Event Hubs 연결 문자열 직접 사용

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

샘플

피드백

피드백

추가 리소스