Dukungan Spring Cloud Azure Kafka

2025-06-22
Berlaku untuk: ✅ Version 4.20.0, ✅ Version 5.22.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
- autentikasi DefaultAzureCredential

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.

Nota

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:

Properti Spring Cloud Azure for Event Hubs Kafka.
Opsi konfigurasi autentikasi global credential dan profile dengan awalan spring.cloud.azure.
Konfigurasi tingkat khusus Kafka. Konfigurasi tingkat Kafka juga tersedia untuk pengikat Spring Boot dan Spring Cloud Stream untuk cakupan common, consumer, producer, atau admin, 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-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 defaultnya adalah `false`.
spring.kafka.properties.azure.credential.password	Kata sandi yang digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
musim semi.kafka.properties.azure.credential.username	Nama pengguna yang akan digunakan saat melakukan autentikasi nama pengguna/kata sandi dengan Azure.
musim semi.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.

Nota

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:

Harta benda	Deskripsi
spring.cloud.azure.eventhubs.kafka.enabled	Apakah akan mengaktifkan dukungan Azure Event Hubs Kafka. Nilai defaultnya adalah `true`.
spring.cloud.azure.eventhubs.connection-string	String koneksi Azure Event Hubs. 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 dependensi spring-boot-starter dalam proyek Anda secara transitif.

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

Nota

Ingatlah untuk menambahkan spring-cloud-azure-dependencies BOM bersama dengan dependensi di atas. Untuk detailnya, lihat bagian Memulai 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.

Nota

Jika Anda memilih untuk menggunakan prinsip keamanan untuk mengautentikasi dan mengotorisasi dengan ID Microsoft Entra untuk mengakses sumber daya Azure, lihat bagian Mengotorisasi 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

Nota

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

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

Menggunakan identitas terkelola untuk autentikasi OAuth

Untuk menggunakan identitas terkelola, Anda perlu mengaktifkan identitas terkelola untuk layanan Anda dan menetapkan peran Azure Event Hubs Data Receiver dan Azure Event Hubs Data Sender. Untuk informasi selengkapnya, lihat Menetapkan peran Azure untuk hak akses.
Konfigurasikan properti berikut dalam file application.yml Anda:
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
Penting

Jika Anda menggunakan identitas terkelola yang ditetapkan pengguna, Anda juga perlu menambahkan properti spring.cloud.azure.credential.client-id dengan ID klien identitas terkelola yang ditetapkan pengguna.

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.

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

Nota

Karena versi 5.0.0, saat menggunakan autentikasi string koneksi dengan kerangka kerja Spring Cloud Stream, properti berikut masih diperlukan untuk memastikan bahwa string koneksi dapat berlaku, di mana nilai <kafka-binder-name> harus 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.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Jika versi spring-cloud-dependencies yang Anda gunakan 2022.0.0, Anda akan menemukan pengecualian java.lang.IllegalStateException: kafka_context has not been refreshed yet. Untuk mengatasi masalah ini, tingkatkan ke versi yang lebih tinggi.

Nota

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> harus kafka ketika tidak ada konfigurasi yang disesuaikan untuk nama pengikat 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.

Nota

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.

Bagikan melalui

Dukungan Spring Cloud Azure Kafka

Versi Kafka yang didukung

Jenis autentikasi yang didukung

Cara kerjanya

Autentikasi kredensial OAuth

Autentikasi string koneksi biasa

Konfigurasi

Properti yang dapat dikonfigurasi saat menggunakan dukungan Kafka dengan autentikasi OAuth

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

Penyiapan dependensi

Penggunaan dasar

Menggunakan autentikasi OAuth

Dukungan aplikasi Spring Kafka

Penyiapan dependensi

Pembaruan konfigurasi

Dukungan aplikasi Kafka binder Spring Cloud Stream

Penyiapan dependensi

Konfigurasi

Menggunakan identitas terkelola untuk autentikasi OAuth

Sampel

Menggunakan autentikasi string koneksi

Penyiapan dependensi

Konfigurasi

Menggunakan string koneksi Azure Event Hubs secara langsung

Menggunakan Azure Resource Manager untuk mengambil string koneksi

Sampel

Saran dan Komentar

Sumber Daya Tambahan: