Compartilhar via

Tutorial: Configurar a ponte MQTT entre o MQ do Azure IoT (versão prévia) e a Grade de Eventos do Azure

  • Artigo

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.

Neste tutorial, você aprenderá a configurar o IoT MQ para a ponte MQTT bidirecional com o PaaS do agente MQTT da Grade de Eventos do Azure. Você pode usar esse recurso para processar seus dados de IoT na borda e na nuvem. Por exemplo, você pode usar o MQ do IoT para processar dados de telemetria na borda e, em seguida, fazer a ponte dos dados para a Grade de Eventos do Azure para processamento adicional na nuvem.

Pré-requisitos

Definir variáveis de ambiente

Entre com a CLI do Azure:

az login

Defina as variáveis de ambiente para o restante da configuração. Substitua valores em <> por valores ou nomes válidos de sua escolha. Um novo namespace da Grade de Eventos do Azure e um espaço de tópico são criados em sua assinatura do Azure com base nos nomes que você fornece:

# For this tutorial, the steps assume the IoT Operations cluster and the Event Grid
# are in the same subscription, resource group, and location.

# Name of the resource group of Azure Event Grid and IoT Operations cluster 
export RESOURCE_GROUP=<RESOURCE_GROUP_NAME>

# Azure region of Azure Event Grid and IoT Operations cluster
export LOCATION=<LOCATION>

# Name of the Azure Event Grid namespace
export EVENT_GRID_NAMESPACE=<EVENT_GRID_NAMESPACE>

# Name of the Arc-enabled IoT Operations cluster 
export CLUSTER_NAME=<CLUSTER_NAME>

# Subscription ID of Azure Event Grid and IoT Operations cluster
export SUBSCRIPTION_ID=<SUBSCRIPTION_ID>

Criar namespace da Grade de Eventos com o agente MQTT habilitado

Crie o namespace da Grade de Eventos com a CLI do Azure. O local deve ser o mesmo que você usou para implantar operações de IoT do Azure.

az eventgrid namespace create \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --topic-spaces-configuration "{state:Enabled,maximumClientSessionsPerAuthenticationName:3}"

Ao definir o topic-spaces-configuration, este comando cria um namespace com:

  • Agente MQTT habilitado
  • Máximo de sessões de cliente por nome de autenticação como 3.

A opção máximo de sessões de cliente permite que o IoT MQ gere várias instâncias e ainda se conecte. Para saber mais, confira suporte a várias sessões.

Criar um espaço de tópico

No namespace da Grade de Eventos, crie um espaço de tópico nomeado tutorial com um modelo de tópico telemetry/#.

az eventgrid namespace topic-space create \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --name tutorial \
  --topic-templates "telemetry/#"

Usando o curinga # no modelo de tópico, você pode publicar em qualquer tópico no espaço do tópico telemetry. Por exemplo, telemetry/temperature ou telemetry/humidity.

Permita acesso ao MQ do Azure IoT (versão prévia) no espaço de tópico da Grade de Eventos

Usando az k8s-extension show, localize a ID da entidade de segurança para a extensão do Azure IoT MQ Arc. O comando armazena a ID da entidade de segurança em uma variável para uso posterior.

export PRINCIPAL_ID=$(az k8s-extension show \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name mq \
  --cluster-type connectedClusters \
  --query identity.principalId -o tsv)
echo $PRINCIPAL_ID

Anote o valor de saída para identity.principalId, que é um valor GUID com o seguinte formato:

d84481ae-9181-xxxx-xxxx-xxxxxxxxxxxx

Em seguida, use a CLI do Azure para atribuir funções de editor e assinante ao IoT MQ para o espaço de tópico que você criou.

Atribua a função de editor:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "EventGrid TopicSpaces Publisher" \
  --scope /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.EventGrid/namespaces/$EVENT_GRID_NAMESPACE/topicSpaces/tutorial

Atribua a função de assinante:

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "EventGrid TopicSpaces Subscriber" \
  --scope /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.EventGrid/namespaces/$EVENT_GRID_NAMESPACE/topicSpaces/tutorial

Dica

O escopo corresponde ao id do espaço de tópico que você criou com az eventgrid namespace topic-space create na etapa anterior e você pode encontrá-lo na saída do comando.

Nome do host do agente MQTT da Grade de Eventos

Use a CLI do Azure para obter o nome de host do agente MQTT da Grade de Eventos.

az eventgrid namespace show \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENT_GRID_NAMESPACE \
  --query topicSpacesConfiguration.hostname \
  -o tsv

Anote o valor de saída para topicSpacesConfiguration.hostname esse é um valor de nome de host semelhante a:

example.region-1.ts.eventgrid.azure.net

Criar um conector de ponte MQTT e recursos de mapa de tópicos

Em um novo arquivo chamado bridge.yaml, especifique o conector de ponte MQTT e a configuração do mapa de tópicos. Substitua o valor do espaço reservado de exemplo em remoteBrokerConnectionendpoint pelo nome do host MQTT da Grade de Eventos da etapa anterior. Inclua o número da porta 8883.

apiVersion: mq.iotoperations.azure.com/v1beta1
kind: MqttBridgeConnector
metadata:
  name: tutorial-bridge
  namespace: azure-iot-operations
spec:
  image: 
    repository: mcr.microsoft.com/azureiotoperations/mqttbridge
    tag: 0.4.0-preview
    pullPolicy: IfNotPresent
  protocol: v5
  bridgeInstances: 2
  logLevel: debug
  remoteBrokerConnection:
    endpoint: example.region-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: {}
---
apiVersion: mq.iotoperations.azure.com/v1beta1
kind: MqttBridgeTopicMap
metadata:
  name: tutorial-topic-map
  namespace: azure-iot-operations 
spec:
  mqttBridgeConnectorRef: tutorial-bridge
  routes:
    - direction: local-to-remote
      name: publish
      source: tutorial/local
      target: telemetry/iot-mq
      qos: 1
    - direction: remote-to-local
      name: subscribe
      source: telemetry/#
      target: tutorial/cloud
      qos: 1

Configure o conector de ponte MQTT para:

  • Usar o agente MQTT da Grade de Eventos como o agente remoto
  • Usar o agente do IoT MQ local como o agente local
  • Usar o TLS para agentes remotos e locais
  • Usar a identidade gerenciada atribuída pelo sistema para autenticação no agente remoto
  • Usar a conta de serviço do Kubernetes para autenticação no agente local
  • Usar o mapa de tópicos para mapear o tópico tutorial/local para o tópico telemetry/iot-mq no agente remoto
  • Usar o mapa de tópicos para mapear o tópico telemetry/# sobre o agente remoto para o tópico tutorial/cloud no agente local

Quando você publica no tópico tutorial/local no agente do IoT MQ local, a mensagem é colocada em ponte para o tópico telemetry/iot-mq no agente MQTT da Grade de Eventos remoto. Em seguida, a mensagem é enviada novamente para o tutorial/cloud tópico no agente do IoT MQ local. Da mesma forma, quando você publica no telemetry/iot-mq tópico no agente MQTT da Grade de Eventos remoto, a mensagem é colocada em ponte para o tutorial/cloud tópico no agente do IoT MQ local.

Aplique o arquivo de implantação com kubectl.

kubectl apply -f bridge.yaml

mqttbridgeconnector.mq.iotoperations.azure.com/tutorial-bridge created
mqttbridgetopicmap.mq.iotoperations.azure.com/tutorial-topic-map created

Verificar a implantação da ponte MQTT

Use o kubectl para verificar se as duas instâncias de ponte estão prontas e em execução.

kubectl get pods -n azure-iot-operations -l app=aio-mq-mqttbridge

NAME                       READY   STATUS    RESTARTS   AGE
aio-mq-tutorial-bridge-0   1/1     Running   0          45s
aio-mq-tutorial-bridge-1   1/1     Running   0          45s

Agora você pode publicar no agente local e assinar o Agente MQTT da Grade de Eventos e verificar o fluxo de mensagens conforme o esperado.

Implantar cliente MQTT

Para verificar se a ponte MQTT está funcionando, implante um cliente MQTT no mesmo namespace que o IoT MQ. Em um novo arquivo chamado client.yaml, especifique a implantação do cliente:

apiVersion: v1
kind: Pod
metadata:
  name: mqtt-client
  namespace: azure-iot-operations
spec:
  serviceAccountName: mqtt-client
  containers:
  - image: alpine
    name: mqtt-client
    command: ["sh", "-c"]
    args: ["apk add mosquitto-clients mqttui && sleep infinity"]
    volumeMounts:
    - name: mq-sat
      mountPath: /var/run/secrets/tokens
    - name: trust-bundle
      mountPath: /var/run/certs
  volumes:
  - name: mq-sat
    projected:
      sources:
      - serviceAccountToken:
          path: mq-sat
          audience: aio-mq
          expirationSeconds: 86400
  - name: trust-bundle
    configMap:
      name: aio-ca-trust-bundle-test-only

Aplique o arquivo de implantação com kubectl.

kubectl apply -f client.yaml

pod/mqtt-client created

Iniciar um assinante

Use kubectl exec para iniciar um shell no pod do cliente mosquitto.

kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh

Dentro do shell, inicie um assinante para o agente do IoT MQ no espaço de tópico tutorial/# com mqttui.

mqttui log "tutorial/#" \
-b mqtts://aio-mq-dmqtt-frontend:8883 \
-u '$sat' \
--password $(cat /var/run/secrets/tokens/mq-sat) \
--insecure

Deixe o comando em execução e abra uma nova janela de terminal.

Publicar mensagens MQTT na nuvem por meio da ponte

Em uma nova janela do terminal, inicie outro shell no pod do cliente mosquitto.

kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh

Dentro do shell, use mosquitto para publicar cinco mensagens no tópico tutorial/local.

mosquitto_pub -h aio-mq-dmqtt-frontend -p 8883 \
-m "This message goes all the way to the cloud and back!" \
-t "tutorial/local" -u '$sat' -P $(cat /var/run/secrets/tokens/mq-sat) \
--cafile /var/run/certs/ca.crt \
--repeat 5 --repeat-delay 1 -d

Exibir as mensagens no assinante

No shell do assinante, você verá as mensagens publicadas.

23:17:50.802 QoS:AtMostOnce  tutorial/local     Payload( 52): This message goes all the way to the cloud and back!
23:17:51.086 QoS:AtMostOnce  tutorial/cloud     Payload( 52): This message goes all the way to the cloud and back!
23:17:51.803 QoS:AtMostOnce  tutorial/local     Payload( 52): This message goes all the way to the cloud and back!
23:17:51.888 QoS:AtMostOnce  tutorial/cloud     Payload( 52): This message goes all the way to the cloud and back!
23:17:52.804 QoS:AtMostOnce  tutorial/local     Payload( 52): This message goes all the way to the cloud and back!
23:17:52.888 QoS:AtMostOnce  tutorial/cloud     Payload( 52): This message goes all the way to the cloud and back!
23:17:53.805 QoS:AtMostOnce  tutorial/local     Payload( 52): This message goes all the way to the cloud and back!
23:17:53.895 QoS:AtMostOnce  tutorial/cloud     Payload( 52): This message goes all the way to the cloud and back!
23:17:54.807 QoS:AtMostOnce  tutorial/local     Payload( 52): This message goes all the way to the cloud and back!
23:17:54.881 QoS:AtMostOnce  tutorial/cloud     Payload( 52): This message goes all the way to the cloud and back!

Aqui, você verá que as mensagens são publicadas no agente do IoT MQ local para o tópico tutorial/local, feitas em ponte para o agente MQTT da Grade de Eventos e, em seguida, enviadas novamente ao agente do IoT MQ local novamente sobre o tópico tutorial/cloud. Em seguida, as mensagens são entregues ao assinante. Neste exemplo, o tempo de viagem de ida e volta é de cerca de 80 ms.

Verificar as métricas da Grade de Eventos para verificar a entrega de mensagens

Você também pode verificar as métricas da Grade de Eventos para verificar se as mensagens são entregues ao agente MQTT da Grade de Eventos. No portal do Azure, navegue até o namespace da Grade de Eventos que você criou. Em Métricas>MQTT: Mensagens publicadas com êxito. Você deverá ver o número de mensagens publicadas e entregues aumentar à medida que publica mensagens no agente do IoT MQ local.

Screenshot of the metrics view in Azure portal to show successful MQTT messages.

Dica

Verifique as configurações de mapas de tópicos, QoS e rotas de mensagem com a extensão da CLIaz iot ops check --detail-level 2.

Próximas etapas

Neste tutorial, você aprendeu a configurar o IoT MQ para ponte MQTT bidirecional com o agente MQTT da Grade de Eventos do Azure. Como próximas etapas, explore os seguintes cenários:

Conteúdo relacionado