Spring Cloud Azure Kafka-támogatás

  • Cikk

Ez a cikk a következőre vonatkozik: ✔️ 4.14.0 ✔️ 5.8.0-s verzió

A 4.3.0-s verziótól kezdve a Spring Cloud Azure for Kafka különböző típusú hitelesítő adatokat támogat a hitelesítéshez és az Azure Event Hubshoz való csatlakozáshoz.

Támogatott Kafka-verzió

Az indítás jelenlegi verziójának kompatibilisnek kell lennie az Apache Kafka Clients 2.0.0-val Java 8 vagy újabb verzióval.

Támogatott hitelesítési típusok

A következő hitelesítési típusok támogatottak:

  • Egyszerű kapcsolati sztring hitelesítés
    • Közvetlen kapcsolati sztring hitelesítés
    • ARM-alapú kapcsolati sztring-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
    • Egyszerű szolgáltatás hitelesítése
    • 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 az alkalmazáshitelesítés konfigurációjától függően először a következő típusú hitelesítő adatok egyikét fogja létrehozni:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Ha ezek közül a hitelesítő adatok közül egyik sem található, a hitelesítőadat-lánc használatával DefaultAzureTokenCredential az alkalmazás tulajdonságaiból, környezeti változóiból, felügyelt identitásából vagy azonosítóiból szerezhet be hitelesítő adatokat. Részletes információkért lásd a Spring Cloud Azure-hitelesítést.

Egyszerű kapcsolati sztring hitelesítés

A kapcsolati sztring hitelesítési mód esetében használhatja közvetlenül kapcsolati sztring hitelesítést, vagy az Azure Resource Manager használatával lekérheti a kapcsolati sztring. A használattal kapcsolatos további információkért tekintse meg kapcsolati sztring hitelesítés alapszintű használatát ismertető szakaszt.

Megjegyzés:

A 4.3.0-s verzió óta kapcsolati sztring hitelesítés elavult az OAuth-hitelesítések 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> előtagjainak spring.cloud.azureglobális hitelesítési konfigurációs beállításai.profile
  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 különböző előtagokkal rendelkező , consumer, producervagy admin hatókörökhözcommon.

A globális tulajdonságok a com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. A Kafka-specifikus tulajdonságok a (Spring Boot) és org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties a (Spring Cloud Stream kötőanyag) segítségével org.springframework.boot.autoconfigure.kafka.KafkaProperties é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 a 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áért tekintse meg a globális konfigurációs tulajdonságokat.

  • 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, a Spring Boot Kafka általános vagy rendszergazdai konfigurációt kell használnia.

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

Name 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 Egy PEM-tanúsítványfájl elérési útja, amelyet a szolgáltatásnév azure-beli hitelesítésekor 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 igaz , és a client-id beállítás be van állítva, az ügyfél-azonosítót fogja használni a felhasználó által hozzárendelt felügyelt identitás ügyfélazonosítójaként. Az alapértelmezett érték: hamis.
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. Az engedélyezett tenant-id értékek a következők: common, organizations, consumersvagy a bérlőazonosító.

Megjegyzés:

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 a fentiekhez hasonlóak.

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:

Property 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 igaz.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs kapcsolati sztring. Adja meg ezt az értéket, ha közvetlenül szeretné megadni a kapcsolati sztring.
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ég beállítása

Adja hozzá a következő függőséget a projekthez. Ez automatikusan magában foglalja a spring-boot-starter függőséget a projektben tranzitív módon.

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

Megjegyzés:

Ne felejtse el hozzáadni a BOM-t spring-cloud-azure-dependencies a fenti függőséggel együtt. További részletekért tekintse meg a Spring Cloud Azure fejlesztői útmutatójának Első lépések szakaszát.

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 for Kafka által biztosított OAuth-hitelesítést használja, a fenti konfigurációk használatával konfigurálhatja az adott hitelesítő adatokat. Másik lehetőségként dönthet úgy is, hogy semmit sem konfigurál a hitelesítő adatokról, ebben az esetben a Spring Cloud Azure betölti a hitelesítő adatokat a környezetből. Ez a szakasz azOkat a használatokat ismerteti, amelyek betöltik a hitelesítő adatokat az Azure CLI-környezetből vagy az Azure Spring Apps üzemeltetési környezetéből.

Megjegyzés:

Ha úgy dönt, hogy biztonsági taggal hitelesít és engedélyez egy Azure-erőforráshoz való hozzáférést a Microsoft Entra-azonosítóval, tekintse meg a Hozzáférés engedélyezése a Microsoft Entra ID-val című szakaszt, amelyből megtudhatja, hogy a biztonsági tag megkapta-e a megfelelő engedélyt az Azure-erőforrás eléréséhez.

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

Spring Kafka-alkalmazás támogatása

Ez a szakasz a Spring Boot-alkalmazás Használati forgatókönyvét ismerteti a Spring Kafka vagy a Spring Integration Kafka könyvtár használatával.

Függőség 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

Az OAuth-hitelesítés használatához egyszerűen 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 kötőanyag Kafka-kódtárát használó Spring Boot-alkalmazások használati forgatókönyvét ismerteti.

Függőség 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ó

Az OAuth-hitelesítés használatához egyszerűen 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

Megjegyzés:

Ha verziót 4.3.0használ, ne felejtse el beállítani 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, ahol kafka-binder-name alapértelmezés szerint egyetlen Kafka binder-alkalmazásban van kafka . A konfiguráció AzureKafkaSpringCloudStreamConfiguration megadja az Azure Identity engedélyezéséhez KafkaBinderConfigurationPropertieshasznált KafkaOAuth2AuthenticateCallbackHandler OAuth biztonsági paramétereket.

A következő 4.4.0verzió esetében ez a tulajdonság automatikusan hozzáadódik az egyes Kafka-kötési környezetekhez, így nincs szükség manuálisan történő hozzáadásra.

Samples

Tekintse meg az azure-spring-boot-samples adattárat a GitHubon.

Kapcsolati sztring hitelesítés használata

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

Megjegyzés:

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

A 4.5.0-s verzió óta, amikor kapcsolati sztring-hitelesítést használ a Spring Cloud Stream-keretrendszerrel, a következő tulajdonságra van szükség annak biztosításához, hogy a kapcsolati sztring érvénybe léphessen, ahol az értéknek <kafka-binder-name> akkor kell lenniekafka, ha nincs testre szabott konfiguráció a Kafka binder nevéhez.

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

Függőség 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 az Azure Resource Managerrel szeretné lekérni a kapcsolati sztring, 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 Kafkához való csatlakozás legegyszerűbb módja a kapcsolati sztring. 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 sztring az alkalmazásban, az Azure Resource Manager használatával lekérheti a kapcsolati sztring. 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 az egyszerű felhasználó rendelkezik elegendő engedéllyel az erőforrás-metaadatok olvasásához.

Megjegyzés:

Ha úgy dönt, hogy biztonsági taggal hitelesít és engedélyez egy Azure-erőforráshoz való hozzáférést a Microsoft Entra-azonosítóval, tekintse meg a Hozzáférés engedélyezése a Microsoft Entra-azonosítóval című szakaszt, amelyből megtudhatja, hogy a biztonsági tag megkapta-e a megfelelő engedélyt az Azure-erőforrás eléréséhez.

Ha az Azure Resource Managerrel szeretné lekérni a kapcsolati sztring, 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}

Samples

Tekintse meg az azure-spring-boot-samples adattárat a GitHubon.