Podpora Spring Cloud Azure Kafka

  • Platí pro: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Podpora Platformy Spring Cloud Azure Kafka pomáhá aplikacím Spring ověřovat a připojovat se k Azure Event Hubs pomocí přihlašovacích údajů OAuth nebo připojovacích řetězců. Tento článek popisuje podporované typy ověřování, možnosti konfigurace, závislosti a scénáře použití.

Podporovaná verze Kafka

Aktuální verze starteru je kompatibilní s klienty Apache Kafka 2.0.0 a používá Java 8 nebo vyšší.

Podporované typy ověřování

Úvodní sada podporuje následující typy ověřování:

  • Ověřování prostým připojovacím řetězcem
    • Přímé ověřování připojovacího řetězce
    • Ověřování připojovacího řetězce založeného na ARM
  • Ověřování přihlašovacích údajů OAuth
    • Ověřování spravované identity
    • Ověřování pomocí uživatelského jména a hesla
    • Ověřování instančního objektu služby
    • ověřování DefaultAzureCredential

Jak to funguje

Ověřování přihlašovacích údajů OAuth

Tato část popisuje celkový pracovní postup ověřování Spring Cloud Azure OAuth.

Spring Cloud Azure nejprve sestaví jeden z následujících typů přihlašovacích údajů v závislosti na konfiguraci ověřování aplikací:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Pokud aplikace nepoužívá jeden z těchto typů přihlašovacích údajů, aplikace pomocí řetězu DefaultAzureTokenCredential přihlašovacích údajů získá přihlašovací údaje z vlastností aplikace, proměnných prostředí, spravované identity nebo idEs. Podrobné informace najdete v tématu ověřování Azure Spring Cloud.

Ověřování prostým připojovacím řetězcem

Pro režim ověřování pomocí připojovacího řetězce můžete použít ověřování pomocí připojovacího řetězce přímo nebo načíst připojovací řetězec pomocí Azure Resource Manager. Další informace o využití najdete v části Základní použití pro ověřování připojovacího řetězce.

Poznámka

Od verze 4.3.0 se ověřování pomocí připojovacího řetězce již nedoporučuje ve prospěch ověřování OAuth.

Konfigurace

Konfigurovatelné vlastnosti při použití podpory Kafka s ověřováním OAuth

Spring Cloud Azure for Kafka podporuje následující dvě úrovně možností konfigurace:

  1. Vlastnosti Spring Cloud Azure pro Event Hubs Kafka.
  2. Možnosti konfigurace globálního ověřování credential a profile s předponami spring.cloud.azure.
  3. Konfigurace úrovní pro Kafka Konfigurace na úrovni platformy Kafka jsou k dispozici také pro bindery Spring Boot a Spring Cloud Stream pro rozsahy common, consumer, producer nebo admin, přičemž každý používá jiný prefix.

Globální vlastnosti jsou vystaveny prostřednictvím com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Vlastnosti specifické pro Kafka se zveřejňují prostřednictvím org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) a org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (binder Spring Cloud Stream).

Následující seznam obsahuje všechny podporované možnosti konfigurace.

  • Spring Cloud Azure for Event Hubs Kafka – vlastnosti

    • Vlastnost: spring.cloud.azure.eventhubs.kafka.enabled
    • Popis: jestli chcete povolit bezplatné připojení přihlašovacích údajů ke službě Azure Event Hubs pro Kafka, výchozí hodnota je true.

  • Možnosti konfigurace globálního ověřování Azure v Spring Cloudu

    • Předpona: spring.cloud.azure
    • Podporované možnosti: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Úplný seznam možností globální konfigurace najdete v tématu Globální vlastnosti konfigurace.

  • Společná konfigurace Spring Boot Kafka

    • Předpona: spring.kafka.properties.azure
    • Příklad: spring.kafka.properties.azure.credential.*

  • Možnosti konfigurace pro uživatele Spring Kafka

    • Předpona: spring.kafka.consumer.properties.azure
    • Příklad: spring.kafka.consumer.properties.azure.credential.*

  • Možnosti konfigurace producenta Spring Kafka

    • Předpona: spring.kafka.producer.properties.azure
    • Příklad: spring.kafka.producer.properties.azure.credential.*

  • Možnosti konfigurace správce Spring Kafka

    • Předpona: spring.kafka.admin.properties.azure
    • Příklad: spring.kafka.admin.properties.azure.credential.*

  • Běžná konfigurace Spring Cloud Stream Kafka Binderu

    • Předpona: spring.cloud.stream.kafka.binder.configuration.azure
    • Příklad: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Konfigurace konzumenta Spring Cloud Stream Kafka Binder

    • Předpona: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Příklad: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Konfigurace producenta Spring Cloud Stream Kafka Binderu

    • Předpona: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Příklad: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Konfigurace správce Spring Cloud Stream Kafka Binderu

    • Předpona: Není podporována, použijte společnou konfiguraci Spring Boot Kafka nebo konfiguraci správce.

Následující tabulka uvádí běžné možnosti konfigurace Platformy Kafka pro Spring Boot:

Jméno Popis
spring.kafka.properties.azure.credential.client-certificate-password Heslo souboru certifikátu.
spring.kafka.properties.azure.credential.client-certificate-path Cesta k souboru certifikátu PEM, který se má použít při ověřování instančního objektu v Azure
spring.kafka.properties.azure.credential.client-id ID klienta, které se má použít při ověřování instančního objektu v Azure. Toto je zastaralá vlastnost.
spring.kafka.properties.azure.credential.client-secret Tajný klíč klienta, který se má použít při ověřování instančního objektu v Azure. Toto je zastaralá vlastnost.
spring.kafka.properties.azure.credential.managed-identity-enabled Určuje, jestli se má spravovaná identita ověřit v Azure. Pokud true a je client-id nastavená, ID klienta je ID klienta přiřazené uživatelem spravované identity. Výchozí hodnota je false.
spring.kafka.properties.azure.credential.password Heslo, které se má použít při ověřování pomocí uživatelského jména a hesla v Azure.
spring.kafka.properties.azure.credential.username Uživatelské jméno, které se má použít při ověřování pomocí uživatelského jména a hesla v Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Koncový bod Microsoft Entra, ke kterému se chcete připojit.
spring.kafka.properties.azure.profile.tenant-id ID tenanta pro prostředky Azure. Hodnoty povolené pro tenant-id jsou: common, organizations, consumersnebo ID tenanta.

Poznámka

Možnosti konfigurace v různých úrovních používají následující pravidla. Konkrétnější možnosti konfigurace mají vyšší prioritu než běžné možnosti konfigurace. Například:

  • Běžné možnosti konfigurace Spring Kafka nahrazují globální možnosti.
  • Možnosti konfigurace uživatelů Spring Kafka nahrazují běžné možnosti.
  • Možnosti konfigurace producenta Spring Kafka nahrazují běžné možnosti.
  • Možnosti konfigurace správce Spring Kafka nahrazují běžné možnosti.
  • Možnosti Spring Cloud Stream Kafka Binderu se řídí stejným vzorem.

Konfigurovatelné vlastnosti při použití podpory Kafka s ověřováním prostým připojovacím řetězcem

Následující tabulka ukazuje službu Spring Boot Event Hubs pro běžné možnosti konfigurace Kafka:

Vlastnost Popis
spring.cloud.azure.eventhubs.kafka.enabled Jestli chcete povolit podporu Azure Event Hubs Kafka. Výchozí hodnota je true.
spring.cloud.azure.eventhubs.connection-string Připojovací řetězec služby Azure Event Hubs Tuto hodnotu zadejte, pokud chcete připojovací řetězec zadat přímo.
spring.cloud.azure.eventhubs.namespace Obor názvů služby Azure Event Hubs Tuto hodnotu zadejte, když chcete načíst informace o připojení prostřednictvím Azure Resource Manageru.
spring.cloud.azure.eventhubs.resource.resource-group Skupina prostředků pro jmenný prostor služby Azure Event Hubs. Tuto hodnotu zadejte, když chcete načíst informace o připojení prostřednictvím Azure Resource Manageru.
spring.cloud.azure.profile.subscription-id ID předplatného. Tuto hodnotu zadejte, když chcete načíst informace o připojení prostřednictvím Azure Resource Manageru.

Nastavení závislostí

Přidejte do projektu následující závislost. Tato závislost automaticky zahrnuje spring-boot-starter závislost ve vašem projektu.

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

Poznámka

Nezapomeňte přidat BOM spring-cloud-azure-dependencies spolu s výše uvedenou závislostí. Podrobnosti najdete v části Začínáme příručky pro vývojáře Spring Cloud v Azure.

Základní využití

Následující části ukazují klasické scénáře použití aplikace Spring Boot.

Použití ověřování OAuth

Pokud používáte ověřování OAuth, které Spring Cloud Azure poskytuje pro Kafka, můžete nakonfigurovat konkrétní přihlašovací údaje pomocí předchozích konfigurací. Případně se můžete rozhodnout, že nebudete konfigurovat žádné přihlašovací údaje. V tomto případě spring Cloud Azure načte přihlašovací údaje z prostředí. Tato část popisuje, jak načíst přihlašovací údaje z prostředí Azure CLI nebo z hostitelského prostředí Azure Spring Apps.

Poznámka

Pokud se rozhodnete použít objekt zabezpečení k ověření a autorizaci pomocí Microsoft Entra ID pro přístup k Azure prostředku, přečtěte si část Autorizace přístupu pomocí Microsoft Entra ID, abyste zajistili, že objekt zabezpečení má dostatečná oprávnění pro přístup k Azure prostředku.

Následující část popisuje scénáře, které používají různé knihovny ekosystému Spring s ověřováním OAuth.

Podpora aplikací Spring Kafka

Tato část popisuje scénář použití aplikace Spring Boot, která používá Spring Kafka nebo knihovnu Spring Integration Kafka.

Nastavení závislostí
<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>

Aktualizace konfigurace

Pokud chcete použít ověřování OAuth, zadejte koncový bod služby Event Hubs, jak je znázorněno v následujícím příkladu:

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

Podpora aplikace Spring Cloud Stream Binder Kafka

Tato část popisuje scénář použití aplikací Spring Boot, které používají knihovnu Kafka binder Spring Cloud Stream.

Nastavení závislostí
<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>
Konfigurace

Pokud chcete použít ověřování OAuth, zadejte koncový bod služby Event Hubs, jak je znázorněno v následujícím příkladu:

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

Poznámka

Pokud používáte verzi 4.3.0, nastavte spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration vlastnost tak, aby umožňovala celý pracovní postup ověřování OAuth. kafka-binder-name je ve výchozím nastavení kafka v aplikaci s jedním adaptérem Kafka. AzureKafkaSpringCloudStreamConfiguration Konfigurace určuje parametry zabezpečení OAuth pro KafkaBinderConfigurationProperties. Tato konfigurace se v KafkaOAuth2AuthenticateCallbackHandler používá k povolení Azure Identity.

U verzí po 4.4.0se tato vlastnost automaticky přidá pro každé prostředí binderu Kafka, takže ji nemusíte přidávat ručně.

Použití spravované identity pro ověřování OAuth

  1. Pokud chcete používat spravovanou identitu, povolte spravovanou identitu pro vaši službu a přiřaďte role Azure Event Hubs Data ReceiverAzure Event Hubs Data Sender . Další informace najdete v tématu Přiřazení rolí Azure pro přístupová práva.

  2. V souboru application.yml nakonfigurujte následující vlastnosti:

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

    Důležitý

    Pokud používáte spravovanou identitu přiřazenou uživatelem, přidejte také vlastnost spring.cloud.azure.credential.client-id s ID klienta spravované identity přiřazené uživatelem.

Vzorky

Podívejte se na azure-spring-boot-samples úložiště na GitHubu.

Použít ověřování pomocí připojovacího řetězce

Můžete přímo použít ověření pomocí připojovacího řetězce nebo k načtení připojovacího řetězce použít Azure Resource Manager.

Poznámka

Od verze 5.0.0 při použití ověřování pomocí připojovacího řetězce v rámci frameworku Spring Cloud Stream stále potřebujete následující vlastnost, aby připojovací řetězec fungoval. Hodnota <kafka-binder-name> by měla být kafka, pokud neupravíte název vazby Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Pokud používáte verzi spring-cloud-dependenciesjava.lang.IllegalStateException: kafka_context has not been refreshed yet, dojde k výjimce 2022.0.0. Pokud chcete tento problém vyřešit, upgradujte na vyšší verzi.

Nastavení závislostí

Pokud chcete migrovat aplikaci Apache Kafka pro použití služby Azure Event Hubs pro Kafka, přidejte následující závislosti.

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

Pokud chcete načíst připojovací řetězec pomocí Azure Resource Manager, přidejte následující závislost:

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

Konfigurace

Přímé použití připojovacího řetězce služby Event Hubs

Nejjednodušší způsob, jak se připojit ke službě Event Hubs pro Kafka, je připojovací řetězec. Stačí přidat následující vlastnost.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Načtení připojovacího řetězce pomocí Azure Resource Manageru

Pokud nechcete ve své aplikaci konfigurovat připojovací řetězec, můžete připojovací řetězec načíst pomocí Azure Resource Manageru. Pokud se chcete ověřit pomocí Azure Resource Manageru, můžete také použít přihlašovací údaje uložené v Azure CLI nebo jiném místním vývojovém nástroji, jako je Visual Studio Code nebo Intellij IDEA. Případně můžete použít spravovanou identitu, pokud je vaše aplikace nasazená do cloudu Azure. Ujistěte se, že má objekt zabezpečení dostatečná oprávnění ke čtení metadat prostředků.

Poznámka

Pokud se rozhodnete použít objekt zabezpečení k ověření a autorizaci pomocí Microsoft Entra ID pro přístup k Azure prostředku, přečtěte si část Autorizace přístupu pomocí Microsoft Entra ID, abyste zajistili, že objekt zabezpečení má dostatečná oprávnění pro přístup k Azure prostředku.

Pokud chcete k načtení připojovacího řetězce použít Azure Resource Manager, stačí přidat následující vlastnost.

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

Vzorky

Podívejte se na azure-spring-boot-samples úložiště na GitHubu.

  • Last updated on