Поддержка Spring Cloud Azure Kafka

Статья
12/14/2024

Эта статья относится к:✅ версии 4.19.0 ✅ версии 5.19.0

С версии 4.3.0 Azure Spring Cloud для Kafka поддерживает различные типы учетных данных для проверки подлинности и подключения к Центрам событий Azure.

Поддерживаемая версия Kafka

Текущая версия начальной версии должна быть совместима с Клиентами Apache Kafka 2.0.0 с помощью Java 8 или более поздней версии.

Поддерживаемые типы проверки подлинности

Поддерживаются следующие типы проверки подлинности:

Обычная проверка подлинности строки подключения
- Проверка подлинности строки прямого подключения
- Проверка подлинности строки подключения на основе ARM
Проверка подлинности учетных данных OAuth
- Проверка подлинности управляемого удостоверения
- Проверка подлинности имени пользователя и пароля
- Проверка подлинности субъекта-службы
- проверка подлинности DefaultAzureCredential

Принцип работы

Проверка подлинности учетных данных OAuth

В этом разделе описывается общий рабочий процесс проверки подлинности Azure OAuth Spring Cloud.

Spring Cloud Azure сначала создаст один из следующих типов учетных данных в зависимости от конфигурации проверки подлинности приложения:

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

Если ни один из этих типов учетных данных не найден, цепочка учетных данных с помощью DefaultAzureTokenCredential будет использоваться для получения учетных данных из свойств приложения, переменных среды, управляемых удостоверений или удостоверений. Подробные сведения см. впроверки подлинности Spring Cloud Azure.

Обычная проверка подлинности строки подключения

Для режима проверки подлинности строки подключения можно использовать проверку подлинности строки подключения напрямую или использовать Azure Resource Manager для получения строки подключения. Дополнительные сведения об использовании см. в разделе Базовое использование для проверки подлинности строки подключения.

Заметка

С версии 4.3.0 проверка подлинности строки подключения не рекомендуется использовать для проверки подлинности OAuth.

Конфигурация

Настраиваемые свойства при использовании поддержки Kafka с проверкой подлинности OAuth

Azure Spring Cloud для Kafka поддерживает следующие два уровня параметров конфигурации:

Свойства Kafka для Spring Cloud для Центров событий.
Параметры глобальной конфигурации проверки подлинности credential и profile с префиксами spring.cloud.azure.
Конфигурации уровня kafka. Конфигурации уровня Kafka также доступны для привязок Spring Boot и Spring Cloud Stream для common, consumer, producerили admin областей, которые имеют разные префиксы.

Глобальные свойства предоставляются через 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).

В следующем списке показаны все поддерживаемые параметры конфигурации.

Свойства Kafka для Spring Cloud для Центров событий.
- Свойство: spring.cloud.azure.eventhubs.kafka.enabled
- Описание: следует ли включить бесплатное подключение учетных данных к Центрам событий Azure для Kafka, значение по умолчанию — true.
Параметры конфигурации глобальной проверки подлинности Azure Spring Cloud
- Префикс: 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	Путь к файлу сертификата PEM для использования при выполнении проверки подлинности субъекта-службы с помощью Azure.
spring.kafka.properties.azure.credential.client-id	Идентификатор клиента, используемый при выполнении проверки подлинности субъекта-службы с помощью Azure. Это устаревшее свойство.
spring.kafka.properties.azure.credential.client-secret	Секрет клиента, используемый при выполнении проверки подлинности субъекта-службы с помощью Azure. Это устаревшее свойство.
spring.kafka.properties.azure.credential.managed-identity-enabled	Следует ли включить управляемое удостоверение для проверки подлинности в Azure. Если true и `client-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. Значения, допустимые для `tenant-id`: `common`, `organizations`, `consumers`или идентификатор клиента.

Заметка

Параметры конфигурации в разных уровнях применяют следующие правила. Более конкретные параметры конфигурации имеют более высокий приоритет, чем распространенные. Например:

Общие параметры конфигурации Spring Kafka заменяют глобальные параметры.
Параметры конфигурации потребителей Spring Kafka заменяют общие параметры.
Параметры конфигурации производителя Spring Kafka заменяют общие параметры.
Параметры конфигурации администратора Spring Kafka заменяют общие параметры.
Параметры Привязки Kafka Stream Spring Cloud точно так же, как описано выше.

Настраиваемые свойства при использовании поддержки Kafka с обычной проверкой подлинности строки подключения

В следующей таблице показаны общие параметры конфигурации Центров событий Spring Boot для Kafka:

Свойство	Описание
spring.cloud.azure.eventhubs.kafka.enabled	Следует ли включить поддержку Kafka Центров событий Azure. Значение по умолчанию — true.
spring.cloud.azure.eventhubs.connection-string	Строка подключения Центров событий Azure. Укажите это значение, если вы хотите предоставить строку подключения напрямую.
spring.cloud.azure.eventhubsпространство имен	Пространство имен Центров событий Azure. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group	Группа ресурсов пространства имен Центров событий Azure. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.
spring.cloud.azure.profile.subscription-id	Идентификатор подписки. Укажите это значение, если требуется получить сведения о подключении с помощью Azure Resource Manager.

Настройка зависимостей

Добавьте в проект следующую зависимость. Это автоматически включает spring-boot-starter зависимость в проекте транзитивно.

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

Заметка

Не забудьте добавить spring-cloud-azure-dependencies BOM вместе с приведенной выше зависимостью. Дополнительные сведения см. в разделе Начало работы руководства разработчика Spring Cloud azure.

Базовое использование

В следующих разделах показаны классические сценарии использования приложений Spring Boot.

Использование проверки подлинности OAuth

При использовании проверки подлинности OAuth, предоставленной Azure Spring Cloud для Kafka, можно настроить определенные учетные данные с помощью приведенных выше конфигураций. Кроме того, вы можете настроить ничего о учетных данных, в этом случае Azure Spring Cloud загрузит учетные данные из среды. В этом разделе описаны способы загрузки учетных данных из среды Azure CLI или среды размещения Azure Spring Apps.

Заметка

Если вы решили использовать субъект безопасности для проверки подлинности и авторизации с помощью идентификатора Microsoft Entra для доступа к ресурсу Azure, ознакомьтесь с разделом Авторизовать доступ с помощью идентификатора Microsoft Entra id, чтобы убедиться, что субъект безопасности получил достаточное разрешение на доступ к ресурсу Azure.

В следующем разделе описаны сценарии использования различных библиотек экосистем Spring с проверкой подлинности OAuth.

Поддержка приложений Spring Kafka

В этом разделе описывается сценарий использования приложения Spring Boot с помощью библиотеки Spring Kafka или Spring Integration Kafka.

Настройка зависимостей

<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

Поддержка приложения Kafka для привязки Spring Cloud Stream

В этом разделе описывается сценарий использования приложений Spring Boot с помощью библиотеки Kafka привязки Spring Cloud Stream.

Настройка зависимостей

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

Конфигурация

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-namekafka по умолчанию в одном приложении привязки Kafka. В AzureKafkaSpringCloudStreamConfiguration конфигурации указаны параметры безопасности OAuth для KafkaBinderConfigurationProperties, которые используются в KafkaOAuth2AuthenticateCallbackHandler для включения удостоверения Azure.

Для версии после 4.4.0это свойство будет добавлено автоматически для каждой среды привязки Kafka, поэтому ее добавлять вручную не требуется.

Использование управляемого удостоверения для проверки подлинности OAuth

Чтобы использовать управляемое удостоверение, необходимо включить управляемое удостоверение для службы и назначить Azure Event Hubs Data Receiver и Azure Event Hubs Data Sender роли. Дополнительные сведения см. в статье Назначение ролей Azure для прав доступа.
Настройте следующие свойства в файле application.yml:
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
Важный

Если вы используете управляемое удостоверение, назначаемое пользователем, необходимо также добавить свойство spring.cloud.azure.credential.client-id с идентификатором клиента управляемого удостоверения, назначаемого пользователем.

Образцы

См. репозиторий azure-spring-boot-samples на сайте GitHub.

Использование проверки подлинности строки подключения

Для получения строки подключения можно использовать проверку подлинности строки подключения напрямую или использовать Azure Resource Manager.

Spring Cloud Azure 5.x
Spring Cloud Azure 4.x

Заметка

Поскольку версия 5.0.0.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.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Если используемая версия spring-cloud-dependencies2022.0.0, возникнет исключение java.lang.IllegalStateException: kafka_context has not been refreshed yet. Чтобы решить эту проблему, выполните обновление до более поздней версии.

Заметка

Так как версия 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 для использования Центров событий Azure для Kafka.

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

Если вы хотите получить строку подключения с помощью Azure Resource Manager, добавьте следующую зависимость:

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

Если вы не хотите настроить строку подключения в приложении, можно использовать Azure Resource Manager для получения строки подключения. Для проверки подлинности с помощью Azure Resource Manager можно также использовать учетные данные, хранящиеся в Azure CLI или другом локальном средстве разработки, например Visual Studio Code или Intellij IDEA. Кроме того, можно использовать управляемое удостоверение, если приложение развернуто в облаке Azure. Просто убедитесь, что субъект имеет достаточно разрешений для чтения метаданных ресурса.

Заметка

Если вы решили использовать субъект безопасности для проверки подлинности и авторизации с помощью идентификатора Microsoft Entra для доступа к ресурсу Azure, ознакомьтесь с разделом Авторизовать доступ с помощью идентификатора Microsoft Entra ID, чтобы убедиться, что субъект безопасности получил достаточное разрешение на доступ к ресурсу Azure.

Чтобы использовать Azure Resource Manager для получения строки подключения, просто добавьте следующее свойство.

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

Образцы

См. репозиторий azure-spring-boot-samples на сайте GitHub.

Поделиться через

Поддержка Spring Cloud Azure Kafka

Поддерживаемая версия Kafka

Поддерживаемые типы проверки подлинности

Принцип работы

Проверка подлинности учетных данных OAuth

Обычная проверка подлинности строки подключения

Конфигурация

Настраиваемые свойства при использовании поддержки Kafka с проверкой подлинности OAuth

Настраиваемые свойства при использовании поддержки Kafka с обычной проверкой подлинности строки подключения

Настройка зависимостей

Базовое использование

Использование проверки подлинности OAuth

Поддержка приложений Spring Kafka

Настройка зависимостей

Обновление конфигурации

Поддержка приложения Kafka для привязки Spring Cloud Stream

Настройка зависимостей

Конфигурация

Использование управляемого удостоверения для проверки подлинности OAuth

Образцы

Использование проверки подлинности строки подключения

Настройка зависимостей

Конфигурация

Использование строки подключения Центров событий напрямую

Получение строки подключения с помощью Azure Resource Manager

Образцы

Обратная связь

Дополнительные ресурсы