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

Artykuł
12/15/2024

Ten artykuł dotyczy:✅ w wersji 4.19.0 ✅ w wersji 5.19.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

Obsługiwane są następujące typy uwierzytelniania:

Uwierzytelnianie zwykłych parametrów połączenia
- Bezpośrednie uwierzytelnianie parametrów połączenia
- Uwierzytelnianie parametrów połączenia opartego na usłudze ARM
Uwierzytelnianie poświadczeń protokołu OAuth
- Uwierzytelnianie 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.

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

Nuta

Ponieważ wersja 4.3.0, uwierzytelnianie parametrów połączenia jest przestarzałe 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:

Właściwości platformy Kafka platformy Kafka platformy Azure dla usługi Spring Cloud dla usługi Event Hubs.
Globalne opcje konfiguracji uwierzytelniania credential i profile z prefiksami spring.cloud.azure.
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 common, consumer, producerlub zakresów 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 platformy Kafka są widoczne za pośrednictwem org.springframework.boot.autoconfigure.kafka.KafkaProperties (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	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 true i ustawiono `client-id`, użyje identyfikatora klienta jako identyfikatora klienta przypisanej przez użytkownika tożsamości zarządzanej. 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 firmy Microsoft Entra do nawiązania połączenia.
spring.kafka.properties.azure.profile.tenant-id	Identyfikator dzierżawy dla zasobów platformy Azure. Dozwolone wartości dla `tenant-id` to: `common`, `organizations`, `consumers`lub identyfikator dzierżawy.

Nuta

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

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

Nuta

Pamiętaj, aby dodać spring-cloud-azure-dependencies BOM wraz z powyższymi zależnościami. 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

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.

Nuta

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ę Autoryzuj dostęp 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>

Konfiguracja

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

Nuta

Jeśli używasz 4.3.0wersji, nie zapomnij ustawić właściwości spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration w celu włączenia całego przepływu pracy uwierzytelniania OAuth, gdzie kafka-binder-name jest domyślnie kafka w jednej aplikacji powiązania platformy Kafka. AzureKafkaSpringCloudStreamConfiguration konfiguracji określa parametry zabezpieczeń protokołu OAuth dla KafkaBinderConfigurationProperties, które są używane w KafkaOAuth2AuthenticateCallbackHandler w celu włączenia tożsamości platformy Azure.

W przypadku wersji po 4.4.0ta właściwość zostanie dodana automatycznie dla każdego środowiska powiązania platformy Kafka, dlatego nie ma potrzeby ręcznego dodawania jej.

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

Aby użyć tożsamości zarządzanej, musisz włączyć tożsamość zarządzaną dla usługi i przypisać role Azure Event Hubs Data Receiver i Azure Event Hubs Data Sender. Aby uzyskać więcej informacji, zobacz Assign Azure roles for access rights.
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, musisz również dodać właściwość spring.cloud.azure.credential.client-id przy użyciu identyfikatora klienta tożsamości zarządzanej przypisanej przez użytkownika.

Próbki

Zobacz repozytorium azure-spring-boot-samples w witrynie 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.

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

Nuta

Ponieważ wersja 5.0.0, w przypadku korzystania z uwierzytelniania parametrów połączenia z platformą Spring Cloud Stream nadal wymagana jest następująca właściwość, aby upewnić się, że parametry połączenia mogą obowiązywać, gdzie wartość <kafka-binder-name> powinna być kafka, 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.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

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

Nuta

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

Ponieważ wersja 4.5.0, w przypadku korzystania z uwierzytelniania parametrów połączenia z platformą Spring Cloud Stream wymagana jest następująca właściwość, aby upewnić się, że parametry połączenia mogą obowiązywać, gdzie wartość <kafka-binder-name> powinna być kafka, 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>

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.

Nuta

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 witrynie GitHub.

Udostępnij za pośrednictwem

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

Obsługiwana wersja platformy Kafka

Obsługiwane typy uwierzytelniania

Jak to działa

Uwierzytelnianie poświadczeń protokołu OAuth

Uwierzytelnianie zwykłych parametrów połączenia

Konfiguracja

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

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

Konfiguracja zależności

Podstawowe użycie

Korzystanie z uwierzytelniania OAuth

Obsługa aplikacji Spring Kafka

Konfiguracja zależności

Aktualizacja konfiguracji

Obsługa aplikacji platformy Kafka powiązanego z usługą Spring Cloud Stream

Konfiguracja zależności

Konfiguracja

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

Próbki

Korzystanie z uwierzytelniania parametrów połączenia

Konfiguracja zależności

Konfiguracja

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

Pobieranie parametrów połączenia za pomocą usługi Azure Resource Manager

Próbki

Opinia

Dodatkowe zasoby