Share via


Conectar o conector de nuvem da ponte MQTT da versão prévia do Azure IoT MQ a outros agentes do MQTT

Importante

O recurso Pré-visualização de Operações do Azure IoT — habilitado pelo Azure Arc — está atualmente em VERSÃO PRÉVIA. Você não deve usar esse software em versão prévia em ambientes de produção.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Você pode usar a ponte MQTT da versão prévia do Azure IoT MQ para se conectar à Grade de Eventos do Azure ou a outros agentes do MQTT. A ponte MQTT é o processo de conexão de dois agentes MQTT para que eles possam trocar mensagens.

  • Quando dois agentes são conectados, as mensagens publicadas em um agente são encaminhadas automaticamente para o outro e vice-versa.
  • A ponte MQTT ajuda a criar uma rede de agentes MQTT que se comunicam entre si e expandem a infraestrutura do MQTT incluindo agentes adicionais conforme necessário.
  • A ponte MQTT é útil para vários locais físicos, compartilhar tópicos e mensagens MQTT entre borda e a nuvem ou quando quiser integrar o MQTT a outros sistemas de mensagens.

Para fazer a ponte para outro agente, o Azure IoT MQ deve saber o URL do ponto de extremidade do agente remoto, qual versão do MQTT, como autenticar e quais tópicos mapear. Para maximizar a modularidade e a flexibilidade de uma forma nativa do Kubernetes, esses valores são configurados como recursos personalizados do Kubernetes (CRDs) chamados MqttBridgeConnector e MqttBridgeTopicMap. Esse guia explica como criar o conector de ponte MQTT usando esses recursos.

  1. Crie um arquivo YAML que defina recurso de MqttBridgeConnector. Você pode usar o YAML de exemplo, mas certifique-se de alterar o namespace para corresponder ao que tem o Azure IoT MQ implantado e o remoteBrokerConnection.endpoint para corresponder ao URL do ponto de extremidade do agente remoto.

  2. Crie um arquivo YAML que defina recurso de MqttBridgeTopicMap. Você pode usar o YAML de exemplo, mas certifique-se de alterar o namespace para corresponder ao que tem o Azure IoT MQ implantado e o mqttBridgeConnectorRef para corresponder ao nome do recurso de MqttBridgeConnector criado na etapa anterior.

  3. Implante o conector de ponte MQTT e o mapa de tópicos com kubectl apply -f <filename>.

    $ kubectl apply -f my-mqtt-bridge.yaml 
    mqttbridgeconnectors.mq.iotoperations.azure.com my-mqtt-bridge created
    $ kubectl apply -f my-topic-map.yaml
    mqttbridgetopicmaps.mq.iotoperations.azure.com my-topic-map created
    

Depois de implantado, use kubectl get pods para verificar se as mensagens começam a fluir de e para o ponto de extremidade.

Configure MqttBridgeConnector

O recurso de MqttBridgeConnector define o conector de ponte MQTT que pode se comunicar com um agente remoto. Inclui os seguintes componentes:

  • Uma ou mais instâncias do conector de ponte MQTT. Cada instância é um contêiner que executa o conector de ponte MQTT.
  • Uma conexão do agente remoto.
  • Uma conexão do agente local opcional.

O exemplo a seguir mostra uma configuração de exemplo para a ponte para um agente MQTT da Grade de Eventos do Azure. Ele usa a identidade gerenciada atribuída pelo sistema para autenticação e criptografia TLS.

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: MqttBridgeConnector
metadata:
  name: my-mqtt-bridge
  namespace: azure-iot-operations
spec:
  image: 
    repository: mcr.microsoft.com/azureiotoperations/mqttbridge 
    tag: 0.4.0-preview
    pullPolicy: IfNotPresent
  protocol: v5
  bridgeInstances: 1
  clientIdPrefix: factory-gateway-
  logLevel: debug
  remoteBrokerConnection:
    endpoint: example.westeurope-1.ts.eventgrid.azure.net:8883
    tls:
      tlsEnabled: true
    authentication:
      systemAssignedManagedIdentity:
        audience: https://eventgrid.azure.net
  localBrokerConnection:
    endpoint: aio-mq-dmqtt-frontend:8883
    tls:
      tlsEnabled: true
      trustedCaCertificateConfigMap: aio-ca-trust-bundle-test-only
    authentication:
      kubernetes: {}

A tabela a seguir descreve os campos no recurso de MqttBridgeConnector:

Campo Obrigatório Descrição
imagem Sim A imagem do conector do Kafka. Você pode especificar pullPolicy, repository e tag da imagem. Os valores adequados são mostrados no exemplo anterior.
protocolo Sim Versão do protocolo MQTT. Pode ser v5 ou v3. Consulte suporte do MQTT v3.1.1.
bridgeInstances Não Número de instâncias para o conector de ponte. O padrão é UTF-1. Consulte o Número de instâncias.
clientIdPrefix Não O prefixo da ID do cliente gerada dinamicamente. O padrão é não ter prefixo. Consulte a Configuração da ID do cliente.
logLevel Não Nível do log. Pode ser debug ou info. O padrão é info.
remoteBrokerConnection Sim Detalhes de conexão do agente remoto para o qual fazer a ponte. Consulte a Conexão do agente remoto.
localBrokerConnection Não Detalhes da conexão do agente local para o qual fazer a ponte. Usa como padrão o valor mostrado. Consulte a Conexão de agente local.

Suporte do MQTT v3.1.1

O conector de ponte pode ser configurado para usar o MQTT v3.1.1 com a conexão do agente local para o Azure IoT MQ e para a conexão do agente remoto. No entanto, isso interromperá as assinaturas compartilhadas se o agente remoto não der suporte a ela. Se você planeja usar assinaturas compartilhadas, deixe v5 como padrão.

Número de instâncias

Para alta disponibilidade e escala, configure o conector de ponte MQTT para usar várias instâncias. O fluxo de mensagens e as rotas são balanceados automaticamente entre instâncias diferentes.

spec:
  bridgeInstances: 2

Configuração da ID do cliente

O Azure IoT MQ gera uma ID do cliente para cada cliente MqttBridgeConnector, usando um prefixo que você especifica, no formato de {clientIdPrefix}-{routeName}. Essa ID do cliente é importante para o Azure IoT MQ reduzir a perda de mensagens e evitar conflitos ou colisões com IDs de cliente existentes, pois a especificação do MQTT permite apenas uma conexão por ID do cliente.

Por exemplo, se clientIdPrefix: "client-", e houver duas routes no mapa de tópicos, as IDs do cliente serão: client-route1 e client-route2.

Conexão do agente remoto

O campo remoteBrokerConnection define os detalhes da conexão para fazer a ponte para o agente remoto. Ela inclui os seguintes campos:

Campo Obrigatório Descrição
endpoint Sim URL do ponto de extremidade do agente remoto com porta. Por exemplo, example.westeurope-1.ts.eventgrid.azure.net:8883.
tls Sim Especifica se a conexão é criptografada com TLS e possui certificado de autoridade de certificação (AC) confiável. Confira Suporte ao TLS
autenticação Sim Detalhes de autenticação do Azure IoT MQ a serem usados com o agente. Deve ser um dos seguintes valores: identidade gerenciada atribuída pelo sistema ou X.509. Consulte Autenticação.
protocolo Não Valor da cadeia de caracteres definindo para usar MQTT ou MQTT em WebSockets. Pode ser mqtt ou webSocket. O padrão é mqtt.

Autenticação

O campo de autenticação define o método de autenticação para o Azure IoT MQ a ser usado com o agente remoto. Ela inclui os seguintes campos:

Campo Obrigatório Descrição
systemAssignedManagedIdentity Não Autenticar com a identidade gerenciada atribuída pelo sistema. Consulte Identidade gerenciada.
x509 Não Detalhes da autenticação usando certificados X.509. Consulte X.509.

Identidade gerenciada

O campo systemAssignedManagedIdentity inclui os seguintes campos:

Campo Obrigatório Descrição
audience Sim O público-alvo do token. Obrigatório se estiver usando a identidade gerenciada. Para a Grade de Eventos, é https://eventgrid.azure.net.

Se o Azure IoT MQ for implantado como uma extensão do Azure Arc, ele obterá uma identidade gerenciada atribuída pelo sistema por padrão. Você deve usar uma identidade gerenciada para o Azure IoT MQ para interagir com os recursos do Azure, incluindo o agente MQTT da Grade de Eventos, pois ele permite que você evite o gerenciamento de credenciais e mantenha a alta disponibilidade.

Para usar a identidade gerenciada para autenticação com recursos do Azure, primeiro atribua uma função RBAC apropriada do Azure, como Distribuidor de TopicSpaces do EventGrid à identidade gerenciada do Azure IoT MQ fornecida pelo Arc.

Em seguida, especifique e MQTTBridgeConnector com a identidade gerenciada como o método de autenticação:

spec:
  remoteBrokerConnection:
    authentication:
      systemAssignedManagedIdentity:
        audience: https://eventgrid.azure.net

Quando você usa a identidade gerenciada, a ID do cliente não é configurável e equivale à ID do recurso do Azure Resource Manager da extensão do Azure Arc do Azure IoT MQ dentro Azure.

A identidade gerenciada atribuída pelo sistema é fornecida pelo Azure Arc. O certificado associado à identidade gerenciada deve ser renovado pelo menos a cada 90 dias para evitar um processo de recuperação manual. Para saber mais, confira Como fazer para resolver recursos expirados do Kubernetes habilitados para o Azure Arc?

X.509

O campo x509 inclui os seguintes campos:

Campo Obrigatório Descrição
secretName Sim O segredo do Kubernetes que contém o certificado do cliente e a chave privada. Você pode usar o Azure Key Vault para gerenciar segredos do Azure IoT MQ em vez de segredos do Kubernetes. Para saber mais, consulte Gerenciar segredos usando o Azure Key Vault ou segredos do Kubernetes.

Muitos agentes MQTT, como a Grade de Eventos, dão suporte à autenticação X.509. A ponte MQTT do Azure IoT MQ pode apresentar um certificado X.509 do cliente e negociar a comunicação TLS. Use um segredo do Kubernetes para armazenar o certificado de cliente X.509, a chave privada e a AC intermediária.

kubectl create secret generic bridge-client-secret \
--from-file=client_cert.pem=mqttbridge.pem \
--from-file=client_key.pem=mqttbridge.key \
--from-file=client_intermediate_certs.pem=intermediate.pem

E faça referência a ele com secretName:

spec:
  remoteBrokerConnection:
    authentication:
      x509:
        secretName: bridge-client-cert

Conexão de agente local

O campo localBrokerConnection define os detalhes da conexão para fazer a ponte para o agente local.

Campo Obrigatório Descrição
endpoint Sim URL do ponto de extremidade do agente remoto com porta.
tls Sim Especifica se a conexão é criptografada com TLS e possui certificado de autoridade de certificação (AC) confiável. Confira Suporte ao TLS
autenticação Sim Detalhes de autenticação do Azure IoT MQ a serem usados com o agente. O único método com suporte é o SAT (token de conta de serviço) do Kubernetes. Para usar o SAT, especifique kubernetes: {}.

Por padrão, o IoT MQ é implantado no namespace azure-iot-operations com TLS habilitado e autenticação SAT.

Em seguida, a configuração de conexão do agente local de MqttBridgeConnector deve ser configurada para corresponder. O YAML de implantação do MqttBridgeConnector deve ter localBrokerConnection no mesmo nível que remoteBrokerConnection. Por exemplo, para usar o TLS com a autenticação SAT para corresponder à implantação padrão do IoT MQ:

spec:
  localBrokerConnection:
    endpoint: aio-mq-dmqtt-frontend:8883
    tls:
      tlsEnabled: true
      trustedCaCertificateConfigMap: aio-ca-trust-bundle-test-only
    authentication:
      kubernetes: {}

Aqui, trustedCaCertifcateName é o ConfigMap para a AC raiz do Azure IoT MQ, como o ConfigMap para a AC raiz do agente remoto. A AC raiz padrão é armazenada em um ConfigMap chamado aio-ca-trust-bundle-test-only.

Para obter mais informações sobre como obter a AC raiz, consulte Configurar o TLS com o gerenciamento automático de certificados para proteger a comunicação MQTT.

Compatível com TLS

O campo tls define a configuração do TLS para a conexão de agente remoto ou local. Ela inclui os seguintes campos:

Campo Obrigatório Descrição
tlsEnabled Sim Se o TLS está habilitado ou não.
trustedCaCertificateConfigMap Não O certificado de AC para confiar ao se conectar ao agente. Obrigatório se o TLS estiver habilitado.

O suporte à criptografia TLS está disponível para conexões de agente remoto e local.

  • Para conexão de agente remoto: se o TLS estiver habilitado, um certificado de AC confiável deverá ser especificado como uma referência de ConfigMap do Kubernetes. Caso contrário, o handshake do TLS provavelmente falhará, a menos que o ponto de extremidade remoto seja amplamente confiável, um certificado de AC confiável já está no repositório de certificados do sistema operacional. Por exemplo, a Grade de Eventos usa uma raiz de AC amplamente confiável para que a especificação não seja necessária.
  • Para conexão de agente local (Azure IoT MQ): se o TLS estiver habilitado para o ouvinte do agente do Azure IoT MQ, o certificado de AC que emitiu o certificado do servidor ouvinte deverá ser especificado como uma referência de ConfigMap do Kubernetes.

Ao especificar uma AC confiável, crie um ConfigMap contendo a parte pública da AC e especifique o nome configmap na propriedade trustedCaCertificateConfigMap. Por exemplo:

kubectl create configmap client-ca-configmap --from-file ~/.step/certs/root_ca.crt

Configure MqttBridgeTopicMap

O recurso de MqttBridgeTopicMap define o mapeamento de tópico entre os agentes locais e remotos. Ele deve ser usado juntamente com um recurso de MqttBridgeConnector. Inclui os seguintes componentes:

  • O nome do recurso de MqttBridgeConnector ao qual vincular.
  • Uma lista de rotas para a ponte.
  • Uma configuração opcional de assinatura compartilhada.

Um MqttBridgeConnector pode usar vários MqttBridgeTopicMaps vinculados a ele. Quando um recurso de MqttBridgeConnector é implantado, o operador do Azure IoT MQ começa a verificar o namespace para encontrar qualquer MqttBridgeTopicMaps vinculado a ele e gerenciar automaticamente o fluxo de mensagens entre as instâncias de MqttBridgeConnector. Em seguida, uma vez implantado, o MqttBridgeTopicMap é vinculado ao MqttBridgeConnector. Cada MqttBridgeTopicMap pode ser vinculado a apenas um MqttBridgeConnector.

O exemplo a seguir mostra uma configuração de MqttBridgeTopicMap para fazer a ponte de mensagens do tópico remoto remote-topic para o tópico local local-topic:

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: MqttBridgeTopicMap
metadata:
  name: my-topic-map
  namespace: azure-iot-operations 
spec:
  mqttBridgeConnectorRef: my-mqtt-bridge
  routes:
    - direction: remote-to-local
      name: first-route
      qos: 0
      source: remote-topic
      target: local-topic
      sharedSubscription:
        groupMinimumShareNumber: 3
        groupName: group1
    - direction: local-to-remote
      name: second-route
      qos: 1
      source: local-topic
      target: remote-topic

A tabela a seguir descreve os campos no recurso de MqttBridgeTopicMap:

Campos Obrigatório Descrição
mqttBridgeConnectorRef Sim O nome do recurso MqttBridgeConnector a ser criado.
rotas Sim Uma lista de rotas para a ponte. Para obter mais informações, consulte Rotas.

Rotas

Um MqttBridgeTopicMap pode ter várias rotas. O campo routes define a lista de rotas. Ela inclui os seguintes campos:

Campos Obrigatório Descrição
direction Sim Direção do fluxo de mensagens. Pode ser remote-to-local ou local-to-remote. Para obter mais informações, consulte Direção.
name Sim O nome da rota.
qos Não QoS (Qualidade de Serviço) do MQTT. O valor padrão é 1.
source Sim Tópico do MQTT de origem. Pode ter curingas como # e +. Consulte Curingas no tópico de origem.
destino Não Tópico do MQTT de destino. Não pode ter curingas. Se não for especificado, ele será o mesmo que o de origem. Consulte Fazer referência do tópico de origem no destino.
sharedSubscription Não Configuração de assinatura compartilhada. Ativa um número configurado de clientes para escala adicional. Para obter mais informações, confira Recursos compartilhados.

Direção

Por exemplo, se a direção for local para remota, o Azure IoT MQ publicará todas as mensagens no tópico local especificado no tópico remoto:

routes:
  - direction: local-to-remote
    name: "send-alerts"
    source: "alerts"
    target: "factory/alerts"

Se a direção for invertida, o Azure IoT MQ receberá mensagens de um agente remoto. Aqui, o destino é omitido e todas as mensagens do tópico commands/factory no agente remoto são publicadas no mesmo tópico localmente.

routes:
  - direction: remote-to-local
    name: "receive-commands"
    source: "commands/factory"

Curingas no tópico de origem

Para fazer a ponte de tópicos não estáticos, use curingas para definir como os padrões de tópico devem ser correspondidos e a regra da tradução de nomes do tópico. Por exemplo, para fazer a ponte de todas as mensagens em todos os subtópicos em telemetry, use o curinga # de vários níveis:

routes:
  - direction: local-to-remote
    name: "wildcard-source"
    source: "telemetry/#"
    target: "factory/telemetry"

No exemplo, se uma mensagem for publicada em qualquer tópico em telemetry, como telemetry/furnace/temperature, o Azure IoT MQ a publicará no agente de ponte remota no tópico factory/telemetry estático.

Para curinga de tópico de nível único, use + em vez disso, como telemetry/+/temperature.

O conector de ponte MQTT deve saber o tópico exato no agente de destino remoto ou no Azure IoT MQ sem nenhuma ambiguidade. Curingas só estão disponíveis como parte do tópico source.

Fazer referência do tópico de origem no destino

Para fazer referência a todo o tópico de origem, omita completamente a configuração do tópico de destino na rota. Há suporte para caracteres curinga.

Por exemplo, qualquer mensagem publicada no tópico my-topic/#, como my-topic/foo ou my-topic/bar, é enviada ao agente remoto no mesmo tópico:

routes:
  - direction: local-to-remote
    name: "target-same-as-source"
    source: "my-topic/#"
    # No target

Não há suporte para outros métodos de referência de tópico de origem.

Assinaturas compartilhadas

O campo sharedSubscription define a configuração de assinatura compartilhada para a rota. Ela inclui os seguintes campos:

Campos Obrigatório Descrição
groupMinimumShareNumber Sim Número de clientes a serem usados para assinatura compartilhada.
groupName Sim Nome do grupo de assinaturas compartilhadas.

As assinaturas compartilhadas ajudam o Azure IoT MQ a criar mais clientes para a ponte MQTT. Você pode configurar uma assinatura compartilhada diferente para cada rota. O Azure IoT MQ assina mensagens do tópico de origem e as envia para um cliente por vez usando round-robin. Em seguida, o cliente publica as mensagens no agente de ponte.

Por exemplo, se você configurar uma rota com assinatura compartilhada e definir groupMinimumShareNumber como 3:

routes:
    - direction: local-to-remote
      qos: 1
      source: "shared-sub-topic"
      target: "remote/topic"
      sharedSubscription:
        groupMinimumShareNumber: 3
        groupName: "sub-group"

A ponte MQTT do Azure IoT MQ cria três clientes assinantes, independentemente da quantidade de instâncias. Apenas um cliente obtém cada mensagem de $share/sub-group/shared-sub-topic. Em seguida, o mesmo cliente publica a mensagem no agente remoto na ponte no tópico remote/topic. A próxima mensagem vai para um próximo cliente.

Isso ajuda a equilibrar o tráfego de mensagens para a ponte entre vários clientes com IDs diferentes. Isso será útil se o agente de ponte limitar quantas mensagens cada cliente pode enviar.

Suporte ao agente MQTT da Grade de Eventos do Azure

Para minimizar o gerenciamento de credenciais, usar a identidade gerenciada atribuída pelo sistema e o RBAC do Azure é a maneira recomendada de fazer a ponte entre o Azure IoT MQ e o recurso de agente MQTT da Grade de Eventos do Azure.

Para obter um tutorial de ponta a ponta, confira Tutorial: configurar a ponte MQTT entre a versão prévia do Azure IoT MQ e a Grade de Eventos do Azure.

Conectar-se ao agente MQTT da Grade de Eventos com identidade gerenciada

Primeiro, usando az k8s-extension show, localize a ID da entidade de segurança para a extensão Arc do Azure IoT MQ. Anote o valor de saída para identity.principalId, que deve se parecer com abcd1234-5678-90ab-cdef-1234567890ab.

az k8s-extension show --resource-group <RESOURCE_GROUP> --cluster-name <CLUSTER_NAME> --name mq --cluster-type connectedClusters --query identity.principalId -o tsv

Em seguida, use a CLI do Azure para atribuir as funções à identidade gerenciada da extensão Arc do Azure IoT MQ. Substitua <MQ_ID> pela ID da entidade de segurança descoberta na etapa anterior. Por exemplo, para atribuir a função Distribuidor de TopicSpaces do EventGrid:

az role assignment create --assignee <MQ_ID> --role 'EventGrid TopicSpaces Publisher' --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.EventGrid/namespaces/<EVENT_GRID_NAMESPACE>

Dica

Para otimizar o princípio de privilégios mínimos, você pode atribuir a função a um espaço de tópico em vez de todo o namespace da Grade de Eventos. Para saber mais, consulte RBAC da Grade de Eventos e Espaços do tópico.

Finalmente, crie um MQTTBridgeConnector e escolha a identidade gerenciada como o método de autenticação. Crie MqttBridgeTopicMaps e implante a ponte MQTT com kubectl.

Máximo de sessões de cliente por nome de autenticação

Se bridgeInstances for definido acima de 1, definaConfiguração>Máximo de sessões de cliente por nome de autenticação do agente MQTT da Grade de Eventos para corresponder ao número de instâncias. Essa configuração impede que problemas como o erro 151: cota excedida.

Limite por conexão

Se não for possível usar a identidade gerenciada, tenha em mente os limites por conexão do agente MQTT da Grade de Eventos ao projetar sua configuração. No momento da publicação, o limite é de 100 mensagens/segundo para cada direção de uma conexão. Para aumentar a taxa de transferência da ponte MQTT, use assinaturas compartilhadas para aumentar o número de clientes que atendem a cada rota.

Fazer a ponte de outro agente para a versão prévia do Azure IoT MQ

O Azure IoT MQ é um agente MQTT compatível e outros agentes podem fazer a ponte com as credenciais de autenticação e autorização apropriadas. Por exemplo, consulte a documentação da ponte MQTT para HiveMQ, VerneMQ, EMQX e Mosquitto.