Aracılığıyla paylaş

Spring Cloud Azure Kafka desteği

  • Makale

Bu makale şunlar için geçerlidir: ✔️ Sürüm 4.14.0 ✔️ Sürüm 5.8.0

Kafka için Spring Cloud Azure, 4.3.0 sürümünden itibaren kimlik doğrulaması yapmak ve Azure Event Hubs'a bağlanmak için çeşitli kimlik bilgisi türlerini destekler.

Desteklenen Kafka sürümü

Starter'ın geçerli sürümü Java 8 veya üzerini kullanan Apache Kafka İstemcileri 2.0.0 ile uyumlu olmalıdır.

Desteklenen kimlik doğrulama türleri

Aşağıdaki kimlik doğrulama türleri desteklenmektedir:

  • Düz bağlantı dizesi kimlik doğrulaması
    • Doğrudan bağlantı dizesi kimlik doğrulaması
    • ARM tabanlı bağlantı dizesi kimlik doğrulaması
  • OAuth kimlik bilgisi kimlik doğrulaması
    • Yönetilen kimlik doğrulaması
    • Kullanıcı adı/parola kimlik doğrulaması
    • Hizmet sorumlusu kimlik doğrulaması
    • DefaultAzureCredential kimlik doğrulaması

Nasıl çalışır?

OAuth kimlik bilgisi kimlik doğrulaması

Bu bölümde Spring Cloud Azure OAuth kimlik doğrulamasının genel iş akışı açıklanmaktadır.

Spring Cloud Azure, uygulama kimlik doğrulaması yapılandırmasına bağlı olarak ilk olarak aşağıdaki kimlik bilgileri türlerinden birini oluşturur:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Bu tür kimlik bilgilerinin hiçbiri bulunmazsa, aracılığıyla kimlik bilgisi zinciri DefaultAzureTokenCredential uygulama özelliklerinden, ortam değişkenlerinden, yönetilen kimlikten veya IDE'lerden kimlik bilgilerini almak için kullanılır. Ayrıntılı bilgi için bkz . Spring Cloud Azure kimlik doğrulaması.

Düz bağlantı dizesi kimlik doğrulaması

bağlantı dizesi kimlik doğrulama modu için doğrudan bağlantı dizesi kimlik doğrulamasını kullanabilir veya bağlantı dizesi almak için Azure Resource Manager'ı kullanabilirsiniz. Kullanım hakkında daha fazla bilgi için bağlantı dizesi kimlik doğrulaması için temel kullanım bölümüne bakın.

Dekont

4.3.0 sürümünden bu yana bağlantı dizesi kimlik doğrulaması, OAuth kimlik doğrulamaları için kullanım dışı bırakılmıştır.

Yapılandırma

OAuth kimlik doğrulaması ile Kafka desteği kullanılırken yapılandırılabilir özellikler

Kafka için Spring Cloud Azure aşağıdaki iki yapılandırma seçeneğini destekler:

  1. Event Hubs için Spring Cloud Azure Kafka özellikleri.
  2. ve profile ön ekleriyle spring.cloud.azuregenel kimlik doğrulama yapılandırma seçeneklericredential.
  3. Kafka'ya özgü düzey yapılandırmaları. Kafka düzeyinde yapılandırmalar, farklı ön ekleri olan , consumer, producerveya admin kapsamları için Spring Boot ve Spring Cloud Stream bağlayıcıları için commonde kullanılabilir.

Genel özellikler aracılığıyla com.azure.spring.cloud.autoconfigure.context.AzureGlobalPropertieskullanıma sunulur. Kafka'ya özgü özellikler (Spring Boot) ve org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream bağlayıcısı) aracılığıyla org.springframework.boot.autoconfigure.kafka.KafkaProperties kullanıma sunulur.

Aşağıdaki listede desteklenen tüm yapılandırma seçenekleri gösterilmektedir.

  • Event Hubs için Spring Cloud Azure Kafka özellikleri.

    • Özellik: spring.cloud.azure.eventhubs.kafka.enabled
    • Açıklama: Kafka için Azure Event Hubs'a kimlik bilgisi ücretsiz bağlantısının etkinleştirilip etkinleştirilmeyileceği, varsayılan değerdir true.

  • Spring Cloud Azure genel kimlik doğrulaması yapılandırma seçenekleri

    • Önek: spring.cloud.azure
    • Desteklenen seçenekler: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Genel yapılandırma seçeneklerinin tam listesi için bkz . Genel yapılandırma özellikleri.

  • Spring Boot Kafka ortak yapılandırması

    • Önek: spring.kafka.properties.azure
    • Örnek: spring.kafka.properties.azure.credential.*

  • Spring Kafka tüketici yapılandırma seçenekleri

    • Önek: spring.kafka.consumer.properties.azure
    • Örnek: spring.kafka.consumer.properties.azure.credential.*

  • Spring Kafka üretici yapılandırma seçenekleri

    • Önek: spring.kafka.producer.properties.azure
    • Örnek: spring.kafka.producer.properties.azure.credential.*

  • Spring Kafka yönetici yapılandırma seçenekleri

    • Önek: spring.kafka.admin.properties.azure
    • Örnek: spring.kafka.admin.properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder ortak yapılandırması

    • Önek: spring.cloud.stream.kafka.binder.configuration.azure
    • Örnek: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Spring Cloud Stream Kafka Binder tüketici yapılandırması

    • Önek: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Örnek: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder üretici yapılandırması

    • Önek: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Örnek: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder yönetici yapılandırması

    • Ön ek: Desteklenmez, Spring Boot Kafka ortak veya yönetici yapılandırmasını kullanmalıdır.

Aşağıdaki tabloda Spring Boot Kafka ortak yapılandırma seçenekleri gösterilmektedir:

Adı Açıklama
spring.kafka.properties.azure.credential.client-certificate-password Sertifika dosyasının parolası.
spring.kafka.properties.azure.credential.client-certificate-path Azure ile hizmet sorumlusu kimlik doğrulaması gerçekleştirirken kullanılacak PEM sertifika dosyasının yolu.
spring.kafka.properties.azure.credential.client-id Azure ile hizmet sorumlusu kimlik doğrulaması gerçekleştirirken kullanılacak istemci kimliği. Bu eski bir özelliktir.
spring.kafka.properties.azure.credential.client-secret Azure ile hizmet sorumlusu kimlik doğrulaması gerçekleştirirken kullanılacak istemci gizli dizisi. Bu eski bir özelliktir.
spring.kafka.properties.azure.credential.managed-identity-enabled Yönetilen kimliğin Azure ile kimlik doğrulaması yapmasının etkinleştirilip etkinleştirilmeyileceği. true ise ve client-id ayarlanırsa, kullanıcı tarafından atanan yönetilen kimlik istemci kimliği olarak istemci kimliğini kullanır. Varsayılan değer yanlış değeridir.
spring.kafka.properties.azure.credential.password Azure ile kullanıcı adı/parola kimlik doğrulaması gerçekleştirirken kullanılacak parola.
spring.kafka.properties.azure.credential.username Azure ile kullanıcı adı/parola kimlik doğrulaması gerçekleştirirken kullanılacak kullanıcı adı.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Bağlanacak Microsoft Entra uç noktası.
spring.kafka.properties.azure.profile.tenant-id Azure kaynakları için kiracı kimliği. için tenant-id izin verilen değerler şunlardır: common, organizations, consumersveya kiracı kimliği.

Dekont

Farklı düzeylerdeki yapılandırma seçenekleri aşağıdaki kuralları uygular. Daha belirli yapılandırma seçeneklerinin önceliği yaygın olanlardan daha yüksektir. Örneğin:

  • Spring Kafka ortak yapılandırma seçenekleri genel seçeneklerin yerini alır.
  • Spring Kafka tüketici yapılandırma seçenekleri, ortak seçeneklerin yerini alır.
  • Spring Kafka üretici yapılandırma seçenekleri, ortak seçeneklerin yerini alır.
  • Spring Kafka yönetici yapılandırma seçenekleri, ortak seçeneklerin yerini alır.
  • Spring Cloud Stream Kafka Binder seçenekleri de yukarıdaki gibidir.

Düz bağlantı dizesi kimlik doğrulaması ile Kafka desteği kullanılırken yapılandırılabilir özellikler

Aşağıdaki tabloda Kafka için Spring Boot Event Hubs yaygın yapılandırma seçenekleri gösterilmektedir:

Özellik Açıklama
spring.cloud.azure.eventhubs.kafka.enabled Azure Event Hubs Kafka desteğinin etkinleştirilip etkinleştirilmeyileceği. Varsayılan değer true değeridir.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs bağlantı dizesi. bağlantı dizesi doğrudan sağlamak istediğinizde bu değeri belirtin.
spring.cloud.azure.eventhubs.namespace Azure Event Hubs ad alanı. Azure Resource Manager aracılığıyla bağlantı bilgilerini almak istediğinizde bu değeri belirtin.
spring.cloud.azure.eventhubs.resource.resource-group Azure Event Hubs ad alanının kaynak grubu. Azure Resource Manager aracılığıyla bağlantı bilgilerini almak istediğinizde bu değeri belirtin.
spring.cloud.azure.profile.subscription-id Abonelik kimliği. Azure Resource Manager aracılığıyla bağlantı bilgilerini almak istediğinizde bu değeri belirtin.

Bağımlılık kurulumu

Projenize aşağıdaki bağımlılığı ekleyin. Bu, projenizdeki bağımlılığı geçişli olarak otomatik olarak içerir spring-boot-starter .

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

Dekont

Ürün reçetesini spring-cloud-azure-dependencies yukarıdaki bağımlılıkla birlikte eklemeyi unutmayın. Ayrıntılar için Spring Cloud Azure geliştirici kılavuzunun Başlarken bölümüne bakın.

Temel kullanım

Aşağıdaki bölümlerde klasik Spring Boot uygulaması kullanım senaryoları gösterilmektedir.

OAuth kimlik doğrulamasını kullanma

Kafka için Spring Cloud Azure tarafından sağlanan OAuth kimlik doğrulamasını kullandığınızda, yukarıdaki yapılandırmaları kullanarak belirli kimlik bilgilerini yapılandırabilirsiniz. Alternatif olarak, kimlik bilgileri hakkında hiçbir şey yapılandırmamayı seçebilirsiniz. Bu durumda Spring Cloud Azure, kimlik bilgilerini ortamdan yükler. Bu bölümde, Azure CLI ortamından veya Azure Spring Apps barındırma ortamından kimlik bilgilerini yükleyen kullanımlar açıklanmaktadır.

Dekont

Bir Azure kaynağına erişim için Microsoft Entra Id ile kimlik doğrulaması yapmak ve yetkilendirmek için bir güvenlik sorumlusu kullanmayı seçerseniz, güvenlik sorumlusuna Azure kaynağına erişmek için yeterli iznin verildiğinden emin olmak için Microsoft Entra Id ile erişimi yetkilendirme bölümüne bakın.

Aşağıdaki bölümde, OAuth kimlik doğrulaması ile farklı Spring ekosistem kitaplıklarının kullanıldığı senaryolar açıklanmaktadır.

Spring Kafka uygulama desteği

Bu bölümde Spring Kafka veya Spring Integration Kafka kitaplığını kullanan Spring Boot uygulaması kullanım senaryosu açıklanmaktadır.

Bağımlılık kurulumu
<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>

Yapılandırma güncelleştirmesi

OAuth kimlik doğrulamasını kullanmak için, aşağıdaki örnekte gösterildiği gibi Event Hubs uç noktasını belirtmeniz gerekir:

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

Spring Cloud Stream bağlayıcısı Kafka uygulama desteği

Bu bölümde Spring Cloud Stream bağlayıcı kafka kitaplığını kullanan Spring Boot uygulamaları için kullanım senaryosu açıklanmaktadır.

Bağımlılık kurulumu
<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>
Yapılandırma

OAuth kimlik doğrulamasını kullanmak için aşağıdaki örnekte gösterildiği gibi Event Hubs uç noktasını belirtmeniz gerekir:

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

Dekont

sürümünü 4.3.0kullanıyorsanız özelliğini, varsayılan olarak tek bir Kafka bağlayıcı uygulamasında olan kafka-binder-namekafka OAuth kimlik doğrulaması iş akışının tamamını etkinleştirecek şekilde ayarlamayı spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration unutmayın. Yapılandırma AzureKafkaSpringCloudStreamConfiguration , içinde Azure Kimliğini etkinleştirmek için KafkaBinderConfigurationPropertieskullanılan KafkaOAuth2AuthenticateCallbackHandler OAuth güvenlik parametrelerini belirtir.

sürümünden sonraki 4.4.0sürüm için bu özellik her Kafka bağlayıcı ortamı için otomatik olarak eklenir, bu nedenle el ile eklemenize gerek yoktur.

Örnekler

GitHub'daki azure-spring-boot-samples deposuna bakın.

bağlantı dizesi kimlik doğrulamayı kullanma

bağlantı dizesi kimlik doğrulamasını doğrudan kullanabilir veya bağlantı dizesi almak için Azure Resource Manager'ı kullanabilirsiniz.

Dekont

4.3.0 sürümünden bu yana bağlantı dizesi kimlik doğrulaması, OAuth kimlik doğrulamaları için kullanım dışı bırakılmıştır.

4.5.0 sürümünden bu yana, Spring Cloud Stream çerçevesiyle bağlantı dizesi kimlik doğrulaması kullanılırken, bağlantı dizesi etkili olabileceğinden emin olmak için aşağıdaki özellik gereklidir. Bu özellik, Kafka bağlayıcı adınız için özelleştirilmiş bir yapılandırma olmadığında değerinin <kafka-binder-name> olması gereken yerdedirkafka.

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

Bağımlılık kurulumu

Apache Kafka uygulamanızı Kafka için Azure Event Hubs kullanacak şekilde geçirmek istiyorsanız aşağıdaki bağımlılıkları ekleyin.

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

Azure Resource Manager kullanarak bağlantı dizesi almak istiyorsanız aşağıdaki bağımlılığı ekleyin:

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

Yapılandırma

Event Hubs bağlantı dizesi doğrudan kullanma

Kafka için Event Hubs'a bağlanmanın en basit yolu bağlantı dizesi. Yalnızca aşağıdaki özelliği ekleyin.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Bağlantı dizesi almak için Azure Resource Manager'ı kullanma

Uygulamanızda bağlantı dizesi yapılandırmak istemiyorsanız, bağlantı dizesi almak için Azure Resource Manager'ı kullanabilirsiniz. Azure Resource Manager ile kimlik doğrulaması yapmak için Azure CLI'da veya Visual Studio Code veya Intellij IDEA gibi başka bir yerel geliştirme aracında depolanan kimlik bilgilerini de kullanabilirsiniz. Alternatif olarak, uygulamanız Azure Bulut'a dağıtıldıysa Yönetilen Kimlik'i kullanabilirsiniz. Sorumlunun kaynak meta verilerini okumak için yeterli izne sahip olduğundan emin olun.

Dekont

Azure kaynağına erişim için Microsoft Entra Id ile kimlik doğrulaması yapmak ve yetkilendirmek için bir güvenlik sorumlusu kullanmayı seçerseniz, güvenlik sorumlusuna Azure kaynağına erişmek için yeterli iznin verildiğinden emin olmak için Microsoft Entra Id ile erişimi yetkilendirme bölümüne bakın.

Azure Resource Manager'ı kullanarak bağlantı dizesi almak için aşağıdaki özelliği eklemeniz gerekir.

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

Örnekler

GitHub'daki azure-spring-boot-samples deposuna bakın.