Spring Cloud Azure Kafka のサポート

[アーティクル]
11/09/2023

この記事の対象: ✔️ バージョン 4.14.0 ✔️ バージョン 5.8.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 を使用して接続文字列を取得することができます。使用法について詳しくは、接続文字列認証の基本使用法に関するセクションを参照してください。

Note

バージョン 4.3.0 以降、OAuth 認証が優先されるため、接続文字列認証は非推奨です。

構成

Kafka サポートと OAuth 認証を使用する場合に構成できるプロパティ

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
- 例: spring.kafka.properties.azure.credential。*
Spring Kafka のコンシューマー構成オプション
- プレフィックス: spring.kafka.consumer.properties.azure
- 例: spring.kafka.consumer.properties.azure.credential。*
Spring Kafka のプロデューサー構成オプション
- プレフィックス: spring.kafka.producer.properties.azure
- 例: spring.kafka.producer.properties.azure.credential。*
Spring Kafka の管理者構成オプション
- プレフィックス: spring.kafka.admin.properties.azure
- 例: spring.kafka.admin.properties.azure.credential。*
Spring Cloud Stream Kafka Binder の一般的な構成
- プレフィックス: spring.cloud.stream.kafka.binder.configuration.azure
- 例: spring.cloud.stream.kafka.binder.configuration.azure.credential。*
Spring Cloud Stream Kafka Binder のコンシューマー構成
- プレフィックス: spring.cloud.stream.kafka.binder.consumer-properties.azure
- 例: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential。*
Spring Cloud Stream Kafka Binder のプロデューサー構成
- プレフィックス: spring.cloud.stream.kafka.binder.producer-properties.azure
- 例: spring.cloud.stream.kafka.binder.producer-properties.azure.credential。*
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 かつ `client-id` が設定されている場合、ユーザー割り当てマネージド 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 です。

Note

さまざまなレベルの構成オプションでは、次の規則が適用されます。固有性が高い構成オプションは、一般的な構成オプションよりも優先順位が高くなります。次に例を示します。

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

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

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

プロパティ	説明
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>

Note

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

基本的な使用方法

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

OAuth 認証の使用

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

Note

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

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

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 Binder Kafka アプリケーションのサポート

このセクションでは、Spring Cloud Stream Binder 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

Note

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

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

サンプル

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

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

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

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

Note

バージョン 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

Note

バージョン 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。この問題を解決するには、より高いバージョンにアップグレードします。

依存関係のセットアップ

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

<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 の接続文字列を直接使用する

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

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 も使用できます。プリンシパルにリソースメタデータを読み取るための十分なアクセス許可があることを確認してください。

Note

セキュリティプリンシパルを使用して、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 資格情報認証

プレーン接続文字列認証

構成

Kafka サポートと OAuth 認証を使用する場合に構成できるプロパティ

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

依存関係のセットアップ

基本的な使用方法

OAuth 認証の使用

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

依存関係のセットアップ

構成の更新

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

依存関係のセットアップ

構成

サンプル

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

依存関係のセットアップ

構成

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

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

サンプル

フィードバック

その他のリソース