Partilhar via

Suporte do Spring Cloud Azure Kafka

  • Artigo

Este artigo aplica-se a:✅ Versão 4.19.0 ✅ Versão 5.18.0

A partir da versão 4.3.0, o Spring Cloud Azure para Kafka dá suporte a vários tipos de credenciais para autenticar e se conectar aos Hubs de Eventos do Azure.

Versão Kafka suportada

A versão atual do starter deve ser compatível com Apache Kafka Clients 2.0.0 usando Java 8 ou superior.

Tipos de autenticação suportados

Os seguintes tipos de autenticação são suportados:

  • Autenticação de cadeia de conexão simples
    • Autenticação direta da cadeia de conexão
    • Autenticação de cadeia de conexão baseada em ARM
  • Autenticação de credenciais OAuth
    • Autenticação de identidade gerenciada
    • Autenticação de nome de utilizador/palavra-passe
    • Autenticação da entidade de serviço
    • DefaultAzureCredential autenticação

Como funciona

Autenticação de credenciais OAuth

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

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

  • ClientSecretCredential
  • ClientCertificateCredential
  • UsernamePasswordCredential
  • ManagedIdentityCredential

Se nenhum desses tipos de credenciais for encontrado, a cadeia de credenciais via DefaultAzureTokenCredential será usada para obter credenciais de propriedades de aplicativos, variáveis de ambiente, identidade gerenciada ou IDEs. Para obter informações detalhadas, consulte Spring Cloud Azure authentication.

Autenticação de cadeia de conexão simples

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 Gerenciador de Recursos do Azure 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.

Observação

Desde a versão 4.3.0, a autenticação de cadeia de conexão foi preterida em favor das autenticações OAuth.

Configuração

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

O Spring Cloud Azure para Kafka suporta os seguintes dois níveis de opções de configuração:

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

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

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

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

    • Imóvel: spring.cloud.azure.eventhubs.kafka.enabled
    • Descrição: se deve habilitar a conexão sem credenciais aos 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 suportadas: 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 Spring Boot Kafka

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

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

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

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

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

  • Opções de configuração do 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 administrativa do Spring Cloud Stream Kafka Binder

    • Prefixo: Não suportado, deve usar Spring Boot Kafka configuração comum ou admin.

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

Designação 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 legada.
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 legada.
spring.kafka.properties.azure.credential.managed-identity-enabled Se a identidade gerenciada deve ser habilitada para autenticação com o Azure. Se verdadeiro e o client-id estiver definido, usará o ID do cliente como ID do cliente de identidade gerenciada atribuído ao 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 o ID do locatário.

Observação

As opções de configuração em diferentes níveis aplicam as seguintes regras. As opções de configuração mais específicas têm maior prioridade 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 Spring Kafka substituem as opções comuns.
  • As opções de configuração do produtor Spring Kafka substituem as opções comuns.
  • As opções de configuração de administração do Spring Kafka substituem as opções comuns.
  • As opções do Spring Cloud Stream Kafka Binder são exatamente como as acima.

Propriedades configuráveis ao usar o suporte a 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 o suporte ao Azure Event Hubs Kafka deve ser habilitado. 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 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 O ID da subscrição. 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 seguinte dependência ao seu projeto. Isso incluirá automaticamente a dependência spring-boot-starter em seu projeto transitivamente.

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

Observação

Lembre-se de adicionar a lista técnica spring-cloud-azure-dependencies juntamente com a dependência acima. Para obter detalhes, consulte a seção Introdução do guia do desenvolvedor do Spring Cloud Azure.

Utilização básica

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

Usar autenticação OAuth

Ao usar a autenticação OAuth fornecida pelo Spring Cloud Azure para Kafka, você pode configurar as credenciais específicas usando as configurações acima. Como alternativa, você pode optar por não configurar nada sobre credenciais, caso em que o Spring Cloud Azure carregará as credenciais do ambiente. Esta seção descreve os usos que carregam as credenciais do ambiente da CLI do Azure ou do ambiente de hospedagem do Azure Spring Apps.

Observação

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

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

Suporte à aplicação Spring Kafka

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

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, basta especificar 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 Spring Cloud Stream binder Kafka

Esta seção descreve o cenário de uso para aplicativos Spring Boot usando a biblioteca Kafka do fichário do 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, basta especificar 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

Observação

Se você estiver usando a versão 4.3.0, não se esqueça de definir a propriedade spring.cloud.stream.binders.<kafka-binder-name>.environment.spring.main.sources=com.azure.spring.cloud.autoconfigure.kafka.AzureKafkaSpringCloudStreamConfiguration para habilitar todo o fluxo de trabalho de autenticação OAuth, onde kafka-binder-name é kafka por padrão em um único aplicativo de fichário Kafka. O AzureKafkaSpringCloudStreamConfiguration de configuração especifica os parâmetros de segurança OAuth para KafkaBinderConfigurationProperties, que é usado em KafkaOAuth2AuthenticateCallbackHandler para habilitar a Identidade do Azure.

Para a versão após 4.4.0, essa propriedade será adicionada automaticamente para cada ambiente de fichário Kafka, portanto, não há necessidade de adicioná-la manualmente.

Usar identidade gerenciada para autenticação OAuth

  1. Para usar a identidade gerenciada, você precisa habilitar a identidade gerenciada para seu serviço e atribuir as funções Azure Event Hubs Data Receiver e Azure Event Hubs Data Sender. Para obter mais informações, consulte Atribuir funções do Azure para direitos de acesso.

  2. Configure as seguintes propriedades no arquivo application.yml:

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

    Importante

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

Amostras

Consulte o repositório azure-spring-boot-samples 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 Gerenciador de Recursos do Azure para recuperar a cadeia de conexão.

Observação

Desde a versão 5.0.0, ao usar a autenticação de cadeia de conexão com a estrutura do Spring Cloud Stream, a seguinte propriedade ainda é necessária para garantir que a cadeia de conexão possa entrar em vigor, onde o valor de <kafka-binder-name> deve ser kafka quando não houver nenhuma configuração personalizada para o nome do fichário 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 do spring-cloud-dependencies que você usou for 2022.0.0, você encontrará exceção no java.lang.IllegalStateException: kafka_context has not been refreshed yet. Para resolver esse problema, atualize para uma versão superior.

Configuração de dependência

Adicione as seguintes dependências se 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 a cadeia de conexão usando o Gerenciador de Recursos do Azure, 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 seguinte propriedade.

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

Se não quiser configurar a cadeia de conexão em seu aplicativo, você pode 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 Visual Studio Code ou Intellij IDEA. Como alternativa, você pode usar a Identidade Gerenciada se seu aplicativo for implantado na Nuvem do Azure. Apenas certifique-se de que a entidade de segurança tenha permissão suficiente para ler metadados de recursos.

Observação

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

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

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

Amostras

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