Udostępnij za pośrednictwem

Obsługa platformy Azure Kafka w usłudze Spring Cloud

  • Artykuł

Ten artykuł dotyczy: ✔️ wersja 4.14.0 ✔️ w wersji 5.8.0

W wersji 4.3.0 platforma Spring Cloud Azure dla platformy Kafka obsługuje różne typy poświadczeń w celu uwierzytelniania i nawiązywania połączenia z usługą Azure Event Hubs.

Obsługiwana wersja platformy Kafka

Bieżąca wersja startera powinna być zgodna z klientami platformy Apache Kafka w wersji 2.0.0 przy użyciu języka Java 8 lub nowszego.

Obsługiwane typy uwierzytelniania

Następujące typy uwierzytelnienia są obsługiwane:

  • Zwykłe uwierzytelnianie parametry połączenia
    • Bezpośrednie uwierzytelnianie parametry połączenia
    • Uwierzytelnianie parametry połączenia oparte na usłudze ARM
  • Uwierzytelnianie poświadczeń protokołu OAuth
    • Uwierzytelnianie tożsamości zarządzanej
    • Uwierzytelnianie nazwy użytkownika/hasła
    • Uwierzytelnianie nazwy głównej usługi
    • Uwierzytelnianie w aplikacjach 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.

Platforma Spring Cloud Azure najpierw utworzy jeden z następujących typów poświadczeń w zależności od konfiguracji uwierzytelniania aplikacji:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Jeśli żaden z tych typów poświadczeń nie zostanie znaleziony, łańcuch poświadczeń za pośrednictwem DefaultAzureTokenCredential będzie używany do uzyskiwania poświadczeń z właściwości aplikacji, zmiennych środowiskowych, tożsamości zarządzanej lub środowisk IDE. Aby uzyskać szczegółowe informacje, zobacz Spring Cloud Azure authentication (Uwierzytelnianie platformy Azure w usłudze Spring Cloud).

Zwykłe uwierzytelnianie parametry połączenia

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

Uwaga

Ponieważ wersja 4.3.0, uwierzytelnianie parametry połączenia jest przestarzałe na rzecz uwierzytelniania OAuth.

Konfigurowanie

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 platformy Kafka platformy Kafka platformy Azure dla usługi Spring Cloud dla usługi Event Hubs.
  2. Globalne opcje konfiguracji uwierzytelniania i credentialprofile z prefiksami .spring.cloud.azure
  3. Konfiguracje na poziomie specyficznym dla platformy Kafka. Konfiguracje na poziomie platformy Kafka są również dostępne dla powiązań strumieni spring boot i Spring Cloud dla commonzakresów , consumer, producerlub admin , które mają różne prefiksy.

Właściwości globalne są uwidacznione za pośrednictwem elementu com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Właściwości specyficzne dla platformy Kafka są widoczne za pośrednictwem org.springframework.boot.autoconfigure.kafka.KafkaProperties platformy (Spring Boot) i org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (binder strumienia Spring Cloud).

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

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

    • Właściwość: spring.cloud.azure.eventhubs.kafka.enabled
    • Opis: czy włączyć bezpłatne połączenie 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.

  • Typowa konfiguracja platformy Kafka platformy 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.*

  • Typowa konfiguracja powiązania platformy Kafka usługi 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 integratora platformy Kafka w usłudze 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 narzędzia binder platformy Kafka w usłudze Spring Cloud Stream

    • Prefiks: Nieobsługiwane należy używać typowej konfiguracji platformy Kafka platformy Spring Boot lub administratora.

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

Nazwa/nazwisko 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 wartość true i client-id jest ustawiona, użyje identyfikatora klienta jako identyfikatora klienta tożsamości zarządzanej przypisanej przez użytkownika. Domyślna wartość 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 firmy Microsoft Entra do nawiązania połączenia.
spring.kafka.properties.azure.profile.tenant-id Identyfikator dzierżawy dla zasobów platformy Azure. Dozwolone tenant-id wartości 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 narzędzia Binder platformy Kafka usługi Spring Cloud Stream są podobne do powyższych.

Konfigurowalne właściwości podczas korzystania z obsługi platformy Kafka przy użyciu zwykłego uwierzytelniania parametry połączenia

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

Właściwości 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. Spowoduje to automatyczne uwzględnienie spring-boot-starter zależności w projekcie przechodnio.

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

Uwaga

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

Podstawowy sposób użycia

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

Korzystanie z uwierzytelniania OAuth

W przypadku korzystania z uwierzytelniania OAuth udostępnianego przez platformę Spring Cloud Azure dla platformy Kafka można skonfigurować określone poświadczenia przy użyciu powyższych konfiguracji. Alternatywnie możesz skonfigurować nic o poświadczeniach, w tym przypadku platforma Spring Cloud Azure załaduje poświadczenia ze środowiska. W tej sekcji opisano użycie, które ładują poświadczenia ze środowiska interfejsu wiersza polecenia platformy Azure lub środowiska hostingu usługi Azure Spring Apps.

Uwaga

Jeśli zdecydujesz się użyć podmiotu zabezpieczeń do uwierzytelniania i autoryzacji za pomocą identyfikatora Entra firmy Microsoft na potrzeby uzyskiwania dostępu do zasobu platformy Azure, zobacz sekcję Autoryzowanie dostępu za pomocą identyfikatora Entra firmy Microsoft, aby upewnić się, że podmiot zabezpieczeń otrzymał wystarczające uprawnienia dostępu do zasobu platformy 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 przy użyciu biblioteki Spring Kafka lub 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, wystarczy określić 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 platformy Kafka powiązanego z usługą Spring Cloud Stream

W tej sekcji opisano scenariusz użycia aplikacji Spring Boot korzystających z biblioteki platformy Kafka binder usługi 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>
Konfigurowanie

Aby użyć uwierzytelniania OAuth, wystarczy określić 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, nie zapomnij ustawić spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration właściwości w celu włączenia całego przepływu pracy uwierzytelniania OAuth, gdzie kafka-binder-name jest kafka domyślnie w jednej aplikacji binder platformy Kafka. AzureKafkaSpringCloudStreamConfiguration Konfiguracja określa parametry zabezpieczeń protokołu OAuth dla KafkaBinderConfigurationPropertieselementu , które są używane do KafkaOAuth2AuthenticateCallbackHandler włączania tożsamości platformy Azure.

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

Przykłady

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

Korzystanie z uwierzytelniania parametry połączenia

Aby pobrać parametry połączenia, możesz użyć uwierzytelniania parametry połączenia bezpośrednio lub użyć usługi Azure Resource Manager.

Uwaga

Ponieważ wersja 4.3.0, uwierzytelnianie parametry połączenia jest przestarzałe na rzecz uwierzytelniania OAuth.

Ponieważ wersja 4.5.0, w przypadku korzystania z uwierzytelniania parametry połączenia za pomocą platformy Spring Cloud Stream wymagana jest następująca właściwość, aby upewnić się, że parametry połączenia może obowiązywać, gdzie wartość <kafka-binder-name> powinna być kafka taka, gdy nie ma dostosowanej konfiguracji dla nazwy powiązania platformy Kafka.

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

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 usługi Azure Resource Manager, dodaj następującą zależność:

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

Konfigurowanie

Bezpośrednie używanie usługi Event Hubs parametry połączenia

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

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Pobieranie parametry połączenia przy użyciu usługi Azure Resource Manager

Jeśli nie chcesz konfigurować parametry 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ą identyfikatora Entra firmy Microsoft na potrzeby uzyskiwania dostępu do zasobu platformy Azure, zobacz sekcję Autoryzowanie dostępu za pomocą identyfikatora Entra firmy Microsoft, aby upewnić się, że podmiot zabezpieczeń otrzymał wystarczające uprawnienia dostępu do zasobu platformy 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}

Przykłady

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