Compartir vía

Compatibilidad con Azure Kafka de Spring Cloud

  • Artículo

Este artículo se aplica a:✅ versión 4.19.0 ✅ versión 5.19.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 admitidos

Se admiten los siguientes tipos de autenticación:

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

Cómo funciona

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 de 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 de Spring Cloud.

Autenticación de cadena de conexión sin formato

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

Nota

Desde la versión 4.3.0, la autenticación de cadenas 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, consumer, producero ámbitos de 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 de org.springframework.boot.autoconfigure.kafka.KafkaProperties (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 true y se establece el client-id, 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 Cadena de conexión de Azure Event Hubs. Proporcione este valor cuando desee proporcionar la cadena de conexión directamente.
spring.cloud.azure.eventhubsespacio de nombres .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 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 de spring-boot-starter en el proyecto de forma transitiva.

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

Nota

Recuerde agregar el spring-cloud-azure-dependencies boM junto con la dependencia anterior. Para obtener 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.

Uso de la autenticación de 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 Autorizar el acceso con el identificador de Entra de Microsoft 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 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 propiedad spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration para habilitar todo el flujo de trabajo de autenticación de OAuth, donde kafka-binder-name es kafka de forma predeterminada en una sola aplicación de enlazador de Kafka. El AzureKafkaSpringCloudStreamConfiguration de configuración especifica los parámetros de seguridad de OAuth para KafkaBinderConfigurationProperties, que se usa en KafkaOAuth2AuthenticateCallbackHandler para habilitar Azure Identity.

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

Uso de la identidad administrada para la autenticación de OAuth

  1. Para usar la identidad administrada, debe habilitar la identidad administrada para el servicio y asignar los roles de Azure Event Hubs Data Receiver y Azure Event Hubs Data Sender. Para más información, consulte Asignación de roles de Azure para derechos de acceso.

  2. Configure las siguientes propiedades en el archivo application.yml:

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

    Importante

    Si usa la identidad administrada asignada por el usuario, también debe agregar la propiedad spring.cloud.azure.credential.client-id con el identificador de cliente de identidad administrada asignada por el usuario.

Muestras

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

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

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

Nota

Desde la versión 5.0.0, cuando se usa la autenticación de cadena de conexión con spring Cloud Stream Framework, todavía se requiere la siguiente propiedad para asegurarse de que la cadena de conexión puede 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.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Si la versión de spring-cloud-dependencies que usó es 2022.0.0, encontrará la excepción del java.lang.IllegalStateException: kafka_context has not been refreshed yet. Para solucionar este problema, actualice a una versión superior.

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 la 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 la cadena de conexión de Event Hubs directamente

La manera más sencilla de conectarse a Event Hubs para Kafka es con la 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 la cadena de conexión

Si no desea configurar la cadena de conexión en la aplicación, puede usar Azure Resource Manager para recuperar la 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 Autorizar el acceso con el identificador de Entra de Microsoft 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 la cadena de conexión, basta con 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}

Muestras

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