Megosztás:

Spring Cloud Azure Kafka-támogatás

  • Alkalmazandó: ✅ Version 4.20.0, ✅ Version 5.24.1, ✅ Version 6.1.0, ✅ Version 7.0.0

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ése
  • 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 az ilyen típusú hitelesítő adatok egyike sem található, a hitelesítő adatok DefaultAzureTokenCredential keresztüli lánca az alkalmazástulajdonságokból, környezeti változókból, felügyelt identitásokból vagy azonosítókból származó hitelesítő adatok lekérésére szolgál. További információ: Spring Cloud Azure-hitelesítési.

Egyszerű kapcsolati sztring-hitelesítés

A kapcsolati sztring hitelesítési módjához használhatja közvetlenül a kapcsolati sztring-hitelesítést, vagy az Azure Resource Manager használatával lekérheti a kapcsolati sztringet. A használatról további információt a kapcsolati sztring-hitelesítés szakasz Alapszintű használat című szakaszában talál.

Jegyzet

A 4.3.0-s verzió óta a 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 é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, 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:

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 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 true és a client-id be van állítva, az ügyfélazonosí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 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 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:

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 sztring. 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ég beállítása

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

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

Jegyzet

Ne felejtse el hozzáadni a BOM-spring-cloud-azure-dependencies a fenti 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 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.

Jegyzet

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 rendszerbiztonsá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

Jegyzet

Ha 4.3.0verziót használ, ne felejtse el beállítani a spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration tulajdonságot a teljes OAuth-hitelesítési munkafolyamat engedélyezéséhez, ahol a kafka-binder-name alapértelmezés szerint kafka egyetlen Kafka-iratgyűjtő alkalmazásban. A konfigurációs AzureKafkaSpringCloudStreamConfiguration a KafkaBinderConfigurationPropertiesOAuth biztonsági paramétereit adja meg, amelyeket a KafkaOAuth2AuthenticateCallbackHandler használ az Azure Identity engedélyezéséhez.

A 4.4.0utáni verzió esetén ez a tulajdonság automatikusan hozzáadódik az egyes Kafka-kötési környezetekhez, így nincs szükség arra, hogy manuálisan vegye fel.

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

  1. A felügyelt identitás használatához engedélyeznie kell a felügyelt identitást a szolgáltatáshoz, és hozzá kell rendelnie a Azure Event Hubs Data Receiver és Azure Event Hubs Data Sender szerepköröket. 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, a spring.cloud.azure.credential.client-id tulajdonságot is hozzá kell adnia a felhasználó által hozzárendelt felügyelt identitás ügyfélazonosítójához.

Minták

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

Kapcsolati sztring-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 a kapcsolati sztring-hitelesítést Spring Cloud Stream-keretrendszerrel használja, a kapcsolati sztring érvénybe lépésének biztosításához a következő tulajdonságra van szükség, ahol a <kafka-binder-name> értékét kafka kell megadni, ha nincs testre szabott konfiguráció a Kafka-kötés nevéhez: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Ha a használt spring-cloud-dependencies verziója 2022.0.0, a java.lang.IllegalStateException: kafka_context has not been refreshed yetkivételt fog tapasztalni. A probléma megoldásához frissítsen egy magasabb verzióra.

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 le szeretné kérni a kapcsolati sztringet az Azure Resource Managerrel, adja hozzá a következő függőséget:

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

Konfiguráció

Event Hubs kapcsolati sztring használata közvetlenül

A kafkai Event Hubshoz 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 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 az egyszerű felhasználó rendelkezik elegendő engedéllyel az erőforrás-metaadatok olvasásához.

Jegyzet

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 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 az azure-spring-boot-samples GitHub-adattárat.

  • Last updated on