Ondersteuning voor Spring Cloud Azure Kafka

Ondersteuning voor Spring Cloud Azure Kafka helpt Spring-toepassingen bij het verifiëren en maken van verbinding met Azure Event Hubs met behulp van OAuth-referenties of verbindingsreeksen. In dit artikel worden de ondersteunde verificatietypen, configuratieopties, afhankelijkheden en gebruiksscenario's beschreven.

Ondersteunde Kafka-versie

De huidige versie van de starter is compatibel met Apache Kafka-clients 2.0.0 en gebruikt Java 8 of hoger.

Ondersteunde verificatietypen

De starter ondersteunt de volgende verificatietypen:

• Authenticatie met een gewone verbindingsreeks
  • Directe verificatie van verbindingsreeksen
  • Verificatie met een ARM-gebaseerde verbindingsreeks
• Verificatie van OAuth-referenties
  • Verificatie van beheerde identiteit
  • Verificatie van gebruikersnaam/wachtwoord
  • Authenticatie van service-principals
  • 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 de toepassing geen van deze typen referenties gebruikt, gebruikt de toepassing de referentieketen DefaultAzureTokenCredential om referenties op te halen uit toepassingseigenschappen, omgevingsvariabelen, beheerde identiteit of IDE's. Zie Spring Cloud Azure-verificatievoor gedetailleerde informatie.

Authenticatie met een gewone verbindingsreeks

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.

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. Kafka-specifieke configuraties. De configuraties op Kafka-niveau zijn ook beschikbaar voor Spring Boot- en Spring Cloud Stream-binders voor de scopes common, consumer, producer of admin, die verschillende voorvoegsels hebben.

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

• Producentconfiguratie van Spring Cloud Stream Kafka Binder

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

• Adminconfiguratie van Spring Cloud Stream Kafka Binder

  • Voorvoegsel: Niet ondersteund, gebruik algemene configuratie of beheerconfiguratie van Spring Boot Kafka.

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

Configureerbare eigenschappen bij gebruik van Kafka-ondersteuning met authenticatie via een eenvoudige verbindingsreeks

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

Afhankelijkheid instellen

Voeg de volgende afhankelijkheid toe aan uw project. Deze afhankelijkheid bevat automatisch de spring-boot-starter afhankelijkheid in uw project.

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

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 door Spring Cloud Azure voor Kafka wordt geboden, kunt u specifieke referenties configureren met behulp van de voorgaande configuraties. U kunt er ook voor kiezen om geen inloggegevens te configureren. In dit geval laadt Spring Cloud Azure de inloggegevens vanuit de omgeving. In deze sectie wordt beschreven hoe u referenties laadt vanuit de Azure CLI-omgeving of de Azure Spring Apps hostingomgeving.

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

Ondersteuning voor Spring Kafka-toepassingen

In deze sectie wordt het gebruiksscenario beschreven voor een Spring Boot-toepassing die gebruikmaakt van Spring Kafka of de 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>

Update van de configuratie

Als u OAuth-verificatie wilt gebruiken, geeft u 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 beschreven voor Spring Boot-toepassingen die gebruikmaken van de Kafka-bibliotheek van Spring Cloud Stream.

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

Beheerde identiteit gebruiken voor OAuth-verificatie

1. Als u beheerde identiteit wilt gebruiken, schakelt u beheerde identiteit voor uw service in en wijst u de Azure Event Hubs Data Receiver en Azure Event Hubs Data Sender rollen toe. 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, voegt u ook de eigenschap spring.cloud.azure.credential.client-id toe met de client-id van uw door de gebruiker toegewezen beheerde identiteit.

Voorbeelden

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

Authenticatie met een verbindingsreeks gebruiken

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

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.

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}

Voorbeelden

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