通过

Spring Cloud Azure Kafka 支持

  • 项目

本文适用于： ✔️版本 4.14.0 ✔️ 版本 5.8.0

从版本 4.3.0 开始，Spring Cloud Azure for Kafka 支持各种类型的凭据进行身份验证并连接到Azure 事件中心。

支持的 Kafka 版本

当前版本的初学者应与使用 Java 8 或更高版本的 Apache Kafka 客户端 2.0.0 兼容。

支持的身份验证类型

支持以下身份验证类型：

  • 纯连接字符串身份验证
    • 直接连接字符串身份验证
    • 基于 ARM 的连接字符串身份验证
  • OAuth 凭据身份验证
    • 托管标识身份验证
    • 用户名/密码身份验证
    • 服务主体身份验证
    • DefaultAzureCredential身份验证

工作原理

OAuth 凭据身份验证

本部分介绍 Spring Cloud Azure OAuth 身份验证的总体工作流。

Spring Cloud Azure 将首先根据应用程序身份验证配置生成以下类型的凭据之一：

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

如果未找到这些类型的凭据，则凭据 DefaultAzureTokenCredential 链将用于从应用程序属性、环境变量、托管标识或 IDE 获取凭据。 有关详细信息，请参阅 Spring Cloud Azure 身份验证。

纯连接字符串身份验证

对于连接字符串身份验证模式，可以直接使用连接字符串身份验证或使用 Azure 资源管理器来检索连接字符串。 有关用法的详细信息，请参阅连接字符串身份验证的基本用法部分。

注意

由于版本为 4.3.0，连接字符串身份验证已弃用，以支持 OAuth 身份验证。

配置

将 Kafka 支持与 OAuth 身份验证配合使用时可配置的属性

适用于 Kafka 的 Spring Cloud Azure 支持以下两个级别的配置选项：

  1. Spring Cloud Azure for Event Hubs Kafka 属性。
  2. 全局身份验证配置选项 credential 和 profile 前缀为 spring.cloud.azure.
  3. 特定于 Kafka 的级别配置。 Kafka 级别配置也适用于 Spring Boot 和 Spring Cloud Stream 绑定器，这些绑定器commonconsumerproduceradmin具有不同的前缀。

全局属性通过 com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. 特定于 Kafka 的属性通过 org.springframework.boot.autoconfigure.kafka.KafkaProperties （Spring Boot） 和 org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties （Spring Cloud Stream 绑定器）公开。

以下列表显示所有受支持的配置选项。

  • Spring Cloud Azure for Event Hubs Kafka 属性。

    • 财产： spring.cloud.azure.eventhubs.kafka.enabled
    • 说明：是否为 Kafka 启用与 Azure 事件中心 的无凭据连接，默认值为 true。

  • Spring Cloud Azure 全局身份验证配置选项

    • 前缀：spring.cloud.azure
    • 支持的选项： spring.cloud.azure.credential.*spring.cloud.azure.profile.*

    有关全局配置选项的完整列表，请参阅 全局配置属性。

  • Spring Boot Kafka 常见配置

    • 前缀：spring.kafka.properties.azure
    • 示例： spring.kafka.properties.azure.credential.*

  • Spring Kafka 使用者配置选项

    • 前缀：spring.kafka.consumer.properties.azure
    • 示例： spring.kafka.consumer.properties.azure.credential.*

  • Spring Kafka 生成者配置选项

    • 前缀：spring.kafka.producer.properties.azure
    • 示例： spring.kafka.producer.properties.azure.credential.*

  • Spring Kafka 管理员配置选项

    • 前缀：spring.kafka.admin.properties.azure
    • 示例： spring.kafka.admin.properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder 常见配置

    • 前缀：spring.cloud.stream.kafka.binder.configuration.azure
    • 示例： spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Spring Cloud Stream Kafka Binder 使用者配置

    • 前缀：spring.cloud.stream.kafka.binder.consumer-properties.azure
    • 示例： spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder 生成者配置

    • 前缀：spring.cloud.stream.kafka.binder.producer-properties.azure
    • 示例： spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder 管理员配置

    • 前缀：不支持，应使用 Spring Boot Kafka 常见或管理员配置。

下表显示了 Spring Boot Kafka 通用配置选项：

名称 描述
spring.kafka.properties.azure.credential.client-certificate-password 证书文件的密码。
spring.kafka.properties.azure.credential.client-certificate-path 使用 Azure 执行服务主体身份验证时要使用的 PEM 证书文件的路径。
spring.kafka.properties.azure.credential.client-id 使用 Azure 执行服务主体身份验证时要使用的客户端 ID。 这是一个旧属性。
spring.kafka.properties.azure.credential.client-secret 使用 Azure 执行服务主体身份验证时要使用的客户端密码。 这是一个旧属性。
spring.kafka.properties.azure.credential.managed-identity-enabled 是否允许托管标识通过 Azure 进行身份验证。 如果 为 true 且 client-id 已设置，将使用客户端 ID 作为用户分配的托管标识客户端 ID。 默认值是 false。
spring.kafka.properties.azure.credential.password 在 Azure 中执行用户名/密码身份验证时要使用的密码。
spring.kafka.properties.azure.credential.username 在 Azure 中执行用户名/密码身份验证时要使用的用户名。
spring.kafka.properties.azure.profile.environment.active-directory-endpoint 要连接到的 Microsoft Entra 终结点。
spring.kafka.properties.azure.profile.tenant-id Azure 资源的租户 ID。 允许 tenant-id 的值包括： common、 organizations、 consumers或租户 ID。

注意

不同级别的配置选项应用以下规则。 特定配置选项的优先级高于常见配置选项。 例如：

  • Spring Kafka 通用配置选项取代了全局选项。
  • Spring Kafka 使用者配置选项取代了常用选项。
  • Spring Kafka 生成者配置选项取代了常用选项。
  • Spring Kafka 管理员配置选项取代了常用选项。
  • Spring Cloud Stream Kafka Binder 选项与上述选项类似。

通过纯连接字符串身份验证使用 Kafka 支持时可配置的属性

下表显示了适用于 Kafka 的 Spring Boot 事件中心常见配置选项：

properties 说明
spring.cloud.azure.eventhubs.kafka.enabled 是否启用 Azure 事件中心 Kafka 支持。 默认值为 true。
spring.cloud.azure.eventhubs.connection-string Azure 事件中心 连接字符串。 如果要直接提供连接字符串，请提供此值。
spring.cloud.azure.eventhubs.namespace Azure 事件中心命名空间。 若要通过 Azure 资源管理器检索连接信息，请提供此值。
spring.cloud.azure.eventhubs.resource.resource-group Azure 事件中心命名空间的资源组。 若要通过 Azure 资源管理器检索连接信息，请提供此值。
spring.cloud.azure.profile.subscription-id 订阅的 ID。 若要通过 Azure 资源管理器检索连接信息，请提供此值。

依赖项设置

将以下依赖项添加到项目。 这将自动在项目中以可传递方式包含 spring-boot-starter 依赖项。

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

注意

请记住添加 BOM spring-cloud-azure-dependencies 以及上述依赖项。 有关详细信息，请参阅 Spring Cloud Azure 开发人员指南的“入门”部分。

基本用法

以下部分显示了经典 Spring Boot 应用程序使用方案。

使用 OAuth 身份验证

使用 Spring Cloud Azure for Kafka 提供的 OAuth 身份验证时，可以使用上述配置配置配置特定凭据。 或者，可以选择配置任何凭据，在这种情况下，Spring Cloud Azure 将从环境中加载凭据。 本部分介绍从 Azure CLI 环境或 Azure Spring Apps 托管环境加载凭据的用法。

注意

如果选择使用安全主体通过 Microsoft Entra ID 进行身份验证和授权来访问 Azure 资源，请参阅“ 使用 Microsoft Entra ID 授权访问”部分，以确保安全主体已获得访问 Azure 资源的足够权限。

以下部分介绍将不同的 Spring 生态系统库与 OAuth 身份验证配合使用的方案。

Spring Kafka 应用程序支持

本部分介绍使用 Spring Kafka 或 Spring Integration Kafka 库的 Spring Boot 应用程序的使用方案。

依赖项设置
<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>

配置更新

若要使用 OAuth 身份验证，只需指定事件中心终结点，如以下示例所示：

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

Spring Cloud Stream 绑定器 Kafka 应用程序支持

本部分介绍使用 Spring Cloud Stream 绑定器 Kafka 库的 Spring Boot 应用程序的使用方案。

依赖项设置
<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>
配置

若要使用 OAuth 身份验证，只需指定事件中心终结点，如以下示例所示：

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

注意

如果使用版本 4.3.0，请不要忘记设置属性 spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration 以启用整个 OAuth 身份验证工作流，其中 kafka-binder-name 默认在 kafka 单个 Kafka 绑定器应用程序中。 AzureKafkaSpringCloudStreamConfiguration配置指定用于启用 Azure 标识的 OAuth 安全参数KafkaBinderConfigurationPropertiesKafkaOAuth2AuthenticateCallbackHandler。

对于版本之后 4.4.0，此属性将自动为每个 Kafka 绑定器环境添加，因此无需手动添加它。

示例

请参阅 GitHub 上的 azure-spring-boot-samples 存储库。

使用连接字符串身份验证

可以直接使用连接字符串身份验证，也可以使用 Azure 资源管理器检索连接字符串。

注意

由于版本为 4.3.0，连接字符串身份验证已弃用，以支持 OAuth 身份验证。

由于版本为 4.5.0，在将连接字符串身份验证与 Spring Cloud Stream 框架配合使用时，需要以下属性来确保连接字符串生效，其中<kafka-binder-name>当 Kafka 绑定器名称没有自定义配置时，值应kafka有效。

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

依赖项设置

如果要迁移 Apache Kafka 应用程序以使用 Kafka Azure 事件中心，请添加以下依赖项。

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

如果要使用 Azure 资源管理器检索连接字符串，请添加以下依赖项：

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

配置

直接使用事件中心连接字符串

连接到 Kafka 事件中心的最简单方法是使用 连接字符串。 只需添加以下属性即可。

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
使用 Azure 资源管理器检索连接字符串

如果不想在应用程序中配置连接字符串，可以使用 Azure 资源管理器检索连接字符串。 若要使用 Azure 资源管理器进行身份验证，还可以使用存储在 Azure CLI 或其他本地开发工具（如 Visual Studio Code 或 Intellij IDEA）中的凭据。 或者，如果应用程序部署到 Azure 云，则可以使用托管标识。 只需确保主体具有读取资源元数据的足够权限。

注意

如果选择使用安全主体通过 Microsoft Entra ID 进行身份验证和授权来访问 Azure 资源，请参阅“ 使用 Microsoft Entra ID 授权访问”部分，以确保安全主体已获得访问 Azure 资源的足够权限。

若要使用 Azure 资源管理器检索连接字符串，只需添加以下属性即可。

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

示例

请参阅 GitHub 上的 azure-spring-boot-samples 存储库。