Suporte ao Spring Cloud Azure Kafka

  • Aplica-se a: ✅ Version 4.20.0, ✅ Version 5.25.0, ✅ Version 6.5.0, ✅ Version 7.4.0

O suporte do Spring Cloud Azure Kafka ajuda os aplicativos Spring a autenticar e se conectar a Hubs de Eventos do Azure usando credenciais OAuth ou cadeias de conexão. Este artigo descreve os tipos de autenticação, opções de configuração, dependências e cenários de uso com suporte.

Versão do Kafka com suporte

A versão atual do início é compatível com o Apache Kafka Clients 2.0.0 e usa Java 8 ou superior.

Tipos de autenticação com suporte

O início dá suporte aos seguintes tipos de autenticação:

  • Autenticação de cadeia de conexão sem formatação
    • Autenticação de cadeia de conexão direta
    • Autenticação de cadeia de conexão baseada em ARM
  • Autenticação de credencial OAuth
    • Autenticação de identidade gerenciada
    • Autenticação de nome de usuário/senha
    • Autenticação da entidade de serviço
    • autenticação DefaultAzureCredential

Como funciona

Autenticação de credencial OAuth

Esta seção descreve o fluxo de trabalho geral da autenticação OAuth do Spring Cloud Azure.

O Spring Cloud Azure primeiro cria um dos seguintes tipos de credenciais, dependendo da configuração de autenticação do aplicativo:

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Se o aplicativo não usar um desses tipos de credenciais, o aplicativo usará a cadeia de credenciais para DefaultAzureTokenCredential obter credenciais de propriedades de aplicativo, variáveis de ambiente, identidade gerenciada ou IDEs. Para obter informações detalhadas, consulte de autenticação do Spring Cloud Azure.

Autenticação de cadeia de conexão sem formatação

Para o modo de autenticação de cadeia de conexão, você pode usar a autenticação de cadeia de conexão diretamente ou usar o Azure Resource Manager para recuperar a cadeia de conexão. Para obter mais informações sobre o uso, consulte a seção Uso básico para autenticação de cadeia de conexão.

Nota

Desde a versão 4.3.0, a autenticação cadeia de conexão é preterida em favor da autenticação OAuth.

Configuração

Propriedades configuráveis ao usar o suporte do Kafka com a autenticação OAuth

O Spring Cloud Azure para Kafka dá suporte aos dois níveis de opções de configuração a seguir:

  1. Propriedades kafka do Spring Cloud Azure para Hubs de Eventos.
  2. As opções de configuração de autenticação global de credential e profile com prefixos de spring.cloud.azure.
  3. Configurações de nível específicas do Kafka. As configurações no nível do Kafka também estão disponíveis para associadores spring boot e spring cloud stream para escopos de common, consumer, producerou admin, que têm prefixos diferentes.

As propriedades globais são expostas por meio de com.azure.spring.cloud.autoconfigure.context.AzureGlobalProperties. As propriedades específicas do Kafka são expostas por meio de org.springframework.boot.autoconfigure.kafka.KafkaProperties (Spring Boot) e org.springframework.cloud.stream.binder.kafka.properties.KafkaBinderConfigurationProperties (associador spring cloud stream).

A lista a seguir mostra todas as opções de configuração com suporte.

  • Propriedades kafka do Spring Cloud Azure para Hubs de Eventos.

    • Propriedade: spring.cloud.azure.eventhubs.kafka.enabled
    • Descrição: se para habilitar a conexão gratuita de credenciais com os Hubs de Eventos do Azure para Kafka, o valor padrão é true.

  • As opções de configuração de autenticação global do Spring Cloud Azure

    • Prefixo: spring.cloud.azure
    • Opções com suporte: spring.cloud.azure.credential.*, spring.cloud.azure.profile.*

    Para obter a lista completa de opções de configuração global, consulte Propriedades de configuração global.

  • Configuração comum do Kafka do Spring Boot

    • Prefixo: spring.kafka.properties.azure
    • Exemplo: spring.kafka.properties.azure.credential.*

  • Opções de configuração do consumidor do Spring Kafka

    • Prefixo: spring.kafka.consumer.properties.azure
    • Exemplo: spring.kafka.consumer.properties.azure.credential.*

  • Opções de configuração do produtor do Spring Kafka

    • Prefixo: spring.kafka.producer.properties.azure
    • Exemplo: spring.kafka.producer.properties.azure.credential.*

  • Opções de configuração de administrador do Spring Kafka

    • Prefixo: spring.kafka.admin.properties.azure
    • Exemplo: spring.kafka.admin.properties.azure.credential.*

  • Configuração comum do Spring Cloud Stream Kafka Binder

    • Prefixo: spring.cloud.stream.kafka.binder.configuration.azure
    • Exemplo: spring.cloud.stream.kafka.binder.configuration.azure.credential.*

  • Configuração do consumidor do Spring Cloud Stream Kafka Binder

    • Prefixo: spring.cloud.stream.kafka.binder.consumer-properties.azure
    • Exemplo: spring.cloud.stream.kafka.binder.consumer-properties.azure.credential.*

  • Configuração do produtor do Spring Cloud Stream Kafka Binder

    • Prefixo: spring.cloud.stream.kafka.binder.producer-properties.azure
    • Exemplo: spring.cloud.stream.kafka.binder.producer-properties.azure.credential.*

  • Configuração de administrador do Spring Cloud Stream Kafka Binder

    • Prefixo: sem suporte, use a configuração comum ou de administrador do Kafka do Spring Boot.

A tabela a seguir mostra as opções de configuração comuns do Kafka do Spring Boot:

Nome Descrição
spring.kafka.properties.azure.credential.client-certificate-password Senha do arquivo de certificado.
spring.kafka.properties.azure.credential.client-certificate-path Caminho de um arquivo de certificado PEM a ser usado ao executar a autenticação da entidade de serviço com o Azure.
spring.kafka.properties.azure.credential.client-id ID do cliente a ser usada ao executar a autenticação da entidade de serviço com o Azure. Esta é uma propriedade herdada.
spring.kafka.properties.azure.credential.client-secret Segredo do cliente a ser usado ao executar a autenticação da entidade de serviço com o Azure. Esta é uma propriedade herdada.
spring.kafka.properties.azure.credential.managed-identity-enabled Se deseja habilitar a identidade gerenciada para autenticar com o Azure. Se true e o client-id estiver definido, a ID do cliente será a ID do cliente de identidade gerenciada atribuída pelo usuário. O valor padrão é false.
spring.kafka.properties.azure.credential.password Senha a ser usada ao executar a autenticação de nome de usuário/senha com o Azure.
spring.kafka.properties.azure.credential.username Nome de usuário a ser usado ao executar a autenticação de nome de usuário/senha com o Azure.
spring.kafka.properties.azure.profile.environment.active-directory-endpoint O ponto de extremidade do Microsoft Entra ao qual se conectar.
spring.kafka.properties.azure.profile.tenant-id ID do locatário para recursos do Azure. Os valores permitidos para tenant-id são: common, organizations, consumersou a ID do locatário.

Nota

As opções de configuração em diferentes níveis aplicam as regras a seguir. As opções de configuração mais específicas têm prioridade maior do que as comuns. Por exemplo:

  • As opções de configuração comuns do Spring Kafka substituem as opções globais.
  • As opções de configuração do consumidor do Spring Kafka substituem as opções comuns.
  • As opções de configuração do produtor do Spring Kafka substituem as opções comuns.
  • As opções de configuração de administrador do Spring Kafka substituem as opções comuns.
  • As opções do Spring Cloud Stream Kafka Binder seguem o mesmo padrão.

Propriedades configuráveis ao usar o suporte do Kafka com autenticação de cadeia de conexão simples

A tabela a seguir mostra as opções de configuração comuns dos Hubs de Eventos do Spring Boot para Kafka:

Propriedade Descrição
spring.cloud.azure.eventhubs.kafka.enabled Se deseja habilitar o suporte ao Kafka dos Hubs de Eventos do Azure. O valor padrão é true.
spring.cloud.azure.eventhubs.connection-string Cadeia de conexão dos Hubs de Eventos do Azure. Forneça esse valor quando quiser fornecer a cadeia de conexão diretamente.
spring.cloud.azure.eventhubs.namespace Namespace dos Hubs de Eventos do Azure. Forneça esse valor quando quiser recuperar as informações de conexão por meio do Azure Resource Manager.
spring.cloud.azure.eventhubs.resource.resource-group O grupo de recursos do namespace dos Hubs de Eventos do Azure. Forneça esse valor quando quiser recuperar as informações de conexão por meio do Azure Resource Manager.
spring.cloud.azure.profile.subscription-id A ID da assinatura. Forneça esse valor quando quiser recuperar as informações de conexão por meio do Azure Resource Manager.

Configuração de dependência

Adicione a dependência a seguir ao seu projeto. Essa dependência inclui automaticamente a spring-boot-starter dependência em seu projeto.

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

Nota

Lembre-se de adicionar o BOM spring-cloud-azure-dependencies junto com a dependência anterior. Para obter detalhes, consulte a seção Introdução do guia de desenvolvedor do Spring Cloud Azure.

Uso básico

As seções a seguir mostram os cenários clássicos de uso do aplicativo Spring Boot.

Usar a autenticação OAuth

Ao usar a autenticação OAuth que o Spring Cloud Azure fornece para o Kafka, você pode configurar credenciais específicas usando as configurações anteriores. Como alternativa, você pode optar por não configurar nenhuma credencial. Nesse caso, o Spring Cloud Azure carrega as credenciais do ambiente. Esta seção descreve como carregar credenciais do ambiente de CLI do Azure ou do ambiente de hospedagem Aplicativos Spring do Azure.

Nota

Se você optar por usar uma entidade de segurança para autenticar e autorizar com Microsoft Entra ID para acessar um recurso de Azure, consulte a seção Autorizar acesso com Microsoft Entra ID para garantir que a entidade de segurança tenha permissão suficiente para acessar o recurso Azure.

A seção a seguir descreve cenários que usam diferentes bibliotecas de ecossistema do Spring com autenticação OAuth.

Suporte ao aplicativo Spring Kafka

Esta seção descreve o cenário de uso de um aplicativo Spring Boot que usa o Spring Kafka ou a biblioteca Kafka do Spring Integration.

Configuração de dependência
<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>

Atualização de configuração

Para usar a autenticação OAuth, especifique o ponto de extremidade dos Hubs de Eventos, conforme mostrado no exemplo a seguir:

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

Suporte ao aplicativo Kafka do associador do Spring Cloud Stream

Esta seção descreve o cenário de uso para aplicativos Spring Boot que usam a biblioteca Kafka do associador spring cloud stream.

Configuração de dependência
<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>
Configuração

Para usar a autenticação OAuth, especifique o ponto de extremidade dos Hubs de Eventos, conforme mostrado no exemplo a seguir:

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

Nota

Se você estiver usando a versão 4.3.0, defina a spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration propriedade para habilitar todo o fluxo de trabalho de autenticação OAuth. A kafka-binder-name opção é kafka , por padrão, em um único aplicativo associador Kafka. A configuração AzureKafkaSpringCloudStreamConfiguration especifica os parâmetros de segurança OAuth para KafkaBinderConfigurationProperties. Essa configuração é usada KafkaOAuth2AuthenticateCallbackHandler para habilitar Azure Identity.

Para versões depois 4.4.0, essa propriedade é adicionada automaticamente para cada ambiente associador kafka, portanto, você não precisa adicioná-la manualmente.

Usar a identidade gerenciada para autenticação OAuth

  1. Para usar a identidade gerenciada, habilite a identidade gerenciada para seu serviço e atribua as funções e Hubs de Eventos do Azure Data Sender as Hubs de Eventos do Azure Data Receiver funções. Para obter mais informações, consulte Atribuir funções do Azure para direitos de acesso.

  2. Configure as seguintes propriedades em seu arquivo de application.yml:

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

    Importante

    Se você estiver usando a identidade gerenciada atribuída pelo usuário, adicione também a propriedade spring.cloud.azure.credential.client-id com a ID do cliente de identidade gerenciada atribuída pelo usuário.

Amostras

Consulte o azure-spring-boot-samples repositório no GitHub.

Usar autenticação de cadeia de conexão

Você pode usar a autenticação de cadeia de conexão diretamente ou usar o Azure Resource Manager para recuperar a cadeia de conexão.

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

Nota

Desde a versão 5.0.0, ao usar cadeia de conexão autenticação com a estrutura do Spring Cloud Stream, você ainda precisa da propriedade a seguir para garantir que o cadeia de conexão funcione. O valor deve ser kafka se você não personalizar o nome do <kafka-binder-name> associador kafka:spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.implementation.eventhubs.kafka.AzureEventHubsKafkaAutoConfiguration

Se a versão de spring-cloud-dependencies você usar for 2022.0.0, você encontrará a exceção java.lang.IllegalStateException: kafka_context has not been refreshed yet. Para resolver esse problema, atualize para uma versão mais alta.

Configuração de dependência

Adicione as dependências a seguir se você quiser migrar seu aplicativo Apache Kafka para usar os Hubs de Eventos do Azure para Kafka.

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

Se você quiser recuperar o cadeia de conexão usando Azure Resource Manager, adicione a seguinte dependência:

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

Configuração

Usar a cadeia de conexão dos Hubs de Eventos diretamente

A maneira mais simples de se conectar aos Hubs de Eventos para Kafka é com a cadeia de conexão. Basta adicionar a propriedade a seguir.

spring.cloud.azure.eventhubs.connection-string=${AZURE_EVENTHUBS_CONNECTION_STRING}
Usar o Azure Resource Manager para recuperar a cadeia de conexão

Se você não quiser configurar a cadeia de conexão em seu aplicativo, poderá usar o Azure Resource Manager para recuperar a cadeia de conexão. Para autenticar com o Azure Resource Manager, você também pode usar credenciais armazenadas na CLI do Azure ou em outra ferramenta de desenvolvimento local, como o Visual Studio Code ou o Intellij IDEA. Como alternativa, você pode usar a Identidade Gerenciada se o aplicativo for implantado no Azure Cloud. Apenas verifique se a entidade de segurança tem permissão suficiente para ler metadados de recurso.

Nota

Se você optar por usar uma entidade de segurança para autenticar e autorizar com Microsoft Entra ID para acessar um recurso de Azure, consulte a seção Autorizar acesso com Microsoft Entra ID para garantir que a entidade de segurança tenha permissão suficiente para acessar o recurso Azure.

Para usar o Azure Resource Manager para recuperar a cadeia de conexão, basta adicionar a propriedade a seguir.

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

Amostras

Consulte o azure-spring-boot-samples repositório no GitHub.

  • Last updated on