Prise en charge d’Azure Kafka Azure Spring Cloud

Cet article s’applique à : ✔️ Version 4.14.0 ✔️ Version 5.8.0

À partir de la version 4.3.0, Spring Cloud Azure pour Kafka prend en charge différents types d’informations d’identification pour authentifier et se connecter à Azure Event Hubs.

Version de Kafka prise en charge

La version actuelle du starter doit être compatible avec Apache Kafka Clients 2.0.0 à l’aide de Java 8 ou version ultérieure.

Types d’authentification pris en charge

Les types d’authentification suivants sont pris en charge :

• Authentification chaîne de connexion simple
  • Authentification directe chaîne de connexion
  • Authentification chaîne de connexion basée sur ARM
• Authentification des informations d’identification OAuth
  • Authentification d’une identité managée
  • Authentification par nom d’utilisateur/mot de passe
  • Authentification d’un principal du service
  • l’authentification DefaultAzureCredential

Fonctionnement

Authentification des informations d’identification OAuth

Cette section décrit le flux de travail global de l’authentification OAuth Spring Cloud Azure.

Spring Cloud Azure crée d’abord l’un des types d’informations d’identification suivants en fonction de la configuration de l’authentification de l’application :

• ClientSecretCredential
• ClientCertificateCredential
• UsernamePasswordCredential
• ManagedIdentityCredential

Si aucun de ces types d’informations d’identification n’est trouvé, la chaîne d’informations d’identification est DefaultAzureTokenCredential utilisée pour obtenir des informations d’identification à partir des propriétés de l’application, des variables d’environnement, de l’identité managée ou des IDE. Pour plus d’informations, consultez l’authentification Spring Cloud Azure.

Authentification chaîne de connexion simple

Pour le mode d’authentification chaîne de connexion, vous pouvez utiliser l’authentification chaîne de connexion directement ou utiliser Azure Resource Manager pour récupérer le chaîne de connexion. Pour plus d’informations sur l’utilisation, consultez la section Utilisation de base pour chaîne de connexion l’authentification.

Remarque

Depuis la version 4.3.0, chaîne de connexion l’authentification est déconseillée en faveur des authentifications OAuth.

Configuration

Propriétés configurables lors de l’utilisation de la prise en charge de Kafka avec l’authentification OAuth

Spring Cloud Azure pour Kafka prend en charge les deux niveaux suivants d’options de configuration :

1. Propriétés Spring Cloud Azure pour Event Hubs Kafka.
2. Options de configuration d’authentification globale des credentialprofile préfixes spring.cloud.azure.
3. Configurations de niveau spécifiques à Kafka. Les configurations kafka sont également disponibles pour les classeurs Spring Boot et Spring Cloud Stream pour common, consumer, producerou admin étendues, qui ont des préfixes différents.

Les propriétés globales sont exposées via com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Les propriétés propres à Kafka sont exposées via org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) et org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (classeur Spring Cloud Stream).

La liste suivante montre toutes les options de configuration prises en charge.

• Propriétés Spring Cloud Azure pour Event Hubs Kafka.

  • Propriété: spring.cloud.azure.eventhubs.kafka.enabled
  • Description : indique s’il faut activer la connexion gratuite des informations d’identification à Azure Event Hubs pour Kafka, la valeur par défaut est true.

• Options de configuration de l’authentification globale Spring Cloud Azure

  • Préfixe : spring.cloud.azure
  • Options prises en charge : spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

  Pour obtenir la liste complète des options de configuration globale, consultez les propriétés de configuration globale.

• Configuration courante spring Boot Kafka

  • Préfixe : spring.kafka.properties.azure
  • Exemple : spring.kafka.properties.azure.credential.*

• Options de configuration du consommateur Spring Kafka

  • Préfixe : spring.kafka.consumer.properties.azure
  • Exemple : spring.kafka.consumer.properties.azure.credential.*

• Options de configuration du producteur Spring Kafka

  • Préfixe : spring.kafka.producer.properties.azure
  • Exemple : spring.kafka.producer.properties.azure.credential.*

• Options de configuration de l’administrateur Spring Kafka

  • Préfixe : spring.kafka.admin.properties.azure
  • Exemple : spring.kafka.admin.properties.azure.credential.*

• Configuration courante de Spring Cloud Stream Kafka Binder

  • Préfixe : spring.cloud.stream.kafka.binder.configuration.azure
  • Exemple : spring.cloud.stream.kafka.binder.configuration.azure.credential.*

• Configuration du consommateur Spring Cloud Stream Kafka Binder

  • Préfixe : spring.cloud.stream.kafka.binder.consumer-properties.azure
  • Exemple : spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

• Configuration du producteur Spring Cloud Stream Kafka Binder

  • Préfixe : spring.cloud.stream.kafka.binder.producer-properties.azure
  • Exemple : spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

• Configuration de l’administrateur Spring Cloud Stream Kafka Binder

  • Préfixe : Non pris en charge, doit utiliser la configuration commune ou administrateur spring Boot Kafka.

Le tableau suivant présente les options de configuration courantes de Spring Boot Kafka :

Nom	Description
spring.kafka.properties.azure.credential.client-certificate-password	Mot de passe du fichier de certificat.
spring.kafka.properties.azure.credential.client-certificate-path	Chemin d’un fichier de certificat PEM à utiliser lors de l’authentification du principal de service avec Azure.
spring.kafka.properties.azure.credential.client-id	ID client à utiliser lors de l’authentification du principal de service avec Azure. Il s’agit d’une propriété héritée.
spring.kafka.properties.azure.credential.client-secret	Clé secrète client à utiliser lors de l’authentification du principal de service avec Azure. Il s’agit d’une propriété héritée.
spring.kafka.properties.azure.credential.managed-identity-enabled	Indique s’il faut activer l’identité managée pour s’authentifier auprès d’Azure. Si la valeur est true et que la client-id valeur est définie, utilisez l’ID client en tant qu’ID client d’identité managée affecté par l’utilisateur. La valeur par défaut est false (Faux).
spring.kafka.properties.azure.credential.password	Mot de passe à utiliser lors de l’exécution de l’authentification par nom d’utilisateur/mot de passe avec Azure.
spring.kafka.properties.azure.credential.username	Nom d’utilisateur à utiliser lors de l’exécution de l’authentification par nom d’utilisateur/mot de passe avec Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint	Point de terminaison Microsoft Entra auquel se connecter.
spring.kafka.properties.azure.profile.tenant-id	ID de locataire pour les ressources Azure. Les valeurs autorisées tenant-id sont : common, organizations, consumersou l’ID de locataire.

Remarque

Les options de configuration de différents niveaux appliquent les règles suivantes. Les options de configuration plus spécifiques ont une priorité plus élevée que les options courantes. Par exemple :

• Les options de configuration courantes spring Kafka remplacent les options globales.
• Les options de configuration du consommateur Spring Kafka remplacent les options courantes.
• Les options de configuration du producteur Spring Kafka remplacent les options courantes.
• Les options de configuration de l’administrateur Spring Kafka remplacent les options courantes.
• Les options Spring Cloud Stream Kafka Binder sont tout comme celles ci-dessus.

Propriétés configurables lors de l’utilisation de la prise en charge de Kafka avec l’authentification simple chaîne de connexion

Le tableau suivant présente les hubs d’événements Spring Boot pour les options de configuration courantes de Kafka :

Propriété	Description
spring.cloud.azure.eventhubs.kafka.enabled	Indique s’il faut activer la prise en charge d’Azure Event Hubs Kafka. La valeur par défaut est true.
spring.cloud.azure.eventhubs.connection-string	Azure Event Hubs chaîne de connexion. Fournissez cette valeur lorsque vous souhaitez fournir la chaîne de connexion directement.
spring.cloud.azure.eventhubs.namespace	Espace de noms Azure Event Hubs. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group	Groupe de ressources de l’espace de noms Azure Event Hubs. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.
spring.cloud.azure.profile.subscription-id	L'ID de l'abonnement. Indiquez cette valeur lorsque vous souhaitez récupérer les informations de connexion via Azure Resource Manager.

Configuration des dépendances

Ajoutez la dépendance suivante à votre projet. Cela inclut automatiquement la spring-boot-starter dépendance dans votre projet transitivement.

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

Remarque

N’oubliez pas d’ajouter le boM spring-cloud-azure-dependencies avec la dépendance ci-dessus. Pour plus d’informations, consultez la section Prise en main du guide du développeur Spring Cloud Azure.

Utilisation de base

Les sections suivantes montrent les scénarios d’utilisation classiques de l’application Spring Boot.

Utiliser l’authentification OAuth

Lorsque vous utilisez l’authentification OAuth fournie par Spring Cloud Azure pour Kafka, vous pouvez configurer les informations d’identification spécifiques à l’aide des configurations ci-dessus. Vous pouvez également choisir de configurer des informations d’identification, auquel cas Spring Cloud Azure charge les informations d’identification à partir de l’environnement. Cette section décrit les utilisations qui chargent les informations d’identification à partir de l’environnement Azure CLI ou de l’environnement d’hébergement Azure Spring Apps.

Remarque

Si vous choisissez d’utiliser un principal de sécurité pour authentifier et autoriser avec Microsoft Entra ID pour accéder à une ressource Azure, consultez la section Autoriser l’accès avec l’ID Microsoft Entra pour vous assurer que le principal de sécurité a reçu l’autorisation suffisante pour accéder à la ressource Azure.

La section suivante décrit les scénarios utilisant différentes bibliothèques d’écosystèmes Spring avec l’authentification OAuth.

Prise en charge des applications Spring Kafka

Cette section décrit le scénario d’utilisation de l’application Spring Boot à l’aide de la bibliothèque Spring Kafka ou Spring Integration Kafka.

Configuration des dépendances

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

Mise à jour de la configuration

Pour utiliser l’authentification OAuth, spécifiez simplement le point de terminaison Event Hubs, comme illustré dans l’exemple suivant :

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

Prise en charge de l’application Kafka du classeur Spring Cloud Stream

Cette section décrit le scénario d’utilisation pour les applications Spring Boot à l’aide de la bibliothèque Kafka du classeur Spring Cloud Stream.

Configuration des dépendances

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

Configuration

Pour utiliser l’authentification OAuth, spécifiez simplement le point de terminaison Event Hubs, comme indiqué dans l’exemple suivant :

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

Remarque

Si vous utilisez la version 4.3.0, n’oubliez pas de définir la spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration propriété pour activer l’ensemble du flux de travail d’authentification OAuth, où kafka-binder-name se trouve kafka par défaut dans une application de classeur Kafka unique. La configuration AzureKafkaSpringCloudStreamConfiguration spécifie les paramètres de sécurité OAuth pour KafkaBinderConfigurationProperties, qui sont utilisés pour KafkaOAuth2AuthenticateCallbackHandler activer Azure Identity.

Pour la version après 4.4.0, cette propriété est ajoutée automatiquement pour chaque environnement de classeur Kafka. Vous n’avez donc pas besoin de l’ajouter manuellement.

Exemples

Consultez le référentiel azure-spring-boot-samples sur GitHub.

Utiliser l’authentification chaîne de connexion

Vous pouvez utiliser l’authentification chaîne de connexion directement ou utiliser Azure Resource Manager pour récupérer le chaîne de connexion.

Spring Cloud Azure 4.x

Remarque

Depuis la version 4.3.0, chaîne de connexion l’authentification est déconseillée en faveur des authentifications OAuth.

Depuis la version 4.5.0, lors de l’utilisation de l’authentification chaîne de connexion avec Spring Cloud Stream Framework, la propriété suivante est requise pour vous assurer que l’chaîne de connexion peut prendre effet, où la valeur <kafka-binder-name> doit être kafka lorsqu’il n’existe aucune configuration personnalisée pour votre nom de classeur Kafka.

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

Spring Cloud Azure 5.x

Remarque

Depuis la version 5.0.0, lorsque vous utilisez chaîne de connexion authentification avec Spring Cloud Stream Framework, la propriété suivante est toujours nécessaire pour vous assurer que le chaîne de connexion peut prendre effet, où la valeur <kafka-binder-name> doit être kafka lorsqu’il n’existe aucune configuration personnalisée pour votre nom de classeur Kafka.

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

Si la version utilisée spring-cloud-dependencies est 2022.0.0, vous rencontrerez l’exception java.lang.IllegalStateException: kafka_context has not been refreshed yet. Pour résoudre ce problème, effectuez une mise à niveau vers une version ultérieure.

Configuration des dépendances

Ajoutez les dépendances suivantes si vous souhaitez migrer votre application Apache Kafka pour utiliser Azure Event Hubs pour Kafka.

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

Si vous souhaitez récupérer le chaîne de connexion à l’aide d’Azure Resource Manager, ajoutez la dépendance suivante :

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

Configuration

Utiliser les chaîne de connexion Event Hubs directement

La façon la plus simple de se connecter à Event Hubs pour Kafka est avec la chaîne de connexion. Ajoutez simplement la propriété suivante.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

Utiliser Azure Resource Manager pour récupérer chaîne de connexion

Si vous ne souhaitez pas configurer la chaîne de connexion dans votre application, vous pouvez utiliser Azure Resource Manager pour récupérer le chaîne de connexion. Pour vous authentifier auprès d’Azure Resource Manager, vous pouvez également utiliser des informations d’identification stockées dans Azure CLI ou un autre outil de développement local tel que Visual Studio Code ou Intellij IDEA. Vous pouvez également utiliser Managed Identity si votre application est déployée sur Azure Cloud. Assurez-vous que le principal dispose d’une autorisation suffisante pour lire les métadonnées de ressource.

Remarque

Si vous choisissez d’utiliser un principal de sécurité pour authentifier et autoriser avec Microsoft Entra ID pour accéder à une ressource Azure, consultez la section Autoriser l’accès avec l’ID Microsoft Entra pour vous assurer que le principal de sécurité a reçu l’autorisation suffisante pour accéder à la ressource Azure.

Pour utiliser Azure Resource Manager pour récupérer le chaîne de connexion, ajoutez simplement la propriété suivante.

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

Exemples

Consultez le référentiel azure-spring-boot-samples sur GitHub.