Spring Cloud Azure Kafka-támogatás

  • A következőre érvényes:: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

A Spring Cloud Azure Kafka támogatása OAuth-hitelesítő adatokkal vagy kapcsolati sztringekkel segíti a Spring-alkalmazásokat a hitelesítésben és a Azure Event Hubs való csatlakozásban. Ez a cikk a támogatott hitelesítési típusokat, konfigurációs beállításokat, függőségeket és használati forgatókönyveket ismerteti.

Támogatott Kafka-verzió

A kezdő verzió jelenlegi verziója kompatibilis az Apache Kafka Clients 2.0.0-val, és Java 8 vagy újabb verziót használ.

Támogatott hitelesítési típusok

Az indítás a következő hitelesítési típusokat támogatja:

  • Egyszerű hitelesítés kapcsolati karakterlánccal
    • Közvetlen kapcsolódási sztringes hitelesítés
    • ARM-alapú kapcsolatikarakterlánc-hitelesítés
  • OAuth hitelesítő adatok hitelesítése
    • Felügyelt identitás hitelesítése
    • Felhasználónév/jelszó hitelesítése
    • Szolgáltatásnév-hitelesítés
    • DefaultAzureCredential hitelesítés

Hogyan működik?

OAuth hitelesítő adatok hitelesítése

Ez a szakasz a Spring Cloud Azure OAuth-hitelesítés általános munkafolyamatát ismerteti.

A Spring Cloud Azure először az alábbi hitelesítő adatok egyikét hozza létre az alkalmazáshitelesítés konfigurációjától függően:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Ha az alkalmazás nem használ ilyen típusú hitelesítő adatokat, az alkalmazás a hitelesítő adatok láncolatával DefaultAzureTokenCredential kéri le a hitelesítő adatokat az alkalmazás tulajdonságaiból, környezeti változóiból, felügyelt identitásaiból vagy azonosítóiból. További információ: Spring Cloud Azure-hitelesítési.

Egyszerű kapcsolati sztring-hitelesítés

A kapcsolódási sztringes hitelesítési mód esetén közvetlenül használhatja a kapcsolódási sztringes hitelesítést, vagy az Azure Resource Managerrel lekérheti a kapcsolódási sztringet. A használattal kapcsolatos további információkért lásd a Kapcsolati karakterláncos hitelesítés alapvető használata című szakaszt.

Jegyzet

A 4.3.0-s verzió óta kapcsolati karakterlánc hitelesítés elavult az OAuth-hitelesítés javára.

Konfiguráció

Konfigurálható tulajdonságok a Kafka-támogatás OAuth-hitelesítéssel történő használatakor

A Spring Cloud Azure for Kafka a következő két konfigurációs szintet támogatja:

  1. Spring Cloud Azure for Event Hubs Kafka tulajdonságai.
  2. A credential és profile globális hitelesítési konfigurációs beállításai spring.cloud.azureelőtagokkal.
  3. Kafka-specifikus szintű konfigurációk. A Kafka-szintű konfigurációk a Spring Boot- és Spring Cloud Stream-kötésekhez is elérhetők common, consumer, producervagy admin hatókörökhöz, amelyek különböző előtagokkal rendelkeznek.

A globális tulajdonságok com.azure.spring.cloud.autoconfigure.context.AzureGlobalPropertieskeresztül érhetők el. A Kafka-specifikus tulajdonságok org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) és org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream kötőanyag) keresztül érhetők el.

Az alábbi lista az összes támogatott konfigurációs beállítást tartalmazza.

  • Spring Cloud Azure for Event Hubs Kafka tulajdonságai.

    • Tulajdonság: spring.cloud.azure.eventhubs.kafka.enabled
    • Leírás: Ha engedélyezni szeretné a hitelesítő adatok nélküli kapcsolatot az Azure Event Hubs for Kafkához, az alapértelmezett érték true.

  • A Spring Cloud Azure globális hitelesítési konfigurációs beállításai

    • Előtag: spring.cloud.azure
    • Támogatott beállítások: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    A globális konfigurációs beállítások teljes listáját globális konfigurációs tulajdonságokcímű témakörben találja.

  • A Spring Boot Kafka gyakori konfigurációja

    • Előtag: spring.kafka.properties.azure
    • Példa: spring.kafka.properties.azure.credential.*

  • A Spring Kafka fogyasztói konfigurációs beállításai

    • Előtag: spring.kafka.consumer.properties.azure
    • Példa: spring.kafka.consumer.properties.azure.credential.*

  • A Spring Kafka gyártói konfigurációs lehetőségei

    • Előtag: spring.kafka.producer.properties.azure
    • Példa: spring.kafka.producer.properties.azure.credential.*

  • A Spring Kafka rendszergazdai konfigurációs beállításai

    • Előtag: spring.kafka.admin.properties.azure
    • Példa: spring.kafka.admin.properties.azure.credential.*

  • A Spring Cloud Stream Kafka Binder általános konfigurációja

    • Előtag: spring.cloud.stream.kafka.binder.configuration.azure
    • Példa: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • A Spring Cloud Stream Kafka Binder fogyasztói konfigurációja

    • Előtag: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Példa: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • A Spring Cloud Stream Kafka Binder gyártójának konfigurációja

    • Előtag: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Példa: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Spring Cloud Stream Kafka Binder rendszergazdai konfiguráció

    • Előtag: Nem támogatott, használja a Spring Boot Kafka általános vagy rendszergazdai konfigurációját.

Az alábbi táblázat a Spring Boot Kafka gyakori konfigurációs beállításait mutatja be:

Név Leírás
spring.kafka.properties.azure.credential.client-certificate-password A tanúsítványfájl jelszava.
spring.kafka.properties.azure.credential.client-certificate-path A PEM-tanúsítványfájl elérési útja, amelyet az Azure-ral végzett szolgáltatásnév-hitelesítés során kell használni.
spring.kafka.properties.azure.credential.client-id Az Azure-ral végzett egyszerű szolgáltatáshitelesítéshez használandó ügyfélazonosító. Ez egy örökölt tulajdonság.
spring.kafka.properties.azure.credential.client-secret Az Azure-ral végzett egyszerű szolgáltatáshitelesítéshez használandó ügyfélkód. Ez egy örökölt tulajdonság.
spring.kafka.properties.azure.credential.managed-identity-enabled A felügyelt identitás azure-ral való hitelesítésének engedélyezése. Ha true és a(z) client-id be van állítva, az ügyfélazonosító a felhasználó által hozzárendelt felügyelt identitás ügyfélazonosítója. Az alapértelmezett érték a false.
spring.kafka.properties.azure.credential.password Felhasználónév-/jelszó-hitelesítés azure-ral történő végrehajtásakor használandó jelszó.
spring.kafka.properties.azure.credential.username Felhasználónév az Azure-ral történő felhasználónév-/jelszó-hitelesítés végrehajtásakor.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint A Microsoft Entra-végpont, amelyhez csatlakozni szeretne.
spring.kafka.properties.azure.profile.tenant-id Az Azure-erőforrások bérlőazonosítója. A tenant-id engedélyezett értékek a következők: common, organizations, consumersvagy bérlőazonosító.

Jegyzet

A különböző szintek konfigurációs beállításai az alábbi szabályokat alkalmazzák. A konkrétabb konfigurációs beállítások prioritása magasabb, mint a gyakoriaké. Például:

  • A Spring Kafka általános konfigurációs beállításai felülírják a globális beállításokat.
  • A Spring Kafka fogyasztói konfigurációs beállításai felülírják a gyakori beállításokat.
  • A Spring Kafka gyártói konfigurációs beállításai felülírják a gyakori lehetőségeket.
  • A Spring Kafka rendszergazdai konfigurációs beállításai felülírják a gyakori beállításokat.
  • A Spring Cloud Stream Kafka Binder beállításai ugyanazt a mintát követik.

Konfigurálható tulajdonságok a Kafka-támogatás egyszerű kapcsolati sztring-hitelesítéssel történő használatakor

Az alábbi táblázat a Kafkához készült Spring Boot Event Hubs általános konfigurációs beállításait mutatja be:

Ingatlan Leírás
spring.cloud.azure.eventhubs.kafka.enabled Az Azure Event Hubs Kafka támogatásának engedélyezése. Az alapértelmezett érték a true.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs kapcsolati karakterlánca. Adja meg ezt az értéket, ha közvetlenül meg szeretné adni a kapcsolati sztringet.
spring.cloud.azure.eventhubs.namespace Azure Event Hubs névtér. Adja meg ezt az értéket, ha le szeretné kérni a kapcsolati adatokat az Azure Resource Manageren keresztül.
spring.cloud.azure.eventhubs.resource.resource-group Az Azure Event Hubs-névtér erőforráscsoportja. Adja meg ezt az értéket, ha le szeretné kérni a kapcsolati adatokat az Azure Resource Manageren keresztül.
spring.cloud.azure.profile.subscription-id Az előfizetés azonosítója. Adja meg ezt az értéket, ha le szeretné kérni a kapcsolati adatokat az Azure Resource Manageren keresztül.

Függőségek beállítása

Adja hozzá a következő függőséget a projekthez. Ez a függőség automatikusan tartalmazza a spring-boot-starter függőséget a projektben.

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

Jegyzet

Ne felejtse el hozzáadni a BOM-ot spring-cloud-azure-dependencies az előző függőséggel együtt. További információt a Spring Cloud Azure fejlesztői útmutatójánakElső lépések című szakaszában talál.

Alapszintű használat

Az alábbi szakaszok a klasszikus Spring Boot-alkalmazáshasználati forgatókönyveket mutatják be.

OAuth-hitelesítés használata

Ha a Spring Cloud Azure által a Kafkához biztosított OAuth-hitelesítést használja, az előző konfigurációk használatával konfigurálhat bizonyos hitelesítő adatokat. Másik lehetőségként dönthet úgy is, hogy nem konfigurál hitelesítő adatokat. Ebben az esetben a Spring Cloud Azure betölti a hitelesítő adatokat a környezetből. Ez a szakasz bemutatja, hogyan tölthet be hitelesítő adatokat a Azure CLI környezetből vagy a Azure Spring Apps üzemeltetési környezetből.

Jegyzet

Ha úgy dönt, hogy egy biztonsági taggal hitelesíti és engedélyezi a Microsoft Entra ID egy Azure-erőforrás elérését, olvassa el a Hozzáférés engedélyezése Microsoft Entra ID című szakaszt, amely biztosítja, hogy a biztonsági tag rendelkezik-e megfelelő engedéllyel az Azure erőforrás eléréséhez.

Az alábbi szakasz olyan forgatókönyveket ismertet, amelyek különböző Spring-ökoszisztéma-kódtárakat használnak OAuth-hitelesítéssel.

Spring Kafka-alkalmazás támogatása

Ez a szakasz a Spring Kafkát vagy a Spring Integration Kafka-kódtárat használó Spring Boot-alkalmazások használati forgatókönyvét ismerteti.

Függőségek beállítása
<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>

Konfigurációs frissítés

OAuth-hitelesítés használatához adja meg az Event Hubs-végpontot az alábbi példában látható módon:

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

Spring Cloud Stream binder Kafka-alkalmazás támogatása

Ez a szakasz a Spring Cloud Stream-iratgyűjtő Kafka-kódtárat használó Spring Boot-alkalmazások használati forgatókönyvét ismerteti.

Függőségek beállítása
<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>
Konfiguráció

OAuth-hitelesítés használatához adja meg az Event Hubs-végpontot az alábbi példában látható módon:

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

Jegyzet

Ha verziót 4.3.0használ, állítsa be a tulajdonságot a spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration teljes OAuth-hitelesítési munkafolyamat engedélyezéséhez. kafka alapértelmezés szerint kafka-binder-name egyetlen Kafka binderalkalmazásban. A konfiguráció AzureKafkaSpringCloudStreamConfiguration megadja az OAuth biztonsági paramétereit a következőhöz KafkaBinderConfigurationProperties: . Ez a konfiguráció Azure Identitás engedélyezéséhez használhatóKafkaOAuth2AuthenticateCallbackHandler.

A következő 4.4.0verziók esetében ez a tulajdonság automatikusan hozzáadódik az egyes Kafka-kötési környezetekhez, így nem kell manuálisan hozzáadnia.

Felügyelt identitás használata OAuth-hitelesítéshez

  1. A felügyelt identitás használatához engedélyezze a felügyelt identitást a szolgáltatásához, és rendelje hozzá a Azure Event Hubs Data Sender és Azure Event Hubs Data Receiver szerepkört. További információ: Azure-szerepkörök hozzárendelése hozzáférési jogosultságokhoz.

  2. Konfigurálja a következő tulajdonságokat a application.yml fájlban:

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

    Fontos

    Ha felhasználó által hozzárendelt felügyelt identitást használ, adja hozzá a tulajdonságot spring.cloud.azure.credential.client-id a felhasználó által hozzárendelt felügyelt identitás ügyfélazonosítójához is.

Minták

Tekintse meg a azure-spring-boot-samples GitHub adattárát.

Kapcsolati karakterláncos hitelesítés használata

Használhatja közvetlenül a kapcsolati sztring-hitelesítést, vagy az Azure Resource Manager használatával lekérheti a kapcsolati sztringet.

Jegyzet

Az 5.0.0-s verzió óta, amikor kapcsolati karakterlánc hitelesítést használ a Spring Cloud Stream-keretrendszerrel, a következő tulajdonságra van szüksége a kapcsolati karakterlánc működésének biztosításához. A(z) <kafka-binder-name> értékének kafka-nek kell lennie, ha nem szabja testre a Kafka binder nevét: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Ha az Ön által használt spring-cloud-dependencies verziója 2022.0.0, akkor a java.lang.IllegalStateException: kafka_context has not been refreshed yet kivétellel találkozik. A probléma megoldásához frissítsen egy magasabb verzióra.

Függőségek beállítása

Ha az Apache Kafka-alkalmazást az Azure Event Hubs for Kafka használatára szeretné migrálni, adja hozzá a következő függőségeket.

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

Ha Azure Resource Manager használatával szeretné lekérni a kapcsolati karakterlánc, adja hozzá a következő függőséget:

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

Konfiguráció

Az Event Hubs kapcsolati sztring közvetlen használata

Az Event Hubs for Kafka szolgáltatáshoz való csatlakozás legegyszerűbb módja a kapcsolati karakterlánc használata. Csak adja hozzá a következő tulajdonságot.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Kapcsolati sztring lekérése az Azure Resource Manager használatával

Ha nem szeretné konfigurálni a kapcsolati sztringet az alkalmazásban, az Azure Resource Managerrel lekérheti a kapcsolati sztringet. Az Azure Resource Managerrel való hitelesítéshez használhatja az Azure CLI-ben vagy más helyi fejlesztési eszközben, például a Visual Studio Code-ban vagy az Intellij IDEA-ban tárolt hitelesítő adatokat is. Másik lehetőségként a felügyelt identitást is használhatja, ha az alkalmazás az Azure Cloudban van üzembe helyezve. Csak győződjön meg arról, hogy a felhasználói fiók megfelelő jogosultsággal rendelkezik az erőforrás metaadatainak olvasásához.

Jegyzet

Ha úgy dönt, hogy egy biztonsági taggal hitelesíti és engedélyezi a Microsoft Entra ID egy Azure-erőforrás elérését, olvassa el a Hozzáférés engedélyezése Microsoft Entra ID című szakaszt, amely biztosítja, hogy a biztonsági tag rendelkezik-e megfelelő engedéllyel az Azure erőforrás eléréséhez.

Ha az Azure Resource Managerrel szeretné lekérni a kapcsolati sztringet, egyszerűen adja hozzá a következő tulajdonságot.

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

Minták

Tekintse meg a azure-spring-boot-samples GitHub adattárát.

  • Last updated on