Stöd för Spring Cloud Azure Kafka
Den här artikeln gäller för: ✔️ Version 4.14.0 ✔️ Version 5.8.0
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:
- Oformaterad anslutningssträng autentisering
- Direkt anslutningssträng autentisering
- ARM-baserad anslutningssträng-autentisering
- Autentisering med OAuth-autentiseringsuppgifter
- Autentisering av hanterad identitet
- Autentisering med användarnamn/lösenord
- Tjänstens huvudautentisering
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.
Oformaterad anslutningssträng autentisering
För anslutningssträng autentiseringsläge kan du använda anslutningssträng autentisering direkt eller använda Azure Resource Manager för att hämta anslutningssträng. Mer information om användningen finns i avsnittet Grundläggande användning för anslutningssträng autentisering.
Kommentar
Eftersom versionen av 4.3.0 är anslutningssträng autentisering 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:
- Spring Cloud Azure för Event Hubs Kafka-egenskaper.
- Konfigurationsalternativen för global autentisering för
credential
ochprofile
med prefix förspring.cloud.azure
. - 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
,producer
elleradmin
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.
- Egenskapen:
spring.cloud.azure.eventhubs.kafka.enabled
- Beskrivning: Om du vill aktivera kostnadsfri anslutning med autentiseringsuppgifter till Azure Event Hubs för Kafka är
true
standardvärdet .
- Egenskapen:
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.
- Prefix:
Vanliga konfigurationer för Spring Boot Kafka
- Prefix:
spring.kafka.properties.azure
- Exempel:
spring.kafka.properties.azure
.credential.*
- Prefix:
Konfigurationsalternativ för Spring Kafka-konsumenter
- Prefix:
spring.kafka.consumer.properties.azure
- Exempel:
spring.kafka.consumer.properties.azure
.credential.*
- Prefix:
Konfigurationsalternativ för Spring Kafka-producent
- Prefix:
spring.kafka.producer.properties.azure
- Exempel:
spring.kafka.producer.properties.azure
.credential.*
- Prefix:
Konfigurationsalternativ för Spring Kafka-administratör
- Prefix:
spring.kafka.admin.properties.azure
- Exempel:
spring.kafka.admin.properties.azure
.credential.*
- Prefix:
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.*
- Prefix:
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.*
- Prefix:
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.*
- Prefix:
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:
Name | 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 falskt. |
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 , consumers eller klientorganisations-ID. |
Kommentar
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 oformaterad anslutningssträng-autentisering
I följande tabell visas vanliga konfigurationsalternativ för Spring Boot Event Hubs för Kafka:
Property | beskrivning |
---|---|
spring.cloud.azure.eventhubs.kafka.enabled | Om du vill aktivera Azure Event Hubs Kafka-stöd. Standardvärdet är sant. |
spring.cloud.azure.eventhubs.connection-string | Azure Event Hubs anslutningssträng. Ange det här värdet när du vill ange anslutningssträng 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 spring-boot-starter
automatiskt beroendet i projektet transitivt.
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
Kommentar
Kom ihåg att lägga till strukturlistan spring-cloud-azure-dependencies
tillsammans med ovanstående beroende. Mer information finns i avsnittet Komma igång i Utvecklarguiden för 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.
Kommentar
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
<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:
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
<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:
spring.cloud.stream.kafka.binder.brokers=<NAMESPACENAME>.servicebus.windows.net:9093
Kommentar
Om du använder version 4.3.0
ska du inte glömma att ange spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration
egenskapen för att aktivera hela arbetsflödet för OAuth-autentisering, där kafka-binder-name
är kafka
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.0
läggs den här egenskapen till automatiskt för varje Kafka-bindemedelsmiljö, så du behöver inte lägga till den manuellt.
Exempel
Se lagringsplatsen azure-spring-boot-samples på GitHub.
Använda anslutningssträng-autentisering
Du kan använda anslutningssträng autentisering direkt eller använda Azure Resource Manager för att hämta anslutningssträng.
Kommentar
Eftersom versionen av 4.3.0 är anslutningssträng autentisering inaktuell till förmån för OAuth-autentiseringar.
Eftersom version 4.5.0, när du använder anslutningssträng-autentisering med Spring Cloud Stream Framework, krävs följande egenskap för att säkerställa att anslutningssträng kan börja gälla, där värdet <kafka-binder-name>
för ska vara kafka
när det inte finns någon anpassad konfiguration för kafka-pärmnamnet.
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.
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-starter</artifactId>
</dependency>
Om du vill hämta anslutningssträng med Hjälp av Azure Resource Manager lägger du till följande beroende:
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-resourcemanager</artifactId>
</dependency>
Konfiguration
Använda Event Hubs anslutningssträng direkt
Det enklaste sättet att ansluta till Event Hubs för Kafka är med anslutningssträng. Lägg bara till följande egenskap.
spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Använda Azure Resource Manager för att hämta anslutningssträng
Om du inte vill konfigurera anslutningssträng i ditt program kan du använda Azure Resource Manager för att hämta anslutningssträng. 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.
Kommentar
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 kan du läsa 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äng lägger du bara till följande egenskap.
spring:
cloud:
azure:
profile:
subscription-id: ${AZURE_SUBSCRIPTION_ID}
eventhubs:
namespace: ${AZURE_EVENTHUBS_NAMESPACE}
resource:
resource-group: ${AZURE_EVENTHUBS_RESOURCE_GROUP}
Exempel
Se lagringsplatsen azure-spring-boot-samples på GitHub.