Compatibilidad con Azure Kafka de Spring Cloud
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:
- Propiedades de Spring Cloud Azure para Event Hubs Kafka.
- Las opciones de configuración de autenticación global de
credential
yprofile
con prefijos despring.cloud.azure
. - 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
,producer
oadmin
, 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
.
- Propiedad:
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.
- Prefijo:
Configuración común de Kafka de Spring Boot
- Prefijo:
spring.kafka.properties.azure
- Ejemplo:
spring.kafka.properties.azure
.credential.*
- Prefijo:
Opciones de configuración de consumidor de Spring Kafka
- Prefijo:
spring.kafka.consumer.properties.azure
- Ejemplo:
spring.kafka.consumer.properties.azure
.credential.*
- Prefijo:
Opciones de configuración del productor de Spring Kafka
- Prefijo:
spring.kafka.producer.properties.azure
- Ejemplo:
spring.kafka.producer.properties.azure
.credential.*
- Prefijo:
Opciones de configuración de administrador de Spring Kafka
- Prefijo:
spring.kafka.admin.properties.azure
- Ejemplo:
spring.kafka.admin.properties.azure
.credential.*
- Prefijo:
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.*
- Prefijo:
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.*
- Prefijo:
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.*
- Prefijo:
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 , consumers o 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.0
a , 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.