Obsługa platformy Kafka w Spring Cloud Azure

  • Dotyczy: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Obsługa platformy Spring Cloud Azure Kafka ułatwia aplikacjom platformy Spring uwierzytelnianie i łączenie się z Azure Event Hubs przy użyciu poświadczeń protokołu OAuth lub parametrów połączenia. W tym artykule opisano obsługiwane typy uwierzytelniania, opcje konfiguracji, zależności i scenariusze użycia.

Obsługiwana wersja platformy Kafka

Obecna wersja startera jest zgodna z klientami Apache Kafka 2.0.0 i wymaga języka Java 8 lub nowszego.

Obsługiwane typy uwierzytelniania

Starter obsługuje następujące typy uwierzytelniania:

  • Uwierzytelnianie za pomocą zwykłych parametrów połączenia
    • Bezpośrednie uwierzytelnianie parametrów połączenia
    • Uwierzytelnianie oparte na ARM za pomocą parametrów połączenia
  • Uwierzytelnianie poświadczeń protokołu OAuth
    • Uwierzytelnianie za pomocą tożsamości zarządzanej
    • Uwierzytelnianie nazwy użytkownika/hasła
    • Uwierzytelnianie jednostki usługi
    • Uwierzytelnianie DefaultAzureCredential

Jak to działa

Uwierzytelnianie poświadczeń protokołu OAuth

W tej sekcji opisano ogólny przepływ pracy uwierzytelniania OAuth platformy Azure w usłudze Spring Cloud.

Usługa Spring Cloud Azure najpierw tworzy jeden z następujących typów poświadczeń, w zależności od konfiguracji uwierzytelniania aplikacji:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Jeśli aplikacja nie używa jednego z tych typów poświadczeń, korzysta z łańcucha poświadczeń za pośrednictwem DefaultAzureTokenCredential, aby uzyskać poświadczenia z właściwości aplikacji, zmiennych środowiskowych, tożsamości zarządzanej lub środowisk programistycznych IDE. Aby uzyskać szczegółowe informacje, zobacz Spring Cloud Azure authentication.

Uwierzytelnianie zwykłych parametrów połączenia

W trybie uwierzytelniania parametrów połączenia można użyć uwierzytelniania parametrów połączenia bezpośrednio lub użyć usługi Azure Resource Manager do pobrania parametrów połączenia. Aby uzyskać więcej informacji na temat użycia, zobacz sekcję Podstawowe użycie dla uwierzytelniania parametrów połączenia.

Uwaga

Od wersji 4.3.0 uwierzytelnianie za pomocą parametrów połączenia zostało wycofane na rzecz uwierzytelniania OAuth.

Konfiguracja

Konfigurowalne właściwości podczas korzystania z obsługi platformy Kafka z uwierzytelnianiem OAuth

Platforma Azure Spring Cloud dla platformy Kafka obsługuje następujące dwa poziomy opcji konfiguracji:

  1. Właściwości Kafka usługi Event Hubs dla Spring Cloud Azure.
  2. Globalne opcje konfiguracji uwierzytelniania credential i profile z prefiksami spring.cloud.azure.
  3. Konfiguracje na poziomie specyficznym dla platformy Kafka. Konfiguracje na poziomie Kafka są również dostępne dla binderów Spring Boot i Spring Cloud Stream dla zakresów common, consumer, producer lub admin, które mają różne prefiksy.

Właściwości globalne są widoczne za pośrednictwem com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Właściwości specyficzne dla Kafki są udostępniane za pośrednictwem org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) i org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (łącznik Spring Cloud Stream).

Poniższa lista zawiera wszystkie obsługiwane opcje konfiguracji.

  • Właściwości Kafka dla usługi Event Hubs w Spring Cloud Azure.

    • Właściwość: spring.cloud.azure.eventhubs.kafka.enabled
    • Opis: czy włączyć połączenie niewymagające poświadczeń z usługą Azure Event Hubs dla platformy Kafka, wartość domyślna to true.

  • Opcje konfiguracji globalnego uwierzytelniania platformy Azure w usłudze Spring Cloud

    • Prefiks: spring.cloud.azure
    • Obsługiwane opcje: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Aby uzyskać pełną listę opcji konfiguracji globalnej, zobacz Globalne właściwości konfiguracji.

  • Wspólna konfiguracja Kafka w Spring Boot

    • Prefiks: spring.kafka.properties.azure
    • Przykład: spring.kafka.properties.azure.credential.*

  • Opcje konfiguracji konsumentów platformy Spring Kafka

    • Prefiks: spring.kafka.consumer.properties.azure
    • Przykład: spring.kafka.consumer.properties.azure.credential.*

  • Opcje konfiguracji producenta Spring Kafka

    • Prefiks: spring.kafka.producer.properties.azure
    • Przykład: spring.kafka.producer.properties.azure.credential.*

  • Opcje konfiguracji administratora platformy Spring Kafka

    • Prefiks: spring.kafka.admin.properties.azure
    • Przykład: spring.kafka.admin.properties.azure.credential.*

  • Wspólna konfiguracja bindera Kafka dla Spring Cloud Stream

    • Prefiks: spring.cloud.stream.kafka.binder.configuration.azure
    • Przykład: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Konfiguracja klienta platformy Kafka Binder w usłudze Spring Cloud Stream

    • Prefiks: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Przykład: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Konfiguracja producenta bindera Kafka w Spring Cloud Stream

    • Prefiks: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Przykład: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Konfiguracja administratora Kafka Binder w Spring Cloud Stream

    • Prefiks: Nie jest obsługiwane, użyj wspólnej konfiguracji Kafka w Spring Boot lub konfiguracji administratora.

W poniższej tabeli przedstawiono typowe opcje konfiguracji Spring Boot Kafka:

Nazwa Opis
spring.kafka.properties.azure.credential.client-certificate-password Hasło pliku certyfikatu.
spring.kafka.properties.azure.credential.client-certificate-path Ścieżka pliku certyfikatu PEM do użycia podczas przeprowadzania uwierzytelniania jednostki usługi na platformie Azure.
spring.kafka.properties.azure.credential.client-id Identyfikator klienta do użycia podczas przeprowadzania uwierzytelniania jednostki usługi za pomocą platformy Azure. Jest to starsza właściwość.
spring.kafka.properties.azure.credential.client-secret Klucz tajny klienta używany podczas przeprowadzania uwierzytelniania jednostki usługi za pomocą platformy Azure. Jest to starsza właściwość.
spring.kafka.properties.azure.credential.managed-identity-enabled Czy włączyć tożsamość zarządzaną do uwierzytelniania za pomocą platformy Azure. Jeśli ustawiono true i client-id, identyfikator klienta jest identyfikatorem klienta tożsamości zarządzanej przypisanej przez użytkownika. Wartość domyślna to false.
spring.kafka.properties.azure.credential.password Hasło do użycia podczas przeprowadzania uwierzytelniania nazwy użytkownika/hasła na platformie Azure.
spring.kafka.properties.azure.credential.username Nazwa użytkownika do użycia podczas przeprowadzania uwierzytelniania nazwy użytkownika/hasła na platformie Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Punkt końcowy Microsoft Entra, z którym ma zostać nawiązane połączenie.
spring.kafka.properties.azure.profile.tenant-id Identyfikator dzierżawcy dla zasobów platformy Azure. Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy.

Uwaga

Opcje konfiguracji na różnych poziomach stosują następujące reguły. Bardziej szczegółowe opcje konfiguracji mają wyższy priorytet niż typowe. Na przykład:

  • Typowe opcje konfiguracji platformy Spring Kafka zastępują opcje globalne.
  • Opcje konfiguracji konsumentów platformy Spring Kafka zastępują typowe opcje.
  • Opcje konfiguracji producenta Spring Kafka zastępują typowe opcje.
  • Opcje konfiguracji administratora platformy Spring Kafka zastępują typowe opcje.
  • Opcje łącznika Spring Cloud Stream Kafka Binder mają ten sam schemat.

Konfigurowalne właściwości w przypadku korzystania z obsługi platformy Kafka z uwierzytelnianiem w postaci zwykłych parametrów połączenia

W poniższej tabeli przedstawiono typowe opcje konfiguracji usługi Spring Boot Event Hubs dla platformy Kafka:

Własność Opis
spring.cloud.azure.eventhubs.kafka.enabled Czy włączyć obsługę platformy Kafka w usłudze Azure Event Hubs. Wartość domyślna to true.
spring.cloud.azure.eventhubs.connection-string Parametry połączenia usługi Azure Event Hubs. Podaj tę wartość, jeśli chcesz podać parametry połączenia bezpośrednio.
spring.cloud.azure.eventhubs.namespace Przestrzeń nazw usługi Azure Event Hubs. Podaj tę wartość, jeśli chcesz pobrać informacje o połączeniu za pośrednictwem usługi Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group Grupa zasobów przestrzeni nazw usługi Azure Event Hubs. Podaj tę wartość, jeśli chcesz pobrać informacje o połączeniu za pośrednictwem usługi Azure Resource Manager.
spring.cloud.azure.profile.subscription-id Identyfikator subskrypcji. Podaj tę wartość, jeśli chcesz pobrać informacje o połączeniu za pośrednictwem usługi Azure Resource Manager.

Konfiguracja zależności

Dodaj następującą zależność do projektu. Ta zależność automatycznie dołącza zależność spring-boot-starter do Twojego projektu.

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

Uwaga

Pamiętaj, aby dodać BOM spring-cloud-azure-dependencies razem z poprzednią zależnością. Aby uzyskać szczegółowe informacje, zobacz sekcję Wprowadzenie przewodnika dla deweloperów platformy Azure Spring Cloud.

Podstawowe użycie

W poniższych sekcjach przedstawiono klasyczne scenariusze użycia aplikacji Spring Boot.

Korzystanie z uwierzytelniania OAuth

Jeśli używasz uwierzytelniania OAuth zapewniane przez usługę Spring Cloud Azure dla platformy Kafka, można skonfigurować określone poświadczenia przy użyciu poprzednich konfiguracji. Alternatywnie możesz zrezygnować z konfigurowania żadnych poświadczeń. W takim przypadku usługa Spring Cloud Azure ładuje poświadczenia ze środowiska. W tej sekcji opisano sposób ładowania poświadczeń ze środowiska Azure CLI lub środowiska hostingu Azure Spring Apps.

Uwaga

Jeśli zdecydujesz się użyć podmiotu zabezpieczeń do uwierzytelniania i autoryzacji za pomocą Microsoft Entra ID w celu uzyskania dostępu do zasobu Azure, zobacz sekcję Autoryzowanie dostępu za pomocą Microsoft Entra ID, aby upewnić się, że podmiot zabezpieczeń ma wystarczające uprawnienia dostępu do zasobu Azure.

W poniższej sekcji opisano scenariusze korzystające z różnych bibliotek ekosystemu Spring z uwierzytelnianiem OAuth.

Obsługa aplikacji Spring Kafka

W tej sekcji opisano scenariusz użycia aplikacji Spring Boot, która korzysta z biblioteki Spring Kafka lub biblioteki Spring Integration Kafka.

Konfiguracja zależności
<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>

Aktualizacja konfiguracji

Aby użyć uwierzytelniania OAuth, określ punkt końcowy usługi Event Hubs, jak pokazano w poniższym przykładzie:

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

Obsługa aplikacji bindera Kafka w Spring Cloud Stream

W tej sekcji opisano scenariusz używania aplikacji Spring Boot korzystających z biblioteki Kafka bindera Spring Cloud Stream.

Konfiguracja zależności
<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>
Konfiguracja

Aby użyć uwierzytelniania OAuth, określ punkt końcowy usługi Event Hubs, jak pokazano w poniższym przykładzie:

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

Uwaga

Jeśli używasz wersji 4.3.0, ustaw spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration właściwość , aby włączyć cały przepływ pracy uwierzytelniania OAuth. Element kafka-binder-name jest kafka domyślnie w aplikacji z jednym powiązaniem Kafka. AzureKafkaSpringCloudStreamConfiguration Konfiguracja określa parametry zabezpieczeń protokołu OAuth dla elementu KafkaBinderConfigurationProperties. Ta konfiguracja służy w KafkaOAuth2AuthenticateCallbackHandler do włączenia usługi Azure Identity.

W przypadku wersji po 4.4.0programie ta właściwość jest dodawana automatycznie dla każdego środowiska bindera Kafka, więc nie trzeba dodawać jej ręcznie.

Używanie tożsamości zarządzanej na potrzeby uwierzytelniania OAuth

  1. Aby użyć tożsamości zarządzanej, włącz ją dla usługi i przypisz role Azure Event Hubs Data Receiver i Azure Event Hubs Data Sender. Aby uzyskać więcej informacji, zobacz Przypisywanie ról platformy Azure na potrzeby praw dostępu.

  2. Skonfiguruj następujące właściwości w pliku application.yml:

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

    Ważny

    Jeśli używasz tożsamości zarządzanej przypisanej przez użytkownika, dodaj również właściwość spring.cloud.azure.credential.client-id z identyfikatorem klienta tożsamości zarządzanej przypisanej przez użytkownika.

Próbki

Zobacz repozytorium azure-spring-boot-samples w serwisie GitHub.

Korzystanie z uwierzytelniania parametrów połączenia

Możesz użyć uwierzytelniania parametrów połączenia bezpośrednio lub użyć usługi Azure Resource Manager, aby pobrać parametry połączenia.

Uwaga

Od wersji 5.0.0 podczas korzystania z uwierzytelniania za pomocą parametrów połączenia w strukturze Spring Cloud Stream nadal jest wymagana następująca właściwość, aby parametry połączenia działały poprawnie. Wartość <kafka-binder-name> powinna wynosić kafka, jeśli nie dostosujesz nazwy bindera Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Jeśli używana wersja spring-cloud-dependencies to 2022.0.0, napotkasz wyjątek java.lang.IllegalStateException: kafka_context has not been refreshed yet. Aby rozwiązać ten problem, uaktualnij go do nowszej wersji.

Konfiguracja zależności

Dodaj następujące zależności, jeśli chcesz przeprowadzić migrację aplikacji platformy Apache Kafka do korzystania z usługi Azure Event Hubs dla platformy Kafka.

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

Jeśli chcesz pobrać parametry połączenia przy użyciu Azure Resource Manager, dodaj następującą zależność:

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

Konfiguracja

Bezpośrednie używanie parametrów połączenia usługi Event Hubs

Najprostszym sposobem nawiązywania połączenia z usługą Event Hubs dla platformy Kafka jest użycie parametrów połączenia. Wystarczy dodać następującą właściwość.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Pobieranie parametrów połączenia za pomocą usługi Azure Resource Manager

Jeśli nie chcesz konfigurować parametrów połączenia w aplikacji, możesz użyć usługi Azure Resource Manager, aby pobrać parametry połączenia. Aby przeprowadzić uwierzytelnianie za pomocą usługi Azure Resource Manager, możesz również użyć poświadczeń przechowywanych w interfejsie wiersza polecenia platformy Azure lub innym lokalnym narzędziu programistycznym, takim jak Visual Studio Code lub Intellij IDEA. Alternatywnie możesz użyć tożsamości zarządzanej, jeśli aplikacja jest wdrożona w chmurze platformy Azure. Upewnij się, że podmiot zabezpieczeń ma wystarczające uprawnienia do odczytywania metadanych zasobów.

Uwaga

Jeśli zdecydujesz się użyć podmiotu zabezpieczeń do uwierzytelniania i autoryzacji za pomocą Microsoft Entra ID w celu uzyskania dostępu do zasobu Azure, zobacz sekcję Autoryzowanie dostępu za pomocą Microsoft Entra ID, aby upewnić się, że podmiot zabezpieczeń ma wystarczające uprawnienia dostępu do zasobu Azure.

Aby pobrać parametry połączenia przy użyciu usługi Azure Resource Manager, wystarczy dodać następującą właściwość.

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

Próbki

Zobacz repozytorium azure-spring-boot-samples w serwisie GitHub.

  • Last updated on