Spring Cloud Azure Kafka のサポート

[アーティクル]
12/11/2024

この記事の対象:✅ バージョン 4.19.0 ✅ バージョン 5.18.0

バージョン 4.3.0 以降、Spring Cloud Azure for Kafka では、認証して Azure Event Hubs に接続するためのさまざまな種類の資格情報がサポートされています。

サポートされている Kafka バージョン

スターターの現在のバージョンは、Java 8 以降を使用する Apache Kafka Clients 2.0.0 と互換性がある必要があります。

サポートされている認証の種類

次の認証の種類がサポートされています。

プレーン接続文字列認証
- 直接接続文字列認証
- ARM ベースの接続文字列認証
OAuth 資格情報認証
- マネージド ID 認証
- ユーザー名/パスワード認証
- サービスプリンシパル認証
- DefaultAzureCredential 認証

しくみ

OAuth 資格情報認証

このセクションでは、Spring Cloud Azure OAuth 認証の全体的なワークフローについて説明します。

Spring Cloud Azure では、まず、アプリケーション認証の構成に応じて、次のいずれかの種類の資格情報を構築します。

ClientSecretCredential
ClientCertificateCredential
UsernamePasswordCredential
ManagedIdentityCredential

これらの種類の資格情報が見つからない場合は、DefaultAzureTokenCredential 経由の資格情報チェーンを使用して、アプリケーションのプロパティ、環境変数、マネージド ID、または IDE から資格情報を取得します。詳細については、Spring Cloud Azure 認証に関するページを参照してください。

プレーン接続文字列認証

接続文字列認証モードでは、接続文字列認証を直接使用することも、Azure Resource Manager を使用して接続文字列を取得することもできます。使用法の詳細については、「接続文字列認証の基本的な使用法」セクションを参照してください。

手記

バージョン 4.3.0 以降では、OAuth 認証を優先して接続文字列認証が非推奨になりました。

構成

OAuth 認証で Kafka サポートを使用する場合の構成可能なプロパティ

Spring Cloud Azure for Kafka では、次の 2 つのレベルの構成オプションがサポートされています。

Event Hubs Kafka プロパティ用の Spring Cloud Azure。
spring.cloud.azureのプレフィックスを持つ credential と profile のグローバル認証構成オプション。
Kafka 固有のレベルの構成。 Kafka レベルの構成は、common、consumer、producer、または異なるプレフィックスを持つ admin スコープ用の Spring Boot および Spring Cloud Stream バインダーでも使用できます。

グローバルプロパティは、com.azure.spring.cloud.autoconfigure.context.AzureGlobalPropertiesを介して公開されます。 Kafka 固有のプロパティは、org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) と org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Spring Cloud Stream バインダー) を介して公開されます。

次の一覧は、サポートされているすべての構成オプションを示しています。

Event Hubs Kafka プロパティ用の Spring Cloud Azure。
- プロパティ: spring.cloud.azure.eventhubs.kafka.enabled
- 説明: Kafka の Azure Event Hubs への資格情報無料接続を有効にするかどうか、既定値は trueです。
Spring Cloud Azure のグローバル認証構成オプション
- プレフィックス: spring.cloud.azure
- サポートされているオプション: spring.cloud.azure.credential.*、spring.cloud.azure.profile.*
グローバル構成オプションの完全な一覧については、「グローバル構成プロパティを参照してください。
Spring Boot Kafka の一般的な構成
- プレフィックス: spring.kafka.properties.azure
- 例: .credential を spring.kafka.properties.azureします。*
Spring Kafka コンシューマー構成オプション
- プレフィックス: spring.kafka.consumer.properties.azure
- 例: .credential を spring.kafka.consumer.properties.azureします。*
Spring Kafka プロデューサーの構成オプション
- プレフィックス: spring.kafka.producer.properties.azure
- 例: .credential を spring.kafka.producer.properties.azureします。*
Spring Kafka 管理者の構成オプション
- プレフィックス: spring.kafka.admin.properties.azure
- 例: .credential を spring.kafka.admin.properties.azureします。*
Spring Cloud Stream Kafka Binder の一般的な構成
- プレフィックス: spring.cloud.stream.kafka.binder.configuration.azure
- 例: .credential を spring.cloud.stream.kafka.binder.configuration.azureします。*
Spring Cloud Stream Kafka Binder コンシューマーの構成
- プレフィックス: spring.cloud.stream.kafka.binder.consumer-properties.azure
- 例: .credential を spring.cloud.stream.kafka.binder.consumer-properties.azureします。*
Spring Cloud Stream Kafka Binder プロデューサーの構成
- プレフィックス: spring.cloud.stream.kafka.binder.producer-properties.azure
- 例: .credential を spring.cloud.stream.kafka.binder.producer-properties.azureします。*
Spring Cloud Stream Kafka Binder 管理者の構成
- プレフィックス: サポートされていません。Spring Boot Kafka の共通構成または管理者構成を使用する必要があります。

次の表に、Spring Boot Kafka の一般的な構成オプションを示します。

名前	形容
spring.kafka.properties.azure.credential.client-certificate-password	証明書ファイルのパスワード。
spring.kafka.properties.azure.credential.client-certificate-path	Azure でサービスプリンシパル認証を実行するときに使用する PEM 証明書ファイルのパス。
spring.kafka.properties.azure.credential.client-id	Azure でサービスプリンシパル認証を実行するときに使用するクライアント ID。これはレガシプロパティです。
spring.kafka.properties.azure.credential.client-secret	Azure でサービスプリンシパル認証を実行するときに使用するクライアントシークレット。これはレガシプロパティです。
spring.kafka.properties.azure.credential.managed-identity-enabled	マネージド ID を有効にして Azure で認証するかどうかを指定します。 true 、が設定されている場合は、ユーザー割り当てマネージド ID クライアント ID としてクライアント ID を使用します。既定値は falseです。
spring.kafka.properties.azure.credential.password	Azure でユーザー名/パスワード認証を実行するときに使用するパスワード。
spring.kafka.properties.azure.credential.username	Azure でユーザー名/パスワード認証を実行するときに使用するユーザー名。
spring.kafka.properties.azure.profile.environment.active-directory-endpoint	接続先の Microsoft Entra エンドポイント。
spring.kafka.properties.azure.profile.tenant-id	Azure リソースのテナント ID。 `tenant-id` に使用できる値は、`common`、`organizations`、`consumers`、またはテナント ID です。

手記

さまざまなレベルの構成オプションでは、次の規則が適用されます。より具体的な構成オプションは、一般的な構成オプションよりも優先順位が高くなります。例えば：

Spring Kafka の一般的な構成オプションは、グローバルオプションよりも優先されます。
Spring Kafka コンシューマー構成オプションは、一般的なオプションよりも優先されます。
Spring Kafka プロデューサーの構成オプションは、一般的なオプションよりも優先されます。
Spring Kafka 管理者の構成オプションは、一般的なオプションよりも優先されます。
Spring Cloud Stream Kafka Binder のオプションは、上記と同じです。

プレーン接続文字列認証で Kafka サポートを使用する場合の構成可能なプロパティ

次の表に、Kafka の Spring Boot Event Hubs の一般的な構成オプションを示します。

財産	形容
spring.cloud.azure.eventhubs.kafka.enabled	Azure Event Hubs Kafka サポートを有効にするかどうかを指定します。既定値は trueです。
spring.cloud.azure.eventhubs.connection-string	Azure Event Hubs 接続文字列。接続文字列を直接指定する場合は、この値を指定します。
spring.cloud.azure.eventhubs.namespace をする	Azure Event Hubs 名前空間。 Azure Resource Manager を使用して接続情報を取得する場合は、この値を指定します。
spring.cloud.azure.eventhubs.resource.resource-group をする	Azure Event Hubs 名前空間のリソースグループ。 Azure Resource Manager を使用して接続情報を取得する場合は、この値を指定します。
spring.cloud.azure.profile.subscription-id をする	サブスクリプション ID。 Azure Resource Manager を使用して接続情報を取得する場合は、この値を指定します。

依存関係のセットアップ

次の依存関係をプロジェクトに追加します。これにより、プロジェクトに spring-boot-starter 依存関係が推移的に自動的に含まれます。

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

手記

上記の依存関係と共に BOM spring-cloud-azure-dependencies を必ず追加してください。詳細については、Spring Cloud Azure 開発者ガイドの「Getting started」セクションを参照してください。

基本的な使用方法

以降のセクションでは、従来の Spring Boot アプリケーションの使用シナリオを示します。

OAuth 認証を使用する

Spring Cloud Azure for Kafka で提供される OAuth 認証を使用する場合は、上記の構成を使用して特定の資格情報を構成できます。または、資格情報に関して何も構成しないように選択することもできます。その場合、Spring Cloud Azure によって環境から資格情報が読み込まれます。このセクションでは、Azure CLI 環境または Azure Spring Apps ホスティング環境から資格情報を読み込む使用方法について説明します。

手記

セキュリティプリンシパルを使用して、Azure リソースにアクセスするための Microsoft Entra ID による認証と承認を行う場合は、「Microsoft Entra ID を使用したアクセスの承認」セクションを参照して、セキュリティプリンシパルに Azure リソースにアクセスするための十分なアクセス許可が付与されていることを確認してください。

次のセクションでは、OAuth 認証でさまざまな Spring エコシステムライブラリを使用するシナリオについて説明します。

Spring Kafka アプリケーションのサポート

このセクションでは、Spring Kafka または Spring Integration Kafka ライブラリを使用する Spring Boot アプリケーションの使用シナリオについて説明します。

依存関係のセットアップ

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

構成の更新

OAuth 認証を使用するには、次の例に示すように、Event Hubs エンドポイントを指定するだけです。

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

Spring Cloud Stream バインダー Kafka アプリケーションのサポート

このセクションでは、Spring Cloud Stream バインダー Kafka ライブラリを使用する Spring Boot アプリケーションの使用シナリオについて説明します。

依存関係のセットアップ

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

構成

OAuth 認証を使用するには、次の例に示すように Event Hubs エンドポイントを指定するだけです。

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

手記

バージョン 4.3.0を使用している場合は、spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration プロパティを設定して OAuth 認証ワークフロー全体を有効にすることを忘れないでください。この場合、kafka-binder-name は 1 つの Kafka バインダーアプリケーションで既定で kafka されます。構成 AzureKafkaSpringCloudStreamConfiguration では、KafkaBinderConfigurationPropertiesの OAuth セキュリティパラメーターを指定します。これは、KafkaOAuth2AuthenticateCallbackHandler で Azure ID を有効にするために使用されます。

4.4.0後のバージョンの場合、このプロパティは Kafka バインダー環境ごとに自動的に追加されるため、手動で追加する必要はありません。

OAuth 認証にマネージド ID を使用する

マネージド ID を使用するには、サービスのマネージド ID を有効にして、Azure Event Hubs Data Receiver ロールと Azure Event Hubs Data Sender ロールを割り当てる必要があります。詳細については、「アクセス権に Azure ロールを割り当てる」を参照してください。
application.yml ファイルで次のプロパティを構成します。
```
spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true
```
大事な

ユーザー割り当てマネージド ID を使用している場合は、ユーザー割り当てマネージド ID クライアント ID を持つプロパティ spring.cloud.azure.credential.client-id も追加する必要があります。

サンプル

GitHub の azure-spring-boot-samples リポジトリを参照してください。

接続文字列認証を使用する

接続文字列認証を直接使用することも、Azure Resource Manager を使用して接続文字列を取得することもできます。

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

手記

バージョン 5.0.0 以降、Spring Cloud Stream フレームワークで接続文字列認証を使用する場合は、接続文字列を有効にするために、次のプロパティが必要です。ここで、Kafka バインダー名のカスタマイズされた構成がない場合は、<kafka-binder-name> の値を kafka する必要があります。spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

使用した spring-cloud-dependencies のバージョンが 2022.0.0場合は、java.lang.IllegalStateException: kafka_context has not been refreshed yet例外が発生します。この問題を解決するには、より高いバージョンにアップグレードします。

手記

バージョン 4.3.0 以降では、OAuth 認証を優先して接続文字列認証が非推奨になりました。

バージョン 4.5.0 以降、Spring Cloud Stream フレームワークで接続文字列認証を使用する場合は、接続文字列を有効にするために次のプロパティが必要です。ここでは、Kafka バインダー名のカスタマイズされた構成がない場合に <kafka-binder-name> の値を kafka する必要があります spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration。

依存関係のセットアップ

Kafka 用 Azure Event Hubs を使用するように Apache Kafka アプリケーションを移行する場合は、次の依存関係を追加します。

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

Azure Resource Manager を使用して接続文字列を取得する場合は、次の依存関係を追加します。

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

構成

Event Hubs 接続文字列を直接使用する

Event Hubs for Kafka に接続する最も簡単な方法は、接続文字列を使用することです。次のプロパティを追加するだけです。

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}

Azure Resource Manager を使用して接続文字列を取得する

アプリケーションで接続文字列を構成しない場合は、Azure Resource Manager を使用して接続文字列を取得できます。 Azure Resource Manager で認証するには、Azure CLI に格納されている資格情報や、Visual Studio Code や Intellij IDEA などの別のローカル開発ツールを使用することもできます。または、アプリケーションが Azure Cloud にデプロイされている場合は、マネージド ID を使用できます。リソースメタデータを読み取るためにプリンシパルに十分なアクセス許可があることを確認してください。

手記

セキュリティプリンシパルを使用して、Azure リソースにアクセスするための Microsoft Entra ID による認証と承認を行う場合は、「Microsoft Entra ID によるアクセスの承認」セクションを参照して、セキュリティプリンシパルに Azure リソースにアクセスするための十分なアクセス許可が付与されていることを確認してください。

Azure Resource Manager を使用して接続文字列を取得するには、次のプロパティを追加するだけです。

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

サンプル

GitHub の azure-spring-boot-samples リポジトリを参照してください。

次の方法で共有

Spring Cloud Azure Kafka のサポート

サポートされている Kafka バージョン

サポートされている認証の種類

しくみ

OAuth 資格情報認証

プレーン接続文字列認証

構成

OAuth 認証で Kafka サポートを使用する場合の構成可能なプロパティ

プレーン接続文字列認証で Kafka サポートを使用する場合の構成可能なプロパティ

依存関係のセットアップ

基本的な使用方法

OAuth 認証を使用する

Spring Kafka アプリケーションのサポート

依存関係のセットアップ

構成の更新

Spring Cloud Stream バインダー Kafka アプリケーションのサポート

依存関係のセットアップ

構成

OAuth 認証にマネージド ID を使用する

サンプル

接続文字列認証を使用する

依存関係のセットアップ

構成

Event Hubs 接続文字列を直接使用する

Azure Resource Manager を使用して接続文字列を取得する

サンプル

フィードバック

その他のリソース