Share via

Dukungan Spring Cloud Azure Kafka

  • Artikel

Artikel ini berlaku untuk: ✔️ Versi 4.14.0 ✔️ Versi 5.8.0

Dari versi 4.3.0, Spring Cloud Azure for Kafka mendukung berbagai jenis kredensial untuk mengautentikasi dan menyambungkan ke Azure Event Hubs.

Versi Kafka yang didukung

Versi starter saat ini harus kompatibel dengan Apache Kafka Clients 2.0.0 menggunakan Java 8 atau yang lebih tinggi.

Jenis autentikasi yang didukung

Jenis autentikasi berikut ini didukung:

  • Autentikasi string koneksi biasa
    • Autentikasi string koneksi langsung
    • Autentikasi string koneksi berbasis ARM
  • Autentikasi kredensial OAuth
    • Autentikasi identitas terkelola
    • Autentikasi nama pengguna/kata sandi
    • Autentikasi perwakilan layanan
    • DefaultAzureCredential autentikasi

Cara kerjanya

Autentikasi kredensial OAuth

Bagian ini menjelaskan alur kerja keseluruhan autentikasi Spring Cloud Azure OAuth.

Spring Cloud Azure pertama-tama akan membangun salah satu jenis kredensial berikut tergantung pada konfigurasi autentikasi aplikasi:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Jika tidak ada jenis kredensial ini yang ditemukan, rantai kredensial melalui DefaultAzureTokenCredential akan digunakan untuk mendapatkan kredensial dari properti aplikasi, variabel lingkungan, identitas terkelola, atau IDEs. Untuk informasi selengkapnya, lihat Autentikasi Spring Cloud Azure.

Autentikasi string koneksi biasa

Untuk mode autentikasi string koneksi, Anda dapat menggunakan autentikasi string koneksi secara langsung atau menggunakan Azure Resource Manager untuk mengambil string koneksi. Untuk informasi selengkapnya tentang penggunaan, lihat bagian Penggunaan dasar untuk autentikasi string koneksi.

Catatan

Sejak versi 4.3.0, autentikasi string koneksi tidak digunakan lagi demi autentikasi OAuth.

Konfigurasi

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi OAuth

Spring Cloud Azure for Kafka mendukung dua tingkat opsi konfigurasi berikut:

  1. Properti Spring Cloud Azure for Event Hubs Kafka.
  2. Opsi credential konfigurasi autentikasi global dan profile dengan awalan .spring.cloud.azure
  3. Konfigurasi tingkat khusus Kafka. Konfigurasi tingkat Kafka juga tersedia untuk pengikat Spring Boot dan Spring Cloud Stream untuk common, consumer, producer, atau admin cakupan, yang memiliki awalan yang berbeda.

Properti global diekspos melalui com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Properti khusus Kafka diekspos melalui org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) dan org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (pengikat Spring Cloud Stream).

Daftar berikut ini memperlihatkan semua opsi konfigurasi yang didukung.

  • Properti Spring Cloud Azure for Event Hubs Kafka.

    • Properti: spring.cloud.azure.eventhubs.kafka.enabled
    • Deskripsi: apakah akan mengaktifkan koneksi gratis kredensial ke Azure Event Hubs for Kafka, nilai defaultnya adalah true.

  • Opsi konfigurasi autentikasi global Spring Cloud Azure

    • Awalan: spring.cloud.azure
    • Opsi yang didukung: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Untuk daftar lengkap opsi konfigurasi global, lihat Properti konfigurasi global.

  • Konfigurasi umum Spring Boot Kafka

    • Awalan: spring.kafka.properties.azure
    • Contoh: spring.kafka.properties.azure.credential.*

  • Opsi konfigurasi konsumen Spring Kafka

    • Awalan: spring.kafka.consumer.properties.azure
    • Contoh: spring.kafka.consumer.properties.azure.credential.*

  • Opsi konfigurasi produsen Spring Kafka

    • Awalan: spring.kafka.producer.properties.azure
    • Contoh: spring.kafka.producer.properties.azure.credential.*

  • Opsi konfigurasi admin Spring Kafka

    • Awalan: spring.kafka.admin.properties.azure
    • Contoh: spring.kafka.admin.properties.azure.credential.*

  • Konfigurasi umum Spring Cloud Stream Kafka Binder

    • Awalan: spring.cloud.stream.kafka.binder.configuration.azure
    • Contoh: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Konfigurasi konsumen Spring Cloud Stream Kafka Binder

    • Awalan: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Contoh: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Konfigurasi produsen Spring Cloud Stream Kafka Binder

    • Awalan: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Contoh: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Konfigurasi admin Spring Cloud Stream Kafka Binder

    • Awalan: Tidak didukung, harus menggunakan konfigurasi umum atau admin Spring Boot Kafka.

Tabel berikut menunjukkan opsi konfigurasi umum Spring Boot Kafka:

Nama Deskripsi
spring.kafka.properties.azure.credential.client-certificate-password Kata sandi file sertifikat.
spring.kafka.properties.azure.credential.client-certificate-path Jalur file sertifikat PEM yang akan digunakan saat melakukan autentikasi perwakilan layanan dengan Azure.
spring.kafka.properties.azure.credential.client-id ID klien untuk digunakan saat melakukan autentikasi perwakilan layanan dengan Azure. Ini adalah properti warisan.
spring.kafka.properties.azure.credential.client-secret Rahasia klien untuk digunakan saat melakukan autentikasi perwakilan layanan dengan Azure. Ini adalah properti warisan.
spring.kafka.properties.azure.credential.managed-identity-enabled Apakah akan mengaktifkan identitas terkelola untuk mengautentikasi dengan Azure. Jika true dan client-id diatur, akan menggunakan ID klien sebagai ID klien identitas terkelola yang ditetapkan pengguna. Nilai default-nya adalah salah.
spring.kafka.properties.azure.credential.password Kata sandi yang digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
spring.kafka.properties.azure.credential.username Nama pengguna yang akan digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Titik akhir Microsoft Entra untuk disambungkan.
spring.kafka.properties.azure.profile.tenant-id ID Penyewa untuk sumber daya Azure. Nilai yang diizinkan untuk tenant-id adalah: common, organizations, consumers, atau ID penyewa.

Catatan

Opsi konfigurasi di tingkat yang berbeda menerapkan aturan berikut. Opsi konfigurasi yang lebih spesifik memiliki prioritas yang lebih tinggi daripada yang umum. Misalnya:

  • Opsi konfigurasi umum Spring Kafka menggantikan opsi global.
  • Opsi konfigurasi konsumen Spring Kafka menggantikan opsi umum.
  • Opsi konfigurasi produsen Spring Kafka menggantikan opsi umum.
  • Opsi konfigurasi admin Spring Kafka menggantikan opsi umum.
  • Opsi Spring Cloud Stream Kafka Binder sama seperti di atas.

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi string koneksi biasa

Tabel berikut menunjukkan opsi konfigurasi umum Spring Boot Event Hubs untuk Kafka:

Properti Deskripsi
spring.cloud.azure.eventhubs.kafka.enabled Apakah akan mengaktifkan dukungan Azure Event Hubs Kafka. Nilai defaultnya adalah benar.
spring.cloud.azure.eventhubs.connection-string Azure Event Hubs string koneksi. Berikan nilai ini saat Anda ingin memberikan string koneksi secara langsung.
spring.cloud.azure.eventhubs.namespace Namespace Azure Event Hubs. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group Grup sumber daya namespace Azure Event Hubs. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.
spring.cloud.azure.profile.subscription-id ID langganan. Berikan nilai ini saat Anda ingin mengambil informasi koneksi melalui Azure Resource Manager.

Penyiapan dependensi

Tambahkan dependensi berikut ke proyek Anda. Ini akan secara otomatis menyertakan spring-boot-starter dependensi dalam proyek Anda secara transitif.

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

Catatan

Ingatlah untuk menambahkan BOM spring-cloud-azure-dependencies bersama dengan dependensi di atas. Untuk detailnya, lihat bagian Memulai dari panduan pengembang Spring Cloud Azure.

Penggunaan dasar

Bagian berikut menunjukkan skenario penggunaan aplikasi Spring Boot klasik.

Menggunakan autentikasi OAuth

Saat Anda menggunakan autentikasi OAuth yang disediakan oleh Spring Cloud Azure for Kafka, Anda dapat mengonfigurasi kredensial tertentu menggunakan konfigurasi di atas. Atau, Anda dapat memilih untuk mengonfigurasi apa pun tentang kredensial, dalam hal ini Spring Cloud Azure akan memuat kredensial dari lingkungan. Bagian ini menjelaskan penggunaan yang memuat kredensial dari lingkungan Azure CLI atau lingkungan hosting Azure Spring Apps.

Catatan

Jika Anda memilih untuk menggunakan prinsip keamanan untuk mengautentikasi dan mengotorisasi dengan ID Microsoft Entra untuk mengakses sumber daya Azure, lihat bagian Otorisasi akses dengan ID Microsoft Entra untuk memastikan prinsip keamanan telah diberikan izin yang memadai untuk mengakses sumber daya Azure.

Bagian berikut menjelaskan skenario menggunakan pustaka ekosistem Spring yang berbeda dengan autentikasi OAuth.

Dukungan aplikasi Spring Kafka

Bagian ini menjelaskan skenario penggunaan untuk aplikasi Spring Boot menggunakan pustaka Spring Kafka atau Spring Integration Kafka.

Penyiapan dependensi
<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>

Pembaruan konfigurasi

Untuk menggunakan autentikasi OAuth, cukup tentukan titik akhir Azure Event Hubs, seperti yang ditunjukkan dalam contoh berikut:

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

Dukungan aplikasi Kafka binder Spring Cloud Stream

Bagian ini menjelaskan skenario penggunaan untuk aplikasi Spring Boot menggunakan pustaka Kafka binder Spring Cloud Stream.

Penyiapan dependensi
<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>
Konfigurasi

Untuk menggunakan autentikasi OAuth, cukup tentukan titik akhir Azure Event Hubs seperti yang ditunjukkan dalam contoh berikut:

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

Catatan

Jika Anda menggunakan versi 4.3.0, jangan lupa untuk mengatur spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration properti untuk mengaktifkan seluruh alur kerja autentikasi OAuth, di mana kafka-binder-name secara kafka default dalam satu aplikasi binder Kafka. Konfigurasi AzureKafkaSpringCloudStreamConfiguration menentukan parameter keamanan OAuth untuk KafkaBinderConfigurationProperties, yang digunakan KafkaOAuth2AuthenticateCallbackHandler untuk mengaktifkan Azure Identity.

Untuk versi setelah 4.4.0, properti ini akan ditambahkan secara otomatis untuk setiap lingkungan binder Kafka, sehingga Anda tidak perlu menambahkannya secara manual.

Sampel

Lihat repositori azure-spring-boot-samples di GitHub.

Menggunakan autentikasi string koneksi

Anda dapat menggunakan autentikasi string koneksi secara langsung atau menggunakan Azure Resource Manager untuk mengambil string koneksi.

Catatan

Sejak versi 4.3.0, autentikasi string koneksi tidak digunakan lagi demi autentikasi OAuth.

Karena versi 4.5.0, saat menggunakan autentikasi string koneksi dengan kerangka kerja Spring Cloud Stream, properti berikut diperlukan untuk memastikan bahwa string koneksi dapat berlaku, di mana nilai <kafka-binder-name> seharusnya kafka ketika tidak ada konfigurasi yang disesuaikan untuk nama binder Kafka Anda.

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

Penyiapan dependensi

Tambahkan dependensi berikut jika Anda ingin memigrasikan aplikasi Apache Kafka Anda untuk menggunakan Azure Event Hubs untuk Kafka.

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

Jika Anda ingin mengambil string koneksi menggunakan Azure Resource Manager, tambahkan dependensi berikut:

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

Konfigurasi

Menggunakan string koneksi Azure Event Hubs secara langsung

Cara paling sederhana untuk terhubung ke Azure Event Hubs for Kafka adalah dengan string koneksi. Cukup tambahkan properti berikut.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Menggunakan Azure Resource Manager untuk mengambil string koneksi

Jika Anda tidak ingin mengonfigurasi string koneksi di aplikasi, Anda dapat menggunakan Azure Resource Manager untuk mengambil string koneksi. Untuk mengautentikasi dengan Azure Resource Manager, Anda juga dapat menggunakan kredensial yang disimpan di Azure CLI atau alat pengembangan lokal lainnya seperti Visual Studio Code atau Intellij IDEA. Secara bergantian, Anda dapat menggunakan Identitas Terkelola jika aplikasi Anda disebarkan ke Azure Cloud. Pastikan perwakilan memiliki izin yang memadai untuk membaca metadata sumber daya.

Catatan

Jika Anda memilih untuk menggunakan prinsip keamanan untuk mengautentikasi dan mengotorisasi dengan ID Microsoft Entra untuk mengakses sumber daya Azure, lihat bagian Otorisasi akses dengan ID Microsoft Entra untuk memastikan prinsip keamanan telah diberikan izin yang memadai untuk mengakses sumber daya Azure.

Untuk menggunakan Azure Resource Manager untuk mengambil string koneksi, cukup tambahkan properti berikut.

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

Sampel

Lihat repositori azure-spring-boot-samples di GitHub.