Freigeben über

Unterstützung für Spring Cloud Azure Kafka

  • Artikel

Dieser Artikel gilt für:✅ Version 4.19.0 ✅ Version 5.19.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

Die folgenden Authentifizierungstypen werden unterstützt:

  • Einfache Verbindungszeichenfolgenauthentifizierung
    • Direkte Verbindungszeichenfolgenauthentifizierung
    • ARM-basierte Verbindungszeichenfolgenauthentifizierung
  • Authentifizierung von OAuth-Anmeldeinformationen
    • Verwaltete Identitätsauthentifizierung
    • Benutzername/Kennwortauthentifizierung
    • Dienstprinzipalauthentifizierung
    • DefaultAzureCredential Authentifizierung

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 verwendet, um Anmeldeinformationen von Anwendungseigenschaften, Umgebungsvariablen, verwalteter Identität oder IDEs abzurufen. Ausführliche Informationen finden Sie unter Spring Cloud Azure authentication.

Einfache Verbindungszeichenfolgenauthentifizierung

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

Anmerkung

Seit Version 4.3.0 ist die Verbindungszeichenfolgenauthentifizierung 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.AzureGlobalPropertiesverfügbar gemacht. 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.*

    Eine 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 die client-id festgelegt ist, wird die Client-ID als vom Benutzer zugewiesene client-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 für tenant-id zulässigen Werte sind: common, organizations, consumersoder die Mandanten-ID.

Anmerkung

Die Konfigurationsoptionen in verschiedenen Ebenen gelten für die folgenden Regeln. Die spezifischeren Konfigurationsoptionen haben eine höhere Priorität als die gängigen. Zum 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 Verbindungszeichenfolgenauthentifizierung

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

Eigentum Beschreibung
spring.cloud.azure.eventhubs.kafka.enabled Gibt an, ob die Unterstützung von Azure Event Hubs Kafka aktiviert werden soll. Der Standardwert ist true.
spring.cloud.azure.eventhubs.connection-string Verbindungszeichenfolge für Azure Event Hubs. 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>

Anmerkung

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 Spring Cloud Azure-Entwicklerhandbuchs.

Grundlegende Nutzung

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

Verwenden der OAuth-Authentifizierung

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.

Anmerkung

Wenn Sie sich 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 des Zugriffs mit Microsoft Entra ID Abschnitt, 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>

Konfigurationsupdate

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

Anmerkung

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, wobei kafka-binder-name standardmäßig in einer einzelnen Kafka-Sammelmappenanwendung kafka ist. Die Konfiguration AzureKafkaSpringCloudStreamConfiguration gibt die OAuth-Sicherheitsparameter für KafkaBinderConfigurationPropertiesan, die in KafkaOAuth2AuthenticateCallbackHandler zum Aktivieren von Azure Identity verwendet werden.

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

Verwenden der verwalteten Identität für die OAuth-Authentifizierung

  1. Um die verwaltete Identität zu verwenden, müssen Sie die verwaltete Identität für Ihren Dienst aktivieren und die rollen Azure Event Hubs Data Receiver und Azure Event Hubs Data Sender zuweisen. Weitere Informationen finden Sie unter Zuweisen von Azure-Rollen für Zugriffsberechtigungen.

  2. Konfigurieren Sie die folgenden Eigenschaften in Ihrer application.yml Datei:

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

    Wichtig

    Wenn Sie die vom Benutzer zugewiesene verwaltete Identität verwenden, müssen Sie auch die Eigenschaft spring.cloud.azure.credential.client-id mit Ihrer vom Benutzer zugewiesenen verwalteten Identitätsclient-ID hinzufügen.

Proben

Sehen Sie sich die Azure-spring-boot-samples Repository auf GitHub an.

Verwenden der Verbindungszeichenfolgenauthentifizierung

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

Anmerkung

Seit Version 5.0.0 ist bei Verwendung der Verbindungszeichenfolgenauthentifizierung mit Spring Cloud Stream-Framework weiterhin die folgende Eigenschaft erforderlich, um sicherzustellen, dass die Verbindungszeichenfolge wirksam werden kann, wobei der Wert von <kafka-binder-name>kafka sein sollte, wenn keine angepasste Konfiguration für ihren Kafka-Ordnernamen vorhanden ist: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Wenn die verwendete Version von spring-cloud-dependencies2022.0.0ist, wird die Ausnahme der java.lang.IllegalStateException: kafka_context has not been refreshed yetauftreten. Um dieses Problem zu beheben, führen Sie ein Upgrade auf eine höhere Version durch.

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

Wenn Sie die Verbindungszeichenfolge in Ihrer Anwendung nicht konfigurieren möchten, können Sie 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.

Anmerkung

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 Abschnitt, 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}

Proben

Sehen Sie sich die Azure-spring-boot-samples Repository auf GitHub an.