Stöd för Spring Cloud Azure Kafka

Den här artikeln gäller för:✅ version 4.19.0 ✅ version 5.20.1

Från version 4.3.0 stöder Spring Cloud Azure for Kafka olika typer av autentiseringsuppgifter för att autentisera och ansluta till Azure Event Hubs.

Kafka-version som stöds

Den aktuella versionen av startern ska vara kompatibel med Apache Kafka-klienter 2.0.0 med Java 8 eller senare.

Autentiseringstyper som stöds

Följande autentiseringstyper stöds:

• Autentisering med oformaterad anslutningssträng
  • Direktanslutningssträngsautentisering
  • ARM-baserad anslutningssträngsautentisering
• Autentisering med OAuth-autentiseringsuppgifter
  • Hanterad identitetsautentisering
  • Autentisering med användarnamn/lösenord
  • Autentisering med tjänstens huvudnamn
  • DefaultAzureCredential autentisering

Så här fungerar det

Autentisering med OAuth-autentiseringsuppgifter

I det här avsnittet beskrivs det övergripande arbetsflödet för Spring Cloud Azure OAuth-autentisering.

Spring Cloud Azure skapar först en av följande typer av autentiseringsuppgifter beroende på konfigurationen för programautentisering:

• ClientSecretCredential
• ClientCertificateCredential
• UsernamePasswordCredential
• ManagedIdentityCredential

Om ingen av dessa typer av autentiseringsuppgifter hittas används autentiseringskedjan via DefaultAzureTokenCredential för att hämta autentiseringsuppgifter från programegenskaper, miljövariabler, hanterad identitet eller IDE:er. Detaljerad information finns i Spring Cloud Azure-autentisering.

Autentisering med oformaterad anslutningssträng

För autentiseringsläget för anslutningssträngar kan du använda autentisering med anslutningssträngen direkt eller använda Azure Resource Manager för att hämta anslutningssträngen. Mer information om användningen finns i avsnittet Grundläggande användning för autentisering av anslutningssträngar.

Anteckning

Eftersom version 4.3.0 är anslutningssträngsautentisering inaktuell till förmån för OAuth-autentiseringar.

Konfiguration

Konfigurerbara egenskaper när du använder Kafka-stöd med OAuth-autentisering

Spring Cloud Azure for Kafka stöder följande två konfigurationsalternativ:

1. Spring Cloud Azure för Event Hubs Kafka-egenskaper.
2. Konfigurationsalternativen för global autentisering för credential och profile med prefix för spring.cloud.azure.
3. Kafka-specifika nivåkonfigurationer. Kafka-nivåkonfigurationerna är också tillgängliga för Spring Boot- och Spring Cloud Stream-pärmar för common, consumer, producereller admin omfång som har olika prefix.

De globala egenskaperna exponeras via com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. De Kafka-specifika egenskaperna exponeras via org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) och org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream-pärm).

I följande lista visas alla konfigurationsalternativ som stöds.

• Spring Cloud Azure för Event Hubs Kafka-egenskaper.

  • Egenskap: spring.cloud.azure.eventhubs.kafka.enabled
  • Beskrivning: Om du vill aktivera kostnadsfri anslutning med autentiseringsuppgifter till Azure Event Hubs för Kafka är standardvärdet true.

• Konfigurationsalternativ för global autentisering i Spring Cloud Azure

  • Prefix: spring.cloud.azure
  • Alternativ som stöds: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

  En fullständig lista över globala konfigurationsalternativ finns i Globala konfigurationsegenskaper.

• Vanliga konfigurationer för Spring Boot Kafka

  • Prefix: spring.kafka.properties.azure
  • Exempel: spring.kafka.properties.azure.credential.*

• Konfigurationsalternativ för Spring Kafka-konsumenter

  • Prefix: spring.kafka.consumer.properties.azure
  • Exempel: spring.kafka.consumer.properties.azure.credential.*

• Konfigurationsalternativ för Spring Kafka-producent

  • Prefix: spring.kafka.producer.properties.azure
  • Exempel: spring.kafka.producer.properties.azure.credential.*

• Konfigurationsalternativ för Spring Kafka-administratör

  • Prefix: spring.kafka.admin.properties.azure
  • Exempel: spring.kafka.admin.properties.azure.credential.*

• Gemensam konfiguration för Spring Cloud Stream Kafka Binder

  • Prefix: spring.cloud.stream.kafka.binder.configuration.azure
  • Exempel: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

• Spring Cloud Stream Kafka Binder-konsumentkonfiguration

  • Prefix: spring.cloud.stream.kafka.binder.consumer-properties.azure
  • Exempel: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

• Spring Cloud Stream Kafka Binder-producentkonfiguration

  • Prefix: spring.cloud.stream.kafka.binder.producer-properties.azure
  • Exempel: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

• Spring Cloud Stream Kafka Binder-administratörskonfiguration

  • Prefix: Stöds inte, bör använda Spring Boot Kafka gemensam eller administratörskonfiguration.

I följande tabell visas vanliga konfigurationsalternativ för Spring Boot Kafka:

Namn	Beskrivning
spring.kafka.properties.azure.credential.client-certificate-password	Lösenord för certifikatfilen.
spring.kafka.properties.azure.credential.client-certificate-path	Sökväg till en PEM-certifikatfil som ska användas när du utför autentisering med tjänstens huvudnamn med Azure.
spring.kafka.properties.azure.credential.client-id	Klient-ID som ska användas vid autentisering med tjänstens huvudnamn med Azure. Det här är en äldre egenskap.
spring.kafka.properties.azure.credential.client-secret	Klienthemlighet som ska användas vid autentisering av tjänstens huvudnamn med Azure. Det här är en äldre egenskap.
spring.kafka.properties.azure.credential.managed-identity-enabled	Om du vill aktivera hanterad identitet för att autentisera med Azure. Om true och client-id anges använder du klient-ID:t som användartilldelat klient-ID för hanterad identitet. Standardvärdet är false.
spring.kafka.properties.azure.credential.password	Lösenord som ska användas när du utför autentisering med användarnamn/lösenord med Azure.
spring.kafka.properties.azure.credential.username	Användarnamn som ska användas när du utför autentisering med användarnamn/lösenord med Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint	Microsoft Entra-slutpunkten att ansluta till.
spring.kafka.properties.azure.profile.tenant-id	Klientorganisations-ID för Azure-resurser. De värden som tillåts för tenant-id är: common, organizations, consumerseller klientorganisations-ID.

Anteckning

Konfigurationsalternativen på olika nivåer tillämpar följande regler. De mer specifika konfigurationsalternativen har högre prioritet än de vanliga. Till exempel:

• Vanliga konfigurationsalternativ för Spring Kafka ersätter de globala alternativen.
• Spring Kafka-konsumentkonfigurationsalternativ ersätter de vanliga alternativen.
• Spring Kafka-producentkonfigurationsalternativ ersätter de vanliga alternativen.
• Spring Kafka-administratörskonfigurationsalternativ ersätter de vanliga alternativen.
• Spring Cloud Stream Kafka Binder-alternativen är precis som ovanstående.

Konfigurerbara egenskaper när du använder Kafka-stöd med autentisering med oformaterad anslutningssträng

I följande tabell visas vanliga konfigurationsalternativ för Spring Boot Event Hubs för Kafka:

Egenskap	Beskrivning
spring.cloud.azure.eventhubs.kafka.enabled	Om du vill aktivera Azure Event Hubs Kafka-stöd. Standardvärdet är true.
spring.cloud.azure.eventhubs.connection-string	Anslutningssträng för Azure Event Hubs. Ange det här värdet när du vill ange anslutningssträngen direkt.
spring.cloud.azure.eventhubs.namespace	Azure Event Hubs-namnrymd. Ange det här värdet när du vill hämta anslutningsinformationen via Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group	Resursgruppen för Azure Event Hubs-namnområdet. Ange det här värdet när du vill hämta anslutningsinformationen via Azure Resource Manager.
spring.cloud.azure.profile.subscription-id	Prenumerations-ID:t. Ange det här värdet när du vill hämta anslutningsinformationen via Azure Resource Manager.

Beroendekonfiguration

Lägg till följande beroende i projektet. Detta inkluderar automatiskt spring-boot-starter beroende i projektet transitivt.

XML

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

Anteckning

Kom ihåg att lägga till BOM-spring-cloud-azure-dependencies tillsammans med ovanstående beroende. Mer information finns i avsnittet Komma igång i utvecklarguiden Spring Cloud Azure.

Grundläggande användning

I följande avsnitt visas de klassiska Användningsscenarierna för Spring Boot-program.

Använda OAuth-autentisering

När du använder OAuth-autentiseringen som tillhandahålls av Spring Cloud Azure for Kafka kan du konfigurera de specifika autentiseringsuppgifterna med hjälp av ovanstående konfigurationer. Du kan också välja att inte konfigurera något om autentiseringsuppgifter, i vilket fall Spring Cloud Azure läser in autentiseringsuppgifterna från miljön. I det här avsnittet beskrivs de användningar som läser in autentiseringsuppgifterna från Azure CLI-miljön eller Azure Spring Apps-värdmiljön.

Anteckning

Om du väljer att använda ett säkerhetsobjekt för att autentisera och auktorisera med Microsoft Entra-ID för åtkomst till en Azure-resurs läser du avsnittet Auktorisera åtkomst med Microsoft Entra-ID för att kontrollera att säkerhetsobjektet har beviljats tillräcklig behörighet för att få åtkomst till Azure-resursen.

I följande avsnitt beskrivs scenarier med olika Spring-ekosystembibliotek med OAuth-autentisering.

Stöd för Spring Kafka-program

I det här avsnittet beskrivs användningsscenariot för Spring Boot-programmet med hjälp av Spring Kafka- eller Spring Integration Kafka-biblioteket.

Beroendekonfiguration

XML

<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>

Konfigurationsuppdatering

Om du vill använda OAuth-autentiseringen anger du bara Event Hubs-slutpunkten, som du ser i följande exempel:

properties

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

Stöd för Spring Cloud Stream-binder Kafka-program

I det här avsnittet beskrivs användningsscenariot för Spring Boot-program med hjälp av Spring Cloud Stream-binder Kafka-biblioteket.

Beroendekonfiguration

XML

<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>

Konfiguration

Om du vill använda OAuth-autentiseringen anger du bara Event Hubs-slutpunkten enligt följande exempel:

properties

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

Anteckning

Om du använder version 4.3.0ska du inte glömma att ange egenskapen spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration för att aktivera hela arbetsflödet för OAuth-autentisering, där kafka-binder-namekafka som standard i ett enda Kafka-binder-program. Konfigurationen AzureKafkaSpringCloudStreamConfiguration anger OAuth-säkerhetsparametrarna för KafkaBinderConfigurationProperties, som används i KafkaOAuth2AuthenticateCallbackHandler för att aktivera Azure Identity.

För version efter 4.4.0läggs den här egenskapen till automatiskt för varje Kafka-bindemedelsmiljö, så du behöver inte lägga till den manuellt.

Använda hanterad identitet för OAuth-autentisering

1. Om du vill använda den hanterade identiteten behöver du aktivera den hanterade identiteten för din tjänst och tilldela rollerna Azure Event Hubs Data Receiver och Azure Event Hubs Data Sender. Mer information finns i Tilldela Azure-roller för åtkomsträttigheter.

2. Konfigurera följande egenskaper i din application.yml-fil:

   YAML

   spring:
     cloud:
       azure:
         credential:
           managed-identity-enabled: true
   

   Viktigt

   Om du använder användartilldelad hanterad identitet måste du också lägga till egenskapen spring.cloud.azure.credential.client-id med ditt användartilldelade klient-ID för hanterad identitet.

Prover

Se azure-spring-boot-samples-lagringsplatsen på GitHub.

Använda autentisering med anslutningssträngar

Du kan använda anslutningssträngsautentisering direkt eller använda Azure Resource Manager för att hämta anslutningssträngen.

Spring Cloud Azure 5.x

Anteckning

Eftersom versionen av 5.0.0, när du använder anslutningssträngsautentisering med Spring Cloud Stream Framework, krävs fortfarande följande egenskap för att säkerställa att anslutningssträngen kan börja gälla, där värdet för <kafka-binder-name> ska kafka när det inte finns någon anpassad konfiguration för kafka-bindemedlets namn: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Om versionen av spring-cloud-dependencies som du använde är 2022.0.0får du ett undantag från java.lang.IllegalStateException: kafka_context has not been refreshed yet. Lös problemet genom att uppgradera till en högre version.

Spring Cloud Azure 4.x

Anteckning

Eftersom version 4.3.0 är anslutningssträngsautentisering inaktuell till förmån för OAuth-autentiseringar.

Eftersom version 4.5.0, när du använder anslutningssträngsautentisering med Spring Cloud Stream Framework, krävs följande egenskap för att säkerställa att anslutningssträngen kan börja gälla, där värdet för <kafka-binder-name> ska kafka när det inte finns någon anpassad konfiguration för kafka-bindemedlets namn: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Beroendekonfiguration

Lägg till följande beroenden om du vill migrera ditt Apache Kafka-program för att använda Azure Event Hubs för Kafka.

XML

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

Om du vill hämta anslutningssträngen med Hjälp av Azure Resource Manager lägger du till följande beroende:

XML

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

Konfiguration

Använda Event Hubs-anslutningssträngen direkt

Det enklaste sättet att ansluta till Event Hubs för Kafka är med anslutningssträngen. Lägg bara till följande egenskap.

properties

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

Använda Azure Resource Manager för att hämta anslutningssträngen

Om du inte vill konfigurera anslutningssträngen i ditt program kan du använda Azure Resource Manager för att hämta anslutningssträngen. Om du vill autentisera med Azure Resource Manager kan du också använda autentiseringsuppgifter som lagras i Azure CLI eller något annat lokalt utvecklingsverktyg som Visual Studio Code eller Intellij IDEA. Alternativt kan du använda Hanterad identitet om ditt program distribueras till Azure Cloud. Se bara till att huvudnamnet har tillräcklig behörighet för att läsa resursmetadata.

Anteckning

Om du väljer att använda ett säkerhetsobjekt för att autentisera och auktorisera med Microsoft Entra-ID för åtkomst till en Azure-resurs läser du avsnittet Auktorisera åtkomst med Microsoft Entra-ID för att se till att säkerhetsobjektet har beviljats tillräcklig behörighet för att få åtkomst till Azure-resursen.

Om du vill använda Azure Resource Manager för att hämta anslutningssträngen lägger du bara till följande egenskap.

YAML

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

Prover

Se azure-spring-boot-samples-lagringsplatsen på GitHub.