Supporto di Spring Cloud Azure Kafka

  • Si applica a: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

Il supporto di Spring Cloud Azure Kafka consente alle applicazioni Spring di autenticarsi e connettersi a Hub eventi di Azure usando le credenziali OAuth o le stringhe di connessione. Questo articolo descrive i tipi di autenticazione supportati, le opzioni di configurazione, le dipendenze e gli scenari di utilizzo.

Versione di Kafka supportata

La versione corrente dello starter è compatibile con i client Apache Kafka 2.0.0 e usa Java 8 o versione successiva.

Tipi di autenticazione supportati

Lo starter supporta i tipi di autenticazione seguenti:

  • Autenticazione con stringa di connessione normale
    • Autenticazione della stringa di connessione diretta
    • Autenticazione della stringa di connessione basata su ARM
  • Autenticazione delle credenziali OAuth
    • Autenticazione dell'identità gestita
    • Autenticazione con nome utente/password
    • Autenticazione dell'entità servizio
    • autenticazione DefaultAzureCredential

Come funziona

Autenticazione delle credenziali OAuth

Questa sezione descrive il flusso di lavoro complessivo dell'autenticazione OAuth di Spring Cloud di Azure.

Spring Cloud Azure prima compila uno dei tipi di credenziali seguenti, a seconda della configurazione di autenticazione dell'applicazione:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Se l'applicazione non usa uno di questi tipi di credenziali, usa la catena di credenziali tramite DefaultAzureTokenCredential per ottenere le credenziali dalle proprietà dell'applicazione, dalle variabili di ambiente, dall'identità gestita o dagli IDE. Per informazioni dettagliate, vedere autenticazione di Spring Cloud azure.

Autenticazione con stringa di connessione normale

Per la modalità di autenticazione della stringa di connessione, è possibile usare direttamente l'autenticazione della stringa di connessione o usare Azure Resource Manager per recuperare la stringa di connessione. Per altre informazioni sull'utilizzo, vedere la sezione Utilizzo di base per l'autenticazione della stringa di connessione.

Nota

A partire dalla versione 4.3.0, l'autenticazione tramite stringa di connessione è stata deprecata a favore dell'autenticazione OAuth.

Configurazione

Proprietà configurabili quando si usa il supporto kafka con l'autenticazione OAuth

Spring Cloud Azure per Kafka supporta i due livelli di opzioni di configurazione seguenti:

  1. Proprietà Kafka di Spring Cloud Azure per Hub eventi.
  2. Le opzioni di configurazione globali dell'autenticazione di credential e profile con il prefisso spring.cloud.azure.
  3. Configurazioni di livello specifiche di Kafka. Le configurazioni a livello di Kafka sono disponibili anche per i binder di Spring Boot e Spring Cloud Stream per gli ambiti common, consumer, producer o admin, che hanno prefissi diversi.

Le proprietà globali vengono esposte tramite com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. Le proprietà specifiche di Kafka vengono esposte tramite org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) e org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (Binder Spring Cloud Stream).

L'elenco seguente mostra tutte le opzioni di configurazione supportate.

  • Proprietà Kafka di Spring Cloud Azure per Event Hubs.

    • Proprietà: spring.cloud.azure.eventhubs.kafka.enabled
    • Descrizione: se abilitare la connessione gratuita delle credenziali a Hub eventi di Azure per Kafka, il valore predefinito è true.

  • Opzioni di configurazione dell'autenticazione globale di Spring Cloud Azure

    • Prefisso: spring.cloud.azure
    • Opzioni supportate: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Per l'elenco completo delle opzioni di configurazione globali, vedere proprietà di configurazione globale.

  • Configurazione comune di Spring Boot Kafka

    • Prefisso: spring.kafka.properties.azure
    • Esempio: spring.kafka.properties.azure.credential.*

  • Opzioni di configurazione del consumer di Spring Kafka

    • Prefisso: spring.kafka.consumer.properties.azure
    • Esempio: spring.kafka.consumer.properties.azure.credential.*

  • Opzioni di configurazione del producer di Spring Kafka

    • Prefisso: spring.kafka.producer.properties.azure
    • Esempio: spring.kafka.producer.properties.azure.credential.*

  • Opzioni di configurazione dell'amministratore di Spring Kafka

    • Prefisso: spring.kafka.admin.properties.azure
    • Esempio: spring.kafka.admin.properties.azure.credential.*

  • Configurazione comune di Spring Cloud Stream Kafka Binder

    • Prefisso: spring.cloud.stream.kafka.binder.configuration.azure
    • Esempio: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Configurazione consumer di Spring Cloud Stream Kafka Binder

    • Prefisso: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Esempio: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Configurazione del produttore di Kafka Binder per Spring Cloud Stream

    • Prefisso: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Esempio: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Configurazione dell'amministratore di Spring Cloud Stream Kafka Binder

    • Prefisso: non supportato, utilizzare la configurazione comune o di amministrazione di Spring Boot Kafka.

La tabella seguente illustra le opzioni di configurazione comuni di Spring Boot Kafka:

Nome Descrizione
spring.kafka.properties.azure.credential.client-certificate-password Password del file del certificato.
spring.kafka.properties.azure.credential.client-certificate-path Percorso di un file di certificato PEM da usare quando si esegue l'autenticazione dell'entità servizio con Azure.
spring.kafka.properties.azure.credential.client-id ID client da utilizzare per eseguire l'autenticazione del service principal con Azure. Questa è una proprietà esistente.
spring.kafka.properties.azure.credential.client-secret Segreto del client da utilizzare per eseguire l'autenticazione dell'entità servizio con Azure. Questa è una proprietà precedente.
spring.kafka.properties.azure.credential.managed-identity-enabled Indica se abilitare l'identità gestita per l'autenticazione con Azure. Se true e client-id è impostato, l'ID client corrisponde all'ID client dell'identità gestita assegnata dall'utente. Il valore predefinito è false.
spring.kafka.properties.azure.credential.password Password da usare quando si esegue l'autenticazione con nome utente/password con Azure.
spring.kafka.properties.azure.credential.username Nome utente da usare quando si esegue l'autenticazione con nome utente/password con Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint Endpoint di Microsoft Entra a cui connettersi.
spring.kafka.properties.azure.profile.tenant-id ID tenant per le risorse di Azure. I valori consentiti per tenant-id sono: common, organizations, consumerso l'ID tenant.

Nota

Le opzioni di configurazione in diversi livelli applicano le regole seguenti. Le opzioni di configurazione più specifiche hanno priorità più alta rispetto a quelle comuni. Per esempio:

  • Le opzioni di configurazione comuni di Spring Kafka sostituisce le opzioni globali.
  • Le opzioni di configurazione del consumer Spring Kafka prevalgono sulle opzioni comuni.
  • Le opzioni di configurazione del producer di Spring Kafka prevalgono sulle opzioni comuni.
  • Le opzioni di configurazione dell'amministratore di Spring Kafka sostituisce le opzioni comuni.
  • Le opzioni Spring Cloud Stream Kafka Binder seguono lo stesso modello.

Proprietà configurabili quando si usa il supporto Kafka con l'autenticazione con stringa di connessione normale

La tabella seguente illustra le opzioni di configurazione comuni di Hub eventi Spring Boot per Kafka:

Proprietà Descrizione
spring.cloud.azure.eventhubs.kafka.enabled Specifica se abilitare il supporto Kafka di Hub eventi di Azure. Il valore predefinito è true.
spring.cloud.azure.eventhubs.connection-string Stringa di connessione di Hub eventi di Azure. Specificare questo valore quando si vuole specificare direttamente la stringa di connessione.
spring.cloud.azure.eventhubs.namespace Spazio dei nomi di Hub eventi Azure. Specificare questo valore quando si desidera recuperare le informazioni di connessione tramite Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group Gruppo di risorse del namespace di Hub eventi di Azure. Specificare questo valore quando si desidera recuperare le informazioni di connessione tramite Azure Resource Manager.
spring.cloud.azure.profile.subscription-id ID sottoscrizione. Specificare questo valore quando si desidera recuperare le informazioni di connessione tramite Azure Resource Manager.

Configurazione delle dipendenze

Aggiungere la dipendenza seguente al progetto. Questa dipendenza include automaticamente la dipendenza spring-boot-starter nel tuo progetto.

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

Nota

Ricorda di aggiungere il BOM spring-cloud-azure-dependencies insieme alla dipendenza indicata sopra. Per informazioni dettagliate, vedere la sezione introduzione della guida per sviluppatori Spring Cloud di Azure.

Utilizzo di base

Le sezioni seguenti illustrano gli scenari di utilizzo dell'applicazione Spring Boot classici.

Usare l'autenticazione OAuth

Quando si usa l'autenticazione OAuth fornita da Spring Cloud Azure per Kafka, è possibile configurare credenziali specifiche usando le configurazioni precedenti. In alternativa, è possibile scegliere di non configurare alcuna credenziale. In questo caso, Spring Cloud Azure carica le credenziali dall'ambiente. Questa sezione descrive come caricare le credenziali dall'ambiente interfaccia della riga di comando di Azure o dall'ambiente di hosting Azure Spring Apps.

Nota

Se si sceglie di usare un'entità di sicurezza per eseguire l'autenticazione e l'autorizzazione con Microsoft Entra ID per accedere a una risorsa Azure, vedere la sezione Autorizzare l'accesso con Microsoft Entra ID per assicurarsi che l'entità di sicurezza disponga di autorizzazioni sufficienti per accedere alla risorsa Azure.

La sezione seguente descrive gli scenari che usano librerie dell'ecosistema Spring diverse con l'autenticazione OAuth.

Supporto delle applicazioni Spring Kafka

Questa sezione descrive lo scenario di utilizzo per un'applicazione Spring Boot che usa Spring Kafka o la libreria Kafka Spring Integration.

Configurazione delle dipendenze
<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>

Aggiornamento della configurazione

Per usare l'autenticazione OAuth, specificare l'endpoint di Hub eventi, come illustrato nell'esempio seguente:

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

Supporto dell'applicazione binder Kafka di Spring Cloud Stream

Questa sezione descrive lo scenario di utilizzo per le applicazioni Spring Boot che usano la libreria Kafka del binder Spring Cloud Stream.

Configurazione delle dipendenze
<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>
Configurazione

Per usare l'autenticazione OAuth, specificare l'endpoint di Hub eventi, come illustrato nell'esempio seguente:

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

Nota

Se si usa la versione 4.3.0, impostare la spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration proprietà per abilitare l'intero flusso di lavoro di autenticazione OAuth. Il kafka-binder-name è kafka per impostazione predefinita in una singola applicazione con binder Kafka. La configurazione AzureKafkaSpringCloudStreamConfiguration specifica i parametri di sicurezza OAuth per KafkaBinderConfigurationProperties. Questa configurazione viene usata in KafkaOAuth2AuthenticateCallbackHandler per abilitare Azure Identity.

Per le versioni successive a 4.4.0, questa proprietà viene aggiunta automaticamente per ogni ambiente del binder di Kafka, quindi non è necessario aggiungerla manualmente.

Usare l'identità gestita per l'autenticazione OAuth

  1. Per usare l'identità gestita, abilitare l'identità gestita per il servizio e assegnare i ruoli Hub eventi di Azure Data Receiver e Hub eventi di Azure Data Sender. Per altre informazioni, vedere Assegnare ruoli di Azure per i diritti di accesso.

  2. Configurare le proprietà seguenti nel file application.yml:

    spring:
  cloud:
    azure:
      credential:
        managed-identity-enabled: true

    Importante

    Se si usa l'identità gestita assegnata dall'utente, aggiungere anche la proprietà spring.cloud.azure.credential.client-id con l'ID client dell'identità gestita assegnata dall'utente.

Campioni

Consulta il repository azure-spring-boot-samples su GitHub.

Usare l'autenticazione della stringa di connessione

È possibile usare direttamente l'autenticazione della stringa di connessione o usare Azure Resource Manager per recuperare la stringa di connessione.

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

Nota

A partire dalla versione 5.0.0, quando si usa l'autenticazione stringa di connessione con spring cloud stream framework, è comunque necessaria la proprietà seguente per assicurarsi che il stringa di connessione funzioni. Il valore di kafka deve essere <kafka-binder-name> se non si personalizza il nome del binder di Kafka: spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Se la versione di spring-cloud-dependencies usata è 2022.0.0, viene rilevata l'eccezione java.lang.IllegalStateException: kafka_context has not been refreshed yet. Per risolvere questo problema, eseguire l'aggiornamento a una versione successiva.

Configurazione delle dipendenze

Aggiungere le dipendenze seguenti se si vuole eseguire la migrazione dell'applicazione Apache Kafka per usare Hub eventi di Azure per Kafka.

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

Per recuperare il stringa di connessione usando Azure Resource Manager, aggiungere la dipendenza seguente:

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

Configurazione

Usa direttamente la stringa di connessione di Event Hubs

Il modo più semplice per connettersi a Hub eventi per Kafka è la stringa di connessione. È sufficiente aggiungere la proprietà seguente.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Usare Azure Resource Manager per recuperare la stringa di connessione

Se non si vuole configurare la stringa di connessione nell'applicazione, è possibile usare Azure Resource Manager per recuperare la stringa di connessione. Per eseguire l'autenticazione con Azure Resource Manager, è anche possibile usare le credenziali archiviate nell'interfaccia della riga di comando di Azure o in un altro strumento di sviluppo locale, ad esempio Visual Studio Code o Intellij IDEA. In alternativa, è possibile usare l'identità gestita se l'applicazione viene distribuita nel cloud di Azure. Assicurarsi che l'entità disponga di autorizzazioni sufficienti per leggere i metadati delle risorse.

Nota

Se si sceglie di usare un'entità di sicurezza per eseguire l'autenticazione e l'autorizzazione con Microsoft Entra ID per accedere a una risorsa Azure, vedere la sezione Autorizzare l'accesso con Microsoft Entra ID per assicurarsi che l'entità di sicurezza disponga di autorizzazioni sufficienti per accedere alla risorsa Azure.

Per usare Azure Resource Manager per recuperare la stringa di connessione, è sufficiente aggiungere la proprietà seguente.

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

Campioni

Consulta il repository azure-spring-boot-samples su GitHub.

  • Ultimo aggiornamento: