Podpora Spring Cloud Azure Kafka

Článek
12/12/2024

Tento článek se vztahuje na:✅ verze 4.19.0 ✅ verze 5.19.0

Od verze 4.3.0 podporuje Spring Cloud Azure for Kafka různé typy přihlašovacích údajů pro ověřování a připojení ke službě Azure Event Hubs.

Podporovaná verze Kafka

Aktuální verze úvodní sady by měla být kompatibilní s klienty Apache Kafka 2.0.0 pomocí Javy 8 nebo vyšší.

Podporované typy ověřování

Podporují se 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
- 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 se nenajde žádný z těchto typů přihlašovacích údajů, řetězec přihlašovacích údajů prostřednictvím DefaultAzureTokenCredential se použije k získání přihlašovacích údajů 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

V režimu ověřování připojovacího řetězce můžete použít ověřování připojovacího řetězce přímo nebo pomocí Azure Resource Manageru načíst připojovací řetězec. 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 je ověřování připojovacího řetězce zastaralé 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:

Spring Cloud Azure for Event Hubs Kafka – vlastnosti
Možnosti konfigurace globálního ověřování credential a profile s předponami spring.cloud.azure.
Konfigurace na úrovni specifické pro Kafka Konfigurace na úrovni Kafka jsou k dispozici také pro pořadače Spring Boot a Spring Cloud Stream pro common, consumer, producernebo obory admin, které mají různé předpony.

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 příjemce Aplikace 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: Nepodporovaná možnost by měla používat běžnou konfiguraci platformy Spring Boot Kafka nebo konfigurace 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 starší 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 starší vlastnost.
spring.kafka.properties.azure.credential.managed-identity-enabled	Určuje, jestli se má spravovaná identita ověřit v Azure. Pokud true a nastaví se `client-id`, použije se ID klienta jako 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`, `consumers`nebo 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 jsou stejně jako výše uvedené.

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ů oboru 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.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. To bude automaticky zahrnovat spring-boot-starter závislost do projektu tranzitivně.

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

Poznámka

Nezapomeňte přidat spring-cloud-azure-dependencies kusovníku 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 poskytované službou Spring Cloud Azure for Kafka, můžete nakonfigurovat konkrétní přihlašovací údaje pomocí výše uvedených konfigurací. Případně můžete nakonfigurovat nic o přihlašovacích údajích, v takovém případě azure Spring Cloud načte přihlašovací údaje z prostředí. Tato část popisuje použití, která načítají přihlašovací údaje z prostředí Azure CLI nebo 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 prostředku Azure, přečtěte si část Autorizace přístupu pomocí ID Microsoft Entra, abyste měli jistotu, že objekt zabezpečení má dostatečná oprávnění pro přístup k prostředku Azure.

Následující část popisuje scénáře použití různých knihoven ekosystému Spring s ověřováním OAuth.

Podpora aplikací Spring Kafka

Tato část popisuje scénář použití aplikace Spring Boot s využitím knihovny Spring Kafka nebo 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, stačí zadat 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 využívajících 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, stačí zadat 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 4.3.0verze , nezapomeňte nastavit vlastnost spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration tak, aby povolovalo celý pracovní postup ověřování OAuth, kde kafka-binder-name je ve výchozím nastavení kafka v jedné aplikaci kafka binderu. Konfigurační AzureKafkaSpringCloudStreamConfiguration určuje parametry zabezpečení OAuth pro KafkaBinderConfigurationProperties, které se používají v KafkaOAuth2AuthenticateCallbackHandler k povolení identity Azure.

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

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

Pokud chcete používat spravovanou identitu, musíte pro svou službu povolit spravovanou identitu a přiřadit Azure Event Hubs Data Receiver a Azure Event Hubs Data Sender role. Další informace najdete v tématu Přiřazení rolí Azure pro přístupová práva.
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, musíte také přidat vlastnost spring.cloud.azure.credential.client-id s ID klienta spravované identity přiřazené uživatelem.

Vzorky

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

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

K načtení připojovacího řetězce můžete použít přímo ověřování připojovacího řetězce nebo můžete použít Azure Resource Manager.

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

Poznámka

Vzhledem k tomu, že verze 5.0.0 je při použití ověřování připojovacího řetězce s architekturou Spring Cloud Stream stále nutná následující vlastnost, aby se zajistilo, že se připojovací řetězec projeví, kdy hodnota <kafka-binder-name> by měla být kafka, pokud pro název pořadače Kafka neexistuje žádná přizpůsobená konfigurace: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

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

Poznámka

Od verze 4.3.0 je ověřování připojovacího řetězce zastaralé ve prospěch ověřování OAuth.

Vzhledem k tomu, že verze 4.5.0 vyžaduje při použití ověřování připojovacího řetězce s architekturou Spring Cloud Stream následující vlastnost, aby se zajistilo, že se připojovací řetězec projeví, kdy by hodnota <kafka-binder-name> měla být kafka, pokud pro název pořadače Kafka neexistuje žádná přizpůsobená konfigurace: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

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 Manageru, 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 objekt zabezpečení má dostatečná oprávnění ke čtení metadat prostředků.

Poznámka

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 úložiště azure-spring-boot-samples na GitHubu.

Sdílet prostřednictvím

Podpora Spring Cloud Azure Kafka

Podporovaná verze Kafka

Podporované typy ověřování

Jak to funguje

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

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

Konfigurace

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

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

Nastavení závislostí

Základní využití

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

Podpora aplikací Spring Kafka

Nastavení závislostí

Aktualizace konfigurace

Podpora aplikace Spring Cloud Stream Binder Kafka

Nastavení závislostí

Konfigurace

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

Vzorky

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

Nastavení závislostí

Konfigurace

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

Načtení připojovacího řetězce pomocí Azure Resource Manageru

Vzorky

Váš názor

Další materiály