Unterstützung für Spring Cloud Azure Kafka
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:
- Spring Cloud Azure für Event Hubs Kafka-Eigenschaften.
- Die globalen Authentifizierungskonfigurationsoptionen von
credential
undprofile
mit Präfixen vonspring.cloud.azure
. - Kafka-spezifische Levelkonfigurationen. Die Konfigurationen auf Kafka-Ebene sind auch für Spring Boot- und Spring Cloud Stream-Ordner für
common
, ,consumer
,producer
oderadmin
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
.
- Eigenschaft:
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.
- Präfix:
Allgemeine Konfiguration des Spring Boot Kafka
- Präfix:
spring.kafka.properties.azure
- Beispiel:
spring.kafka.properties.azure
.credential.*
- Präfix:
Konfigurationsoptionen für Spring Kafka-Consumer
- Präfix:
spring.kafka.consumer.properties.azure
- Beispiel:
spring.kafka.consumer.properties.azure
.credential.*
- Präfix:
Konfigurationsoptionen für Spring Kafka-Produzenten
- Präfix:
spring.kafka.producer.properties.azure
- Beispiel:
spring.kafka.producer.properties.azure
.credential.*
- Präfix:
Konfigurationsoptionen für Spring Kafka-Administratoren
- Präfix:
spring.kafka.admin.properties.azure
- Beispiel:
spring.kafka.admin.properties.azure
.credential.*
- Präfix:
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.*
- Präfix:
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.*
- Präfix:
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.*
- Präfix:
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.0
verwenden, 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 KafkaBinderConfigurationProperties
die 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.