Share via

Unterstützung für Spring Cloud Azure Kafka

  • Artikel

Dieser Artikel bezieht sich auf: ✔️ Version 4.14.0 ✔️ Version 5.8.0

Ab Version 4.3.0 unterstützt Spring Cloud Azure für Kafka verschiedene Arten von Anmeldeinformationen zum Authentifizieren und Herstellen einer Verbindung mit Azure Event Hubs.

Unterstützte Kafka-Version

Die aktuelle Version des Starters sollte mit Apache Kafka Clients 2.0.0 mit Java 8 oder höher kompatibel sein.

Unterstützte Authentifizierungstypen

Folgende Authentifizierungstypen werden nicht unterstützt:

  • Einfache Verbindungszeichenfolge-Authentifizierung
    • Direkte Verbindungszeichenfolge-Authentifizierung
    • ARM-basierte Verbindungszeichenfolge-Authentifizierung
  • Authentifizierung von OAuth-Anmeldeinformationen
    • Authentifizierung der verwalteten Identität
    • Authentifizierung mit Benutzername/Kennwort
    • Dienstprinzipalauthentifizierung
    • Authentifizierung per DefaultAzureCredential

Funktionsweise

Authentifizierung von OAuth-Anmeldeinformationen

In diesem Abschnitt wird der allgemeine Workflow der Spring Cloud OAuth-Authentifizierung beschrieben.

Spring Cloud Azure erstellt zunächst einen der folgenden Arten von Anmeldeinformationen, je nach Anwendungsauthentifizierungskonfiguration:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Wenn keine dieser Arten von Anmeldeinformationen gefunden wird, wird die Anmeldeinformationskette über DefaultAzureTokenCredential die Anmeldeinformationen verwendet, um Anmeldeinformationen von Anwendungseigenschaften, Umgebungsvariablen, verwalteter Identität oder IDEs abzurufen. Ausführliche Informationen finden Sie unter Spring Cloud Azure-Authentifizierung.

Einfache Verbindungszeichenfolge-Authentifizierung

Für den Verbindungszeichenfolge Authentifizierungsmodus können Sie Verbindungszeichenfolge Authentifizierung direkt verwenden oder den Azure Resource Manager verwenden, um die Verbindungszeichenfolge abzurufen. Weitere Informationen zur Verwendung finden Sie im Abschnitt "Grundlegende Verwendung für Verbindungszeichenfolge Authentifizierung".

Hinweis

Seit Version 4.3.0 ist Verbindungszeichenfolge Authentifizierung zugunsten von OAuth-Authentifizierungen veraltet.

Konfiguration

Konfigurierbare Eigenschaften bei Verwendung der Kafka-Unterstützung mit OAuth-Authentifizierung

Spring Cloud Azure für Kafka unterstützt die folgenden beiden Konfigurationsoptionen:

  1. Spring Cloud Azure für Event Hubs Kafka-Eigenschaften.
  2. Die globalen Authentifizierungskonfigurationsoptionen von credential und profile mit Präfixen von spring.cloud.azure.
  3. Kafka-spezifische Levelkonfigurationen. Die Konfigurationen auf Kafka-Ebene sind auch für Spring Boot- und Spring Cloud Stream-Ordner für common, , consumer, produceroder admin Bereiche verfügbar, die unterschiedliche Präfixe haben.

Die globalen Eigenschaften werden über com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Die kafka-spezifischen Eigenschaften werden über org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) und org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream Binder) verfügbar gemacht.

In der folgenden Liste sind alle unterstützten Konfigurationsoptionen aufgeführt.

  • Spring Cloud Azure für Event Hubs Kafka-Eigenschaften.

    • Eigenschaft: spring.cloud.azure.eventhubs.kafka.enabled
    • Beschreibung: Gibt an, ob die kostenlose Verbindung mit Anmeldeinformationen zu Azure Event Hubs für Kafka aktiviert werden soll, der Standardwert ist true.

  • Die Konfigurationsoptionen für die globale Azure-Authentifizierung in Spring Cloud

    • Präfix: spring.cloud.azure
    • Unterstützte Optionen: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Die vollständige Liste der globalen Konfigurationsoptionen finden Sie unter globalen Konfigurationseigenschaften.

  • Allgemeine Konfiguration des Spring Boot Kafka

    • Präfix: spring.kafka.properties.azure
    • Beispiel: spring.kafka.properties.azure.credential.*

  • Konfigurationsoptionen für Spring Kafka-Consumer

    • Präfix: spring.kafka.consumer.properties.azure
    • Beispiel: spring.kafka.consumer.properties.azure.credential.*

  • Konfigurationsoptionen für Spring Kafka-Produzenten

    • Präfix: spring.kafka.producer.properties.azure
    • Beispiel: spring.kafka.producer.properties.azure.credential.*

  • Konfigurationsoptionen für Spring Kafka-Administratoren

    • Präfix: spring.kafka.admin.properties.azure
    • Beispiel: spring.kafka.admin.properties.azure.credential.*

  • Allgemeine Konfiguration von Spring Cloud Stream Kafka Binder

    • Präfix: spring.cloud.stream.kafka.binder.configuration.azure
    • Beispiel: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Spring Cloud Stream Kafka Binder Consumer Configuration

    • Präfix: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Beispiel: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Feder Cloud Stream Kafka Binder Producer-Konfiguration

    • Präfix: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Beispiel: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Feder Cloud Stream Kafka Binder-Administratorkonfiguration

    • Präfix: Nicht unterstützt, sollte die allgemeine Spring Boot Kafka- oder Administratorkonfiguration verwenden.

Die folgende Tabelle zeigt die allgemeinen Konfigurationsoptionen für Spring Boot Kafka:

Name Beschreibung
spring.kafka.properties.azure.credential.client-certificate-password Kennwort der Zertifikatdatei.
spring.kafka.properties.azure.credential.client-certificate-path Pfad einer PEM-Zertifikatdatei, die beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll.
spring.kafka.properties.azure.credential.client-id Client-ID, die beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll. Dies ist eine legacy-Eigenschaft.
spring.kafka.properties.azure.credential.client-secret Geheimer Clientschlüssel, der beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll. Dies ist eine legacy-Eigenschaft.
spring.kafka.properties.azure.credential.managed-identity-enabled Gibt an, ob verwaltete Identität für die Authentifizierung mit Azure aktiviert werden soll. Wenn "true " und " client-id festgelegt" festgelegt ist, wird die Client-ID als vom Benutzer zugewiesene verwaltete Identitätsclient-ID verwendet. Der Standardwert ist false.
spring.kafka.properties.azure.credential.password Kennwort, das bei der Authentifizierung mit Benutzername/Kennwort mit Azure verwendet werden soll.
spring.kafka.properties.azure.credential.username Benutzername, der bei der Authentifizierung mit Benutzername/Kennwort mit Azure verwendet werden soll.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Der Microsoft Entra-Endpunkt, mit dem eine Verbindung hergestellt werden soll.
spring.kafka.properties.azure.profile.tenant-id Mandanten-ID für Azure-Ressourcen. Die zulässigen tenant-id Werte sind: common, , organizations, consumers, oder die Mandanten-ID.

Hinweis

Die Konfigurationsoptionen in verschiedenen Ebenen gelten für die folgenden Regeln. Die spezifischeren Konfigurationsoptionen haben eine höhere Priorität als die gängigen. Beispiel:

  • Die allgemeinen Konfigurationsoptionen von Spring Kafka ersetzen die globalen Optionen.
  • Spring Kafka Consumer-Konfigurationsoptionen ersetzen die allgemeinen Optionen.
  • Die Konfigurationsoptionen des Spring Kafka-Herstellers ersetzen die allgemeinen Optionen.
  • Die Konfigurationsoptionen für Spring Kafka-Administratoren ersetzen die allgemeinen Optionen.
  • Die Spring Cloud Stream Kafka Binder-Optionen sind genau wie oben beschrieben.

Konfigurierbare Eigenschaften bei Verwendung der Kafka-Unterstützung mit einfacher Verbindungszeichenfolge-Authentifizierung

In der folgenden Tabelle sind die allgemeinen Konfigurationsoptionen für Kafka für Spring Boot Event Hubs aufgeführt:

Eigenschaft Beschreibung
spring.cloud.azure.eventhubs.kafka.enabled Gibt an, ob die Unterstützung von Azure Event Hubs Kafka aktiviert werden soll. Der Standardwert lautet true.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs Verbindungszeichenfolge. Geben Sie diesen Wert an, wenn Sie die Verbindungszeichenfolge direkt bereitstellen möchten.
spring.cloud.azure.eventhubs.namespace Azure Event Hubs-Namespace. Geben Sie diesen Wert an, wenn Sie die Verbindungsinformationen über Azure Resource Manager abrufen möchten.
spring.cloud.azure.eventhubs.resource.resource-group Die Ressourcengruppe des Azure Event Hubs-Namespace. Geben Sie diesen Wert an, wenn Sie die Verbindungsinformationen über Azure Resource Manager abrufen möchten.
spring.cloud.azure.profile.subscription-id Die Abonnement-ID. Geben Sie diesen Wert an, wenn Sie die Verbindungsinformationen über Azure Resource Manager abrufen möchten.

Setup von Abhängigkeiten

Fügen Sie dem Projekt die folgende Abhängigkeit hinzu. Dies schließt automatisch die spring-boot-starter Abhängigkeit in Ihr Projekt transitiv ein.

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

Hinweis

Denken Sie daran, die BOM spring-cloud-azure-dependencies zusammen mit der oben genannten Abhängigkeit hinzuzufügen. Ausführliche Informationen finden Sie im Abschnitt "Erste Schritte " des Azure-Entwicklerhandbuchs für Spring Cloud.

Grundlegende Verwendung

Die folgenden Abschnitte zeigen die klassischen Anwendungsverwendungsszenarien für Spring Boot.

OAuth-Authentifizierung verwenden

Wenn Sie die OAuth-Authentifizierung verwenden, die von Spring Cloud Azure für Kafka bereitgestellt wird, können Sie die spezifischen Anmeldeinformationen mithilfe der oben genannten Konfigurationen konfigurieren. Alternativ können Sie keine Informationen zu Anmeldeinformationen konfigurieren. In diesem Fall lädt Spring Cloud Azure die Anmeldeinformationen aus der Umgebung. In diesem Abschnitt werden die Verwendungen beschrieben, die die Anmeldeinformationen aus der Azure CLI-Umgebung oder der Azure Spring Apps-Hostingumgebung laden.

Hinweis

Wenn Sie sich dafür entscheiden, einen Sicherheitsprinzipal zum Authentifizieren und Autorisieren mit Microsoft Entra-ID für den Zugriff auf eine Azure-Ressource zu verwenden, lesen Sie den Abschnitt "Autorisieren des Zugriffs mit Microsoft Entra ID ", um sicherzustellen, dass dem Sicherheitsprinzipal die ausreichende Berechtigung für den Zugriff auf die Azure-Ressource gewährt wurde.

Im folgenden Abschnitt werden die Szenarien beschrieben, in denen verschiedene Spring-Ökosystembibliotheken mit OAuth-Authentifizierung verwendet werden.

Unterstützung der Spring Kafka-Anwendung

In diesem Abschnitt wird das Verwendungsszenario für spring boot application using Spring Kafka or Spring Integration Kafka library beschrieben.

Setup von Abhängigkeiten
<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>

Aktualisierung der Konfiguration

Um die OAuth-Authentifizierung zu verwenden, geben Sie einfach den Event Hubs-Endpunkt an, wie im folgenden Beispiel gezeigt:

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

Unterstützung der Feder Cloud Stream-Ordner-Kafka-Anwendung

In diesem Abschnitt wird das Verwendungsszenario für Spring Boot-Anwendungen mit der Feder Cloud Stream-Ordner-Kafka-Bibliothek beschrieben.

Setup von Abhängigkeiten
<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

Um die OAuth-Authentifizierung zu verwenden, geben Sie einfach den Event Hubs-Endpunkt an, wie im folgenden Beispiel gezeigt:

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

Hinweis

Wenn Sie Version 4.3.0verwenden, vergessen Sie nicht, die spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration Eigenschaft so festzulegen, dass der gesamte OAuth-Authentifizierungsworkflow aktiviert wird, wo kafka-binder-name sich standardmäßig in einer einzelnen Kafka-Sammelmappenanwendung befindet kafka . Die Konfiguration AzureKafkaSpringCloudStreamConfiguration gibt die OAuth-Sicherheitsparameter an, für KafkaBinderConfigurationPropertiesdie Azure Identity aktiviert KafkaOAuth2AuthenticateCallbackHandler wird.

Für version after 4.4.0, this property will be added automatically for each Kafka binder environment, so there's no need for you to add it manually.

Beispiele

Siehe das Azure-spring-boot-samples-Repository auf GitHub.

Verwenden Verbindungszeichenfolge Authentifizierung

Sie können Verbindungszeichenfolge Authentifizierung direkt verwenden oder den Azure Resource Manager verwenden, um die Verbindungszeichenfolge abzurufen.

Hinweis

Seit Version 4.3.0 ist Verbindungszeichenfolge Authentifizierung zugunsten von OAuth-Authentifizierungen veraltet.

Da version of 4.5.0, when using Verbindungszeichenfolge authentication with Spring Cloud Stream framework, the following property is required to ensure that the Verbindungszeichenfolge can take effect, where the value of <kafka-binder-name> should be kafka when there is no custom configuration for your Kafka binder name.

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

Setup von Abhängigkeiten

Fügen Sie die folgenden Abhängigkeiten hinzu, wenn Sie Ihre Apache Kafka-Anwendung migrieren möchten, um Azure Event Hubs für Kafka zu verwenden.

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

Wenn Sie die Verbindungszeichenfolge mit Azure Resource Manager abrufen möchten, fügen Sie die folgende Abhängigkeit hinzu:

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

Konfiguration

Verwenden von Event Hubs Verbindungszeichenfolge direkt

Die einfachste Möglichkeit zum Herstellen einer Verbindung mit Event Hubs für Kafka ist die Verbindungszeichenfolge. Fügen Sie einfach die folgende Eigenschaft hinzu.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Verwenden von Azure Resource Manager zum Abrufen von Verbindungszeichenfolge

Wenn Sie die Verbindungszeichenfolge in Ihrer Anwendung nicht konfigurieren möchten, können Sie den Azure Resource Manager verwenden, um die Verbindungszeichenfolge abzurufen. Um sich bei Azure Resource Manager zu authentifizieren, können Sie auch Anmeldeinformationen verwenden, die in Azure CLI oder einem anderen lokalen Entwicklungstool wie Visual Studio Code oder Intellij IDEA gespeichert sind. Alternativ können Sie verwaltete Identität verwenden, wenn Ihre Anwendung in Azure Cloud bereitgestellt wird. Stellen Sie nur sicher, dass der Prinzipal über ausreichende Berechtigungen zum Lesen von Ressourcenmetadaten verfügt.

Hinweis

Wenn Sie sich dafür entscheiden, einen Sicherheitsprinzipal für die Authentifizierung und Autorisierung mit Microsoft Entra-ID für den Zugriff auf eine Azure-Ressource zu verwenden, lesen Sie den Abschnitt "Autorisieren" mit Microsoft Entra ID , um sicherzustellen, dass dem Sicherheitsprinzipal die ausreichende Berechtigung für den Zugriff auf die Azure-Ressource gewährt wurde.

Um azure Resource Manager zum Abrufen der Verbindungszeichenfolge zu verwenden, fügen Sie einfach die folgende Eigenschaft hinzu.

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

Beispiele

Siehe das Azure-spring-boot-samples-Repository auf GitHub.