Delen via

Ondersteuning voor Spring Cloud Azure Kafka

  • Artikel

Dit artikel is van toepassing op:✅ versie 4.19.0 ✅ versie 5.19.0

Vanaf versie 4.3.0 ondersteunt Spring Cloud Azure voor Kafka verschillende typen referenties voor verificatie en verbinding maken met Azure Event Hubs.

Ondersteunde Kafka-versie

De huidige versie van de starter moet compatibel zijn met Apache Kafka-clients 2.0.0 met java 8 of hoger.

Ondersteunde verificatietypen

De volgende verificatietypen worden ondersteund:

  • Verificatie van verbindingsreeks zonder opmaak
    • Directe verificatie van verbindingsreeksen
    • Verificatie van op ARM gebaseerde verbindingsreeks
  • Verificatie van OAuth-referenties
    • Verificatie van beheerde identiteit
    • Verificatie van gebruikersnaam/wachtwoord
    • Verificatie van service-principal
    • DefaultAzureCredential verificatie

Hoe het werkt

Verificatie van OAuth-referenties

In deze sectie wordt de algehele werkstroom van Spring Cloud Azure OAuth-verificatie beschreven.

Spring Cloud Azure bouwt eerst een van de volgende typen referenties, afhankelijk van de configuratie van de toepassingsverificatie:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Als geen van deze typen referenties wordt gevonden, wordt de referentieketen via DefaultAzureTokenCredential gebruikt om referenties te verkrijgen van toepassingseigenschappen, omgevingsvariabelen, beheerde identiteit of IDE's. Zie Spring Cloud Azure-verificatievoor gedetailleerde informatie.

Verificatie van verbindingsreeks zonder opmaak

Voor de verificatiemodus voor verbindingsreeksen kunt u verificatie van verbindingsreeksen rechtstreeks gebruiken of Azure Resource Manager gebruiken om de verbindingsreeks op te halen. Zie de sectie Basisgebruik voor verificatie van verbindingsreeksen voor meer informatie over het gebruik.

Notitie

Sinds versie 4.3.0 wordt verificatie van verbindingsreeksen afgeschaft ten gunste van OAuth-verificaties.

Configuratie

Configureerbare eigenschappen bij het gebruik van Kafka-ondersteuning met OAuth-verificatie

Spring Cloud Azure voor Kafka ondersteunt de volgende twee configuratieopties:

  1. Eigenschappen van Spring Cloud Azure voor Event Hubs Kafka.
  2. De algemene configuratieopties voor verificatie van credential en profile met voorvoegsels van spring.cloud.azure.
  3. Configuraties op kafka-specifiek niveau. De Kafka-configuraties zijn ook beschikbaar voor Spring Boot- en Spring Cloud Stream-binders voor common, consumer, producerof admin bereiken, met verschillende voorvoegsels.

De globale eigenschappen worden weergegeven via com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. De kafka-specifieke eigenschappen worden weergegeven via org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) en org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream-binder).

De volgende lijst bevat alle ondersteunde configuratieopties.

  • Eigenschappen van Spring Cloud Azure voor Event Hubs Kafka.

    • Eigenschap: spring.cloud.azure.eventhubs.kafka.enabled
    • Beschrijving: of u een gratis referentieverbinding met Azure Event Hubs voor Kafka wilt inschakelen, de standaardwaarde is true.

  • De configuratieopties voor globale verificatie van Spring Cloud Azure

    • Voorvoegsel: spring.cloud.azure
    • Ondersteunde opties: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Zie algemene configuratie-eigenschappenvoor de volledige lijst met algemene configuratieopties.

  • Algemene configuratie van Spring Boot Kafka

    • Voorvoegsel: spring.kafka.properties.azure
    • Voorbeeld: spring.kafka.properties.azure.credential.*

  • Configuratieopties voor Spring Kafka-consumenten

    • Voorvoegsel: spring.kafka.consumer.properties.azure
    • Voorbeeld: spring.kafka.consumer.properties.azure.credential.*

  • Configuratieopties voor Spring Kafka-producenten

    • Voorvoegsel: spring.kafka.producer.properties.azure
    • Voorbeeld: spring.kafka.producer.properties.azure.credential.*

  • Configuratieopties voor Spring Kafka-beheerders

    • Voorvoegsel: spring.kafka.admin.properties.azure
    • Voorbeeld: spring.kafka.admin.properties.azure.credential.*

  • Algemene configuratie van Spring Cloud Stream Kafka Binder

    • Voorvoegsel: spring.cloud.stream.kafka.binder.configuration.azure
    • Voorbeeld: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Spring Cloud Stream Kafka Binder-consumentenconfiguratie

    • Voorvoegsel: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Voorbeeld: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Configuratie van spring Cloud Stream Kafka Binder-producent

    • Voorvoegsel: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Voorbeeld: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Configuratie van De Binder-beheerder van Spring Cloud Stream Kafka

    • Voorvoegsel: Niet ondersteund, moet de algemene configuratie van Spring Boot Kafka of de beheerconfiguratie worden gebruikt.

In de volgende tabel ziet u de algemene configuratieopties voor Spring Boot Kafka:

Naam Beschrijving
spring.kafka.properties.azure.credential.client-certificate-password Wachtwoord van het certificaatbestand.
spring.kafka.properties.azure.credential.client-certificate-path Pad van een PEM-certificaatbestand dat moet worden gebruikt bij het uitvoeren van service-principalverificatie met Azure.
spring.kafka.properties.azure.credential.client-id Client-id die moet worden gebruikt bij het uitvoeren van service-principalverificatie met Azure. Dit is een verouderde eigenschap.
spring.kafka.properties.azure.credential.client-secret Clientgeheim dat moet worden gebruikt bij het uitvoeren van service-principal-verificatie met Azure. Dit is een verouderde eigenschap.
spring.kafka.properties.azure.credential.managed-identity-enabled Of beheerde identiteit moet worden geverifieerd met Azure. Als true en de client-id is ingesteld, gebruikt u de client-id als door de gebruiker toegewezen client-id voor beheerde identiteit. De standaardwaarde is onwaar.
spring.kafka.properties.azure.credential.password Wachtwoord dat moet worden gebruikt bij het uitvoeren van verificatie van gebruikersnaam en wachtwoord met Azure.
spring.kafka.properties.azure.credential.username Gebruikersnaam die moet worden gebruikt bij het uitvoeren van verificatie met gebruikersnaam en wachtwoord met Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Het Microsoft Entra-eindpunt waarmee verbinding moet worden gemaakt.
spring.kafka.properties.azure.profile.tenant-id Tenant-id voor Azure-resources. De waarden die zijn toegestaan voor tenant-id zijn: common, organizations, consumersof de tenant-id.

Notitie

De configuratieopties op verschillende niveaus zijn van toepassing op de volgende regels. De meer specifieke configuratieopties hebben een hogere prioriteit dan de algemene opties. Bijvoorbeeld:

  • Algemene configuratieopties van Spring Kafka vervangen de algemene opties.
  • Spring Kafka-configuratieopties vervangen de algemene opties.
  • Spring Kafka-configuratieopties vervangen de algemene opties.
  • Configuratieopties voor Spring Kafka-beheerders vervangen de algemene opties.
  • De opties voor Spring Cloud Stream Kafka Binder zijn net als hierboven.

Configureerbare eigenschappen bij het gebruik van Kafka-ondersteuning met verificatie van verbindingsreeksen zonder opmaak

In de volgende tabel ziet u de algemene configuratieopties voor Spring Boot Event Hubs voor Kafka:

Eigenschap Beschrijving
spring.cloud.azure.eventhubs.kafka.enabled Of u ondersteuning voor Azure Event Hubs Kafka wilt inschakelen. De standaardwaarde is waar.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs-verbindingsreeks. Geef deze waarde op wanneer u de verbindingsreeks rechtstreeks wilt opgeven.
spring.cloud.azure.eventhubs.namespace Azure Event Hubs-naamruimte. Geef deze waarde op wanneer u de verbindingsgegevens wilt ophalen via Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group De resourcegroep van de Azure Event Hubs-naamruimte. Geef deze waarde op wanneer u de verbindingsgegevens wilt ophalen via Azure Resource Manager.
spring.cloud.azure.profile.subscription-id De abonnements-id. Geef deze waarde op wanneer u de verbindingsgegevens wilt ophalen via Azure Resource Manager.

Afhankelijkheid instellen

Voeg de volgende afhankelijkheid toe aan uw project. Dit omvat automatisch de spring-boot-starter afhankelijkheid in uw projectovergang.

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

Notitie

Vergeet niet om de BOM-spring-cloud-azure-dependencies samen met de bovenstaande afhankelijkheid toe te voegen. Zie de sectie Aan de slag van de Spring Cloud Azure-ontwikkelaarshandleidingvoor meer informatie.

Basisgebruik

In de volgende secties ziet u de klassieke gebruiksscenario's voor Spring Boot-toepassingen.

OAuth-verificatie gebruiken

Wanneer u de OAuth-verificatie gebruikt die wordt geleverd door Spring Cloud Azure voor Kafka, kunt u de specifieke referenties configureren met behulp van de bovenstaande configuraties. U kunt er ook voor kiezen om niets te configureren over referenties. In dat geval laadt Spring Cloud Azure de referenties uit de omgeving. In deze sectie worden de gebruiksgegevens beschreven die de referenties laden vanuit de Azure CLI-omgeving of de Azure Spring Apps-hostingomgeving.

Notitie

Als u ervoor kiest om een beveiligingsprincipaal te gebruiken om te verifiëren en autoriseren met Microsoft Entra ID voor toegang tot een Azure-resource, raadpleegt u de sectie Toegang autoriseren met Microsoft Entra ID om ervoor te zorgen dat de beveiligingsprincipaal de juiste machtiging heeft gekregen voor toegang tot de Azure-resource.

In de volgende sectie worden de scenario's beschreven die gebruikmaken van verschillende Spring-ecosysteembibliotheken met OAuth-verificatie.

Ondersteuning voor Spring Kafka-toepassingen

In deze sectie wordt het gebruiksscenario voor de Spring Boot-toepassing beschreven met behulp van de Spring Kafka- of Spring Integration Kafka-bibliotheek.

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

Configuratie-update

Als u de OAuth-verificatie wilt gebruiken, geeft u alleen het Event Hubs-eindpunt op, zoals wordt weergegeven in het volgende voorbeeld:

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

Ondersteuning voor Kafka-toepassing voor Spring Cloud Stream-binder

In deze sectie wordt het gebruiksscenario voor Spring Boot-toepassingen beschreven met behulp van de Kafka-bibliotheek van Spring Cloud Stream- binder.

Afhankelijkheid instellen
<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>
Configuratie

Als u de OAuth-verificatie wilt gebruiken, geeft u het Event Hubs-eindpunt op, zoals wordt weergegeven in het volgende voorbeeld:

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

Notitie

Als u versie 4.3.0gebruikt, vergeet dan niet om de eigenschap spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration in te stellen om de hele OAuth-verificatiewerkstroom in te schakelen, waarbij kafka-binder-name standaard wordt kafka in één Kafka-bindertoepassing. De configuratie-AzureKafkaSpringCloudStreamConfiguration geeft de OAuth-beveiligingsparameters voor KafkaBinderConfigurationPropertiesop, die in KafkaOAuth2AuthenticateCallbackHandler wordt gebruikt om Azure Identity in te schakelen.

Voor versie na 4.4.0wordt deze eigenschap automatisch toegevoegd voor elke Kafka-binderomgeving. U hoeft deze dus niet handmatig toe te voegen.

Beheerde identiteit gebruiken voor OAuth-verificatie

  1. Als u de beheerde identiteit wilt gebruiken, moet u de beheerde identiteit voor uw service inschakelen en de rollen Azure Event Hubs Data Receiver en Azure Event Hubs Data Sender toewijzen. Zie Azure-rollen toewijzen voor toegangsrechtenvoor meer informatie.

  2. Configureer de volgende eigenschappen in uw application.yml-bestand:

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

    Belangrijk

    Als u een door de gebruiker toegewezen beheerde identiteit gebruikt, moet u ook de eigenschap toevoegen spring.cloud.azure.credential.client-id met de door de gebruiker toegewezen client-id van de beheerde identiteit.

Monsters

Zie de azure-spring-boot-samples opslagplaats op GitHub.

Verificatie van verbindingsreeksen gebruiken

U kunt verificatie van verbindingsreeksen rechtstreeks gebruiken of Azure Resource Manager gebruiken om de verbindingsreeks op te halen.

Notitie

Sinds versie 5.0.0, is bij het gebruik van verbindingsreeksverificatie met Spring Cloud Stream Framework nog steeds de volgende eigenschap vereist om ervoor te zorgen dat de verbindingsreeks van kracht kan worden, waarbij de waarde van <kafka-binder-name> moet worden kafka wanneer er geen aangepaste configuratie is voor de naam van uw Kafka-binder: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Als de versie van spring-cloud-dependencies die u hebt gebruikt, 2022.0.0is, ziet u een uitzondering op de java.lang.IllegalStateException: kafka_context has not been refreshed yet. Voer een upgrade uit naar een hogere versie om dit probleem op te lossen.

Afhankelijkheid instellen

Voeg de volgende afhankelijkheden toe als u uw Apache Kafka-toepassing wilt migreren om Azure Event Hubs voor Kafka te gebruiken.

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

Als u de verbindingsreeks wilt ophalen met behulp van Azure Resource Manager, voegt u de volgende afhankelijkheid toe:

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

Configuratie

Event Hubs-verbindingsreeks rechtstreeks gebruiken

De eenvoudigste manier om verbinding te maken met Event Hubs voor Kafka is met de verbindingsreeks. Voeg gewoon de volgende eigenschap toe.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Azure Resource Manager gebruiken om de verbindingsreeks op te halen

Als u de verbindingsreeks niet wilt configureren in uw toepassing, kunt u Azure Resource Manager gebruiken om de verbindingsreeks op te halen. Voor verificatie met Azure Resource Manager kunt u ook referenties gebruiken die zijn opgeslagen in Azure CLI of een ander lokaal ontwikkelprogramma, zoals Visual Studio Code of Intellij IDEA. U kunt ook Managed Identity gebruiken als uw toepassing is geïmplementeerd in Azure Cloud. Zorg ervoor dat de principal voldoende machtigingen heeft om metagegevens van resources te lezen.

Notitie

Als u ervoor kiest om een beveiligingsprincipaal te gebruiken om te verifiëren en autoriseren met Microsoft Entra ID voor toegang tot een Azure-resource, raadpleegt u de sectie Toegang autoriseren met Microsoft Entra ID om ervoor te zorgen dat aan de beveiligingsprincipaal de juiste machtiging is verleend voor toegang tot de Azure-resource.

Als u Azure Resource Manager wilt gebruiken om de verbindingsreeks op te halen, voegt u de volgende eigenschap toe.

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

Monsters

Zie de azure-spring-boot-samples opslagplaats op GitHub.