Condividi tramite

Supporto di Spring Cloud Azure Kafka

  • Articolo

Questo articolo si applica a: ✔️ Versione 4.14.0 ✔️ versione 5.8.0

Dalla versione 4.3.0, Spring Cloud Azure per Kafka supporta vari tipi di credenziali per l'autenticazione e la connessione a Hub eventi di Azure.

Versione di Kafka supportata

La versione corrente dello starter deve essere compatibile con i client Apache Kafka 2.0.0 con Java 8 o versione successiva.

Tipi di autenticazione supportati

I seguenti tipi di autenticazione non sono supportati:

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

Funzionamento

Autenticazione delle credenziali OAuth

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

Spring Cloud Azure creerà prima di tutto uno dei tipi di credenziali seguenti a seconda della configurazione di autenticazione dell'applicazione:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Se nessuno di questi tipi di credenziali viene trovato, la catena di credenziali tramite DefaultAzureTokenCredential verrà usata 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 in Azure.

Autenticazione di stringa di connessione normale

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

Nota

A partire dalla versione 4.3.0, stringa di connessione'autenticazione è deprecata a favore delle autenticazioni OAuth.

Impostazione

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. Opzioni di configurazione dell'autenticazione globale di credential e profile con prefissi di spring.cloud.azure.
  3. Configurazioni di livello specifiche di Kafka. Le configurazioni a livello di Kafka sono disponibili anche per i binder Spring Boot e Spring Cloud Stream per commonambiti , consumerproducer, o admin con 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 Hub eventi.

    • 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 globali.

  • Configurazione comune di Spring Boot Kafka

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

  • Opzioni di configurazione del consumer Spring Kafka

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

  • Opzioni di configurazione del producer 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 producer Kafka Binder di 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, deve usare la configurazione comune o amministratore 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 usare quando si esegue l'autenticazione dell'entità servizio con Azure. Si tratta di una proprietà legacy.
spring.kafka.properties.azure.credential.client-secret Segreto client da usare quando si esegue l'autenticazione dell'entità servizio con Azure. Si tratta di una proprietà legacy.
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, userà l'ID client come ID client dell'identità gestita assegnato 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. Ad esempio:

  • Le opzioni di configurazione comuni di Spring Kafka sostituisce le opzioni globali.
  • Le opzioni di configurazione del consumer Spring Kafka sostituisce le opzioni comuni.
  • Le opzioni di configurazione del producer Spring Kafka sostituisce le opzioni comuni.
  • Le opzioni di configurazione dell'amministratore di Spring Kafka sostituisce le opzioni comuni.
  • Le opzioni Spring Cloud Stream Kafka Binder sono simili a quanto sopra.

Proprietà configurabili quando si usa il supporto kafka con l'autenticazione di 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 Indica se abilitare il supporto Hub eventi di Azure Kafka. Il valore predefinito è true.
spring.cloud.azure.eventhubs.connection-string Hub eventi di Azure stringa di connessione. Specificare questo valore quando si vuole specificare direttamente il stringa di connessione.
spring.cloud.azure.eventhubs.namespace Hub eventi di Azure spazio dei nomi. 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 dello spazio dei nomi 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 della 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. Ciò includerà automaticamente la spring-boot-starter dipendenza nel progetto in modo transitivo.

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

Nota

Ricordarsi di aggiungere la distinta base spring-cloud-azure-dependencies insieme alla dipendenza precedente. Per informazioni dettagliate, vedere la sezione Introduzione della Guida per sviluppatori di Spring Cloud 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 le credenziali specifiche usando le configurazioni precedenti. In alternativa, è possibile scegliere di configurare nulla sulle credenziali, nel qual caso Spring Cloud Azure caricherà le credenziali dall'ambiente. Questa sezione descrive gli utilizzi che caricano le credenziali dall'ambiente dell'interfaccia della riga di comando di Azure o dall'ambiente di hosting di Azure Spring Apps.

Nota

Se si sceglie di usare un'entità di sicurezza per autenticare e autorizzare con Microsoft Entra ID per l'accesso a una risorsa di Azure, vedere la sezione Autorizzare l'accesso con Microsoft Entra ID per assicurarsi che all'entità di sicurezza sia stata concessa l'autorizzazione sufficiente per accedere alla risorsa di 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 l'applicazione Spring Boot usando la libreria Spring Kafka o Spring Integration Kafka.

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 solo l'endpoint di Hub eventi, come illustrato nell'esempio seguente:

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

Supporto dell'applicazione Kafka per lo strumento di associazione 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>
Impostazione

Per usare l'autenticazione OAuth, è sufficiente 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, non dimenticare di 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, dove kafka-binder-name è kafka per impostazione predefinita in una singola applicazione di associazione Kafka. La configurazione AzureKafkaSpringCloudStreamConfiguration specifica i parametri di sicurezza OAuth per KafkaBinderConfigurationProperties, che viene usato in KafkaOAuth2AuthenticateCallbackHandler per abilitare l'identità di Azure.

Per la versione successiva 4.4.0a , questa proprietà verrà aggiunta automaticamente per ogni ambiente di associazione Kafka, quindi non è necessario aggiungerla manualmente.

Esempi

Vedere il repository azure-spring-boot-samples in GitHub.

Usare l'autenticazione stringa di connessione

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

Nota

A partire dalla versione 4.3.0, stringa di connessione'autenticazione è deprecata a favore delle autenticazioni OAuth.

Dalla versione 4.5.0, quando si usa l'autenticazione stringa di connessione con il framework Spring Cloud Stream, è necessaria la proprietà seguente per assicurarsi che l'stringa di connessione possa essere effettiva, in cui il valore di <kafka-binder-name> deve essere kafka quando non è disponibile alcuna configurazione personalizzata per il nome del gestore di associazione Kafka.

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

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>

Se si vuole 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>

Impostazione

Usare direttamente Hub eventi stringa di connessione

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

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

Se non si vuole configurare il stringa di connessione nell'applicazione, è possibile usare Azure Resource Manager per recuperare il 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 l'accesso a una risorsa di Azure, vedere la sezione Autorizzare l'accesso con Microsoft Entra ID per assicurarsi che all'entità di sicurezza sia stata concessa l'autorizzazione sufficiente per accedere alla risorsa di Azure.

Per usare Azure Resource Manager per recuperare il 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}

Esempi

Vedere il repository azure-spring-boot-samples in GitHub.