Share via

Compatibilidad con Azure Kafka de Spring Cloud

  • Artículo

Este artículo se aplica a: ✔️ Versión 4.14.0 ✔️ versión 5.8.0

Desde la versión 4.3.0, Spring Cloud Azure for Kafka admite varios tipos de credenciales para autenticarse y conectarse a Azure Event Hubs.

Versión de Kafka compatible

La versión actual del inicio debe ser compatible con Apache Kafka Clients 2.0.0 con Java 8 o posterior.

Tipos de autenticación que se admiten

Se admiten los siguientes tipos de autenticación:

  • Autenticación de cadena de conexión sin formato
    • Autenticación directa de cadena de conexión
    • Autenticación de cadena de conexión basada en ARM
  • Autenticación de credenciales de OAuth
    • Autenticación de identidad administrada
    • Autenticación con nombre de usuario y contraseña
    • Autenticación de entidad de servicio
    • autenticación DefaultAzureCredential

Funcionamiento

Autenticación de credenciales de OAuth

En esta sección se describe el flujo de trabajo general de la autenticación OAuth de Azure de Spring Cloud.

Spring Cloud Azure compilará primero uno de los siguientes tipos de credenciales en función de la configuración de autenticación de la aplicación:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Si no se encuentra ninguno de estos tipos de credenciales, la cadena de credenciales a través DefaultAzureTokenCredential se usará para obtener credenciales de las propiedades de la aplicación, las variables de entorno, la identidad administrada o los IDE. Para obtener información detallada, consulte Autenticación de Azure en Spring Cloud.

Autenticación de cadena de conexión sin formato

Para el modo de autenticación de cadena de conexión, puede usar cadena de conexión autenticación directamente o usar Azure Resource Manager para recuperar el cadena de conexión. Para obtener más información sobre el uso, consulte la sección Uso básico de cadena de conexión autenticación.

Nota:

Desde la versión 4.3.0, la autenticación de cadena de conexión está en desuso en favor de las autenticaciones de OAuth.

Configuración

Propiedades configurables al usar la compatibilidad de Kafka con la autenticación de OAuth

Spring Cloud Azure para Kafka admite los dos niveles siguientes de opciones de configuración:

  1. Propiedades de Spring Cloud Azure para Event Hubs Kafka.
  2. Las opciones de configuración de autenticación global de credential y profile con prefijos de spring.cloud.azure.
  3. Configuraciones de nivel específicas de Kafka. Las configuraciones de nivel de Kafka también están disponibles para los enlazadores Spring Boot y Spring Cloud Stream para commonámbitos , consumer, producero admin , que tienen prefijos diferentes.

Las propiedades globales se exponen a través de com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Las propiedades específicas de Kafka se exponen a través org.springframework.boot.autoconfigure.kafka.KafkaProperties de (Spring Boot) y org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (enlazador de Spring Cloud Stream).

En la lista siguiente se muestran todas las opciones de configuración admitidas.

  • Propiedades de Spring Cloud Azure para Event Hubs Kafka.

    • Propiedad: spring.cloud.azure.eventhubs.kafka.enabled
    • Descripción: si se va a habilitar la conexión gratuita de credenciales a Azure Event Hubs para Kafka, el valor predeterminado es true.

  • Las opciones de configuración de autenticación global de Azure de Spring Cloud

    • Prefijo: spring.cloud.azure
    • Opciones admitidas: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Para obtener la lista completa de opciones de configuración global, consulte Propiedades de configuración global.

  • Configuración común de Kafka de Spring Boot

    • Prefijo: spring.kafka.properties.azure
    • Ejemplo: spring.kafka.properties.azure.credential.*

  • Opciones de configuración de consumidor de Spring Kafka

    • Prefijo: spring.kafka.consumer.properties.azure
    • Ejemplo: spring.kafka.consumer.properties.azure.credential.*

  • Opciones de configuración del productor de Spring Kafka

    • Prefijo: spring.kafka.producer.properties.azure
    • Ejemplo: spring.kafka.producer.properties.azure.credential.*

  • Opciones de configuración de administrador de Spring Kafka

    • Prefijo: spring.kafka.admin.properties.azure
    • Ejemplo: spring.kafka.admin.properties.azure.credential.*

  • Configuración común de Spring Cloud Stream Kafka Binder

    • Prefijo: spring.cloud.stream.kafka.binder.configuration.azure
    • Ejemplo: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Configuración del consumidor de Kafka Binder de Spring Cloud Stream

    • Prefijo: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Ejemplo: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Configuración del productor de Kafka Binder de Spring Cloud Stream

    • Prefijo: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Ejemplo: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Configuración del administrador de Spring Cloud Stream Kafka Binder

    • Prefijo: no compatible, debe usar la configuración común o de administrador de Spring Boot Kafka.

En la tabla siguiente se muestran las opciones de configuración comunes de Spring Boot Kafka:

Nombre Descripción
spring.kafka.properties.azure.credential.client-certificate-password Contraseña del archivo de certificado.
spring.kafka.properties.azure.credential.client-certificate-path Ruta de acceso de un archivo de certificado PEM que se usará al realizar la autenticación de la entidad de servicio con Azure.
spring.kafka.properties.azure.credential.client-id Identificador de cliente que se usará al realizar la autenticación de entidad de servicio con Azure. Se trata de una propiedad heredada.
spring.kafka.properties.azure.credential.client-secret Secreto de cliente que se usará al realizar la autenticación de entidad de servicio con Azure. Se trata de una propiedad heredada.
spring.kafka.properties.azure.credential.managed-identity-enabled Indica si se va a habilitar la identidad administrada para autenticarse con Azure. Si es true y client-id se establece, usará el identificador de cliente como identificador de cliente de identidad administrada asignada por el usuario. El valor predeterminado es false.
spring.kafka.properties.azure.credential.password Contraseña que se usará al realizar la autenticación de nombre de usuario y contraseña con Azure.
spring.kafka.properties.azure.credential.username Nombre de usuario que se usará al realizar la autenticación de nombre de usuario y contraseña con Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Punto de conexión de Microsoft Entra al que conectarse.
spring.kafka.properties.azure.profile.tenant-id Identificador de inquilino para los recursos de Azure. Los valores permitidos para tenant-id son: common, organizations, consumerso el identificador de inquilino.

Nota:

Las opciones de configuración de diferentes niveles aplican las siguientes reglas. Las opciones de configuración más específicas tienen mayor prioridad que las comunes. Por ejemplo:

  • Las opciones de configuración comunes de Spring Kafka reemplazan las opciones globales.
  • Las opciones de configuración de consumidor de Spring Kafka reemplazan a las opciones comunes.
  • Las opciones de configuración del productor de Spring Kafka reemplazan a las opciones comunes.
  • Las opciones de configuración de administrador de Spring Kafka reemplazan a las opciones comunes.
  • Las opciones de Spring Cloud Stream Kafka Binder son iguales a las anteriores.

Propiedades configurables al usar la compatibilidad de Kafka con autenticación de cadena de conexión sin formato

En la tabla siguiente se muestran las opciones de configuración comunes de Spring Boot Event Hubs para Kafka:

Propiedad Descripción
spring.cloud.azure.eventhubs.kafka.enabled Si se habilita la compatibilidad con Kafka de Azure Event Hubs. El valor predeterminado es true.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs cadena de conexión. Proporcione este valor cuando desee proporcionar el cadena de conexión directamente.
spring.cloud.azure.eventhubs.namespace Espacio de nombres de Azure Event Hubs. Proporcione este valor cuando quiera recuperar la información de conexión a través de Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group El grupo de recursos del espacio de nombres de Azure Event Hubs. Proporcione este valor cuando quiera recuperar la información de conexión a través de Azure Resource Manager.
spring.cloud.azure.profile.subscription-id Identificador de la suscripción. Proporcione este valor cuando quiera recuperar la información de conexión a través de Azure Resource Manager.

Configuración de dependencias

Agregue la siguiente dependencia al proyecto. Esto incluirá automáticamente la dependencia en el spring-boot-starter proyecto de forma transitiva.

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

Nota:

Recuerde agregar la lista spring-cloud-azure-dependencies de materiales junto con la dependencia anterior. Para más información, consulte la sección Introducción de la guía para desarrolladores de Azure de Spring Cloud.

Uso básico

En las secciones siguientes se muestran los escenarios clásicos de uso de aplicaciones de Spring Boot.

Usar autenticación OAuth

Al usar la autenticación de OAuth proporcionada por Spring Cloud Azure para Kafka, puede configurar las credenciales específicas mediante las configuraciones anteriores. Como alternativa, puede optar por configurar nada sobre las credenciales, en cuyo caso Spring Cloud Azure cargará las credenciales desde el entorno. En esta sección se describen los usos que cargan las credenciales desde el entorno de la CLI de Azure o el entorno de hospedaje de Azure Spring Apps.

Nota:

Si decide usar una entidad de seguridad para autenticar y autorizar con el identificador de Entra de Microsoft para acceder a un recurso de Azure, consulte la sección Autorización del acceso con el identificador de Microsoft Entra para asegurarse de que a la entidad de seguridad se le ha concedido el permiso suficiente para acceder al recurso de Azure.

En la sección siguiente se describen los escenarios que usan diferentes bibliotecas del ecosistema de Spring con autenticación de OAuth.

Compatibilidad con aplicaciones de Spring Kafka

En esta sección se describe el escenario de uso de la aplicación Spring Boot mediante spring Kafka o la biblioteca de Kafka de integración de Spring.

Configuración de dependencias
<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>

Actualización de la configuración

Para usar la autenticación de OAuth, solo tiene que especificar el punto de conexión de Event Hubs, como se muestra en el ejemplo siguiente:

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

Compatibilidad con aplicaciones kafka del enlazador de Spring Cloud Stream

En esta sección se describe el escenario de uso de las aplicaciones de Spring Boot mediante la biblioteca kafka del enlazador de Spring Cloud Stream.

Configuración de dependencias
<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>
Configuración

Para usar la autenticación de OAuth, solo tiene que especificar el punto de conexión de Event Hubs como se muestra en el ejemplo siguiente:

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

Nota:

Si usa la versión 4.3.0, no olvide establecer la spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration propiedad para habilitar todo el flujo de trabajo de autenticación de OAuth, donde kafka-binder-name está kafka de forma predeterminada en una sola aplicación de enlazador de Kafka. La configuración AzureKafkaSpringCloudStreamConfiguration especifica los parámetros de seguridad de OAuth para KafkaBinderConfigurationProperties, que se usa en KafkaOAuth2AuthenticateCallbackHandler para habilitar Azure Identity.

Para la versión posterior 4.4.0a , esta propiedad se agregará automáticamente para cada entorno de enlazador de Kafka, por lo que no es necesario agregarla manualmente.

Ejemplos

Consulte el repositorio azure-spring-boot-samples en GitHub.

Uso de la autenticación de cadena de conexión

Puede usar cadena de conexión autenticación directamente o usar Azure Resource Manager para recuperar el cadena de conexión.

Nota:

Desde la versión 4.3.0, la autenticación de cadena de conexión está en desuso en favor de las autenticaciones de OAuth.

Desde la versión 4.5.0, al usar cadena de conexión autenticación con spring Cloud Stream Framework, se requiere la siguiente propiedad para asegurarse de que el cadena de conexión pueda surtir efecto, donde el valor de <kafka-binder-name> debe ser kafka cuando no haya ninguna configuración personalizada para el nombre del enlazador de Kafka.

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

Configuración de dependencias

Agregue las siguientes dependencias si desea migrar la aplicación apache Kafka para usar Azure Event Hubs para Kafka.

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

Si desea recuperar el cadena de conexión mediante Azure Resource Manager, agregue la dependencia siguiente:

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

Configuración

Uso de Event Hubs cadena de conexión directamente

La manera más sencilla de conectarse a Event Hubs para Kafka es con el cadena de conexión. Solo tiene que agregar la siguiente propiedad.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Uso de Azure Resource Manager para recuperar cadena de conexión

Si no desea configurar el cadena de conexión en la aplicación, puede usar Azure Resource Manager para recuperar el cadena de conexión. Para autenticarse con Azure Resource Manager, también puede usar credenciales almacenadas en la CLI de Azure u otra herramienta de desarrollo local, como Visual Studio Code o Intellij IDEA. Como alternativa, puede usar la identidad administrada si la aplicación se implementa en la nube de Azure. Asegúrese de que la entidad de seguridad tiene permiso suficiente para leer los metadatos de recursos.

Nota:

Si decide usar una entidad de seguridad para autenticar y autorizar con el identificador de Entra de Microsoft para acceder a un recurso de Azure, consulte la sección Autorización del acceso con el identificador de Microsoft Entra para asegurarse de que a la entidad de seguridad se le ha concedido el permiso suficiente para acceder al recurso de Azure.

Para usar Azure Resource Manager para recuperar el cadena de conexión, solo tiene que agregar la siguiente propiedad.

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

Ejemplos

Consulte el repositorio azure-spring-boot-samples en GitHub.