Connecter le connecteur cloud du pont MQTT Azure IoT (préversion) à d’autres répartiteurs MQTT
Important
Opérations Azure IoT (préversion) – activé parc Azure Arc est actuellement en PRÉVERSION. Vous ne devez pas utiliser ce logiciel en préversion dans des environnements de production.
Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.
Vous pouvez utiliser le pont MQTT Azure IoT MQ (préversion) pour vous connecter à Azure Event Grid ou à d’autres répartiteurs MQTT. Le pontage MQTT est le processus consistant à connecter deux répartiteurs MQTT ensemble afin qu’ils puissent échanger des messages.
- Lorsque deux répartiteurs sont pontés, les messages publiés sur l’un sont automatiquement transférés vers l’autre et inversement.
- Le pontage MQTT permet de créer un réseau de répartiteurs MQTT qui communiquent les uns avec les autres et de développer l’infrastructure MQTT en ajoutant des répartiteurs supplémentaires au besoin.
- Le pontage MQTT est utile pour prendre en charge plusieurs emplacements physiques, partager des messages et des rubriques MQTT entre la périphérie et le cloud ou encore intégrer MQTT à d’autres systèmes de messagerie.
Pour créer un pont vers un autre répartiteur, Azure IoT MQ doit connaître l’URL du point de terminaison du répartiteur distant, la version de MQTT, la procédure d’authentification et les rubriques à mapper. Pour optimiser la composabilité et la flexibilité en mode Kubernetes natif, ces valeurs sont configurées en tant que ressources Kubernetes personnalisées (CRD), appelées MqttBridgeConnector et MqttBridgeTopicMap. Ce guide explique comment créer le connecteur de pont MQTT à l’aide de ces ressources.
Créez un fichier YAML qui définit la ressource MqttBridgeConnector. Vous pouvez utiliser l’exemple de fichier YAML. Toutefois, veillez à modifier
namespacepour qu’il corresponde à celui sur lequel Azure IoT MQ est déployé etremoteBrokerConnection.endpointpour qu’il corresponde à l’URL du point de terminaison du répartiteur distant.Créez un fichier YAML qui définit la ressource MqttBridgeTopicMap. Vous pouvez utiliser l’exemple de fichier YAML. Toutefois, veillez à modifier
namespacepour qu’il corresponde à celui sur lequel Azure IoT MQ est déployé et à modifiermqttBridgeConnectorRefpour qu’il corresponde au nom de la ressource MqttBridgeConnector créée à l’étape précédente.Déployez le connecteur de pont MQTT et la carte de rubriques avec
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
Une fois le déploiement terminé, utilisez kubectl get pods pour vérifier que les messages commencent à circuler vers et depuis votre point de terminaison.
Configurer MqttBridgeConnector
La ressource MqttBridgeConnector définit le connecteur de pont MQTT qui peut communiquer avec un répartiteur distant. Celle-ci comprend les composants suivants :
- Une ou plusieurs instances de connecteur de pont MQTT. Chaque instance est un conteneur exécutant le connecteur de pont MQTT.
- Une connexion de répartiteur distant.
- Une connexion de répartiteur local facultative.
L’exemple suivant montre un exemple de configuration pour créer un pont vers un répartiteur MQTT Azure Event Grid. Il utilise l’identité managée affectée par le système pour l’authentification et le chiffrement 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: {}
Le tableau suivant décrit les champs de la ressource MqttBridgeConnector :
| Champ | Requis | Description |
|---|---|---|
| image | Oui | Image du connecteur Kafka. Vous pouvez spécifier les éléments pullPolicy, repository et tag de l’image. Les valeurs appropriées sont indiquées dans l’exemple précédent. |
| protocol | Oui | Version du protocole MQTT. Peut être v5 ou v3. Consultez Prise en charge de MQTT v3.1.1. |
| bridgeInstances | Non | Nombre d’instances pour le connecteur de pont. 1 constitue la valeur par défaut. Consultez Nombre d’instances. |
| clientIdPrefix | Non | Préfixe de l’ID client généré dynamiquement. Par défaut, aucun préfixe n’est défini. Consultez Configuration de l’ID client. |
| logLevel | Non | Niveau de consignation. Peut être debug ou info. La valeur par défaut est info. |
| remoteBrokerConnection | Oui | Détails de la connexion du répartiteur distant vers lequel établir un pont. Consultez Connexion du répartiteur distant. |
| localBrokerConnection | Non | Détails de la connexion du répartiteur local vers lequel établir un pont. La valeur par défaut est affichée. Consultez Connexion du répartiteur local. |
Prise en charge de MQTT v3.1.1
Le connecteur de pont peut être configuré pour utiliser MQTT v3.1.1 avec la connexion du répartiteur local pour Azure IoT MQ et la connexion du répartiteur distant. Toutefois, si le répartiteur distant ne prend pas en charge cette version, les abonnements partagés sont arrêtés. Si vous envisagez d’utiliser des abonnements partagés, laissez la valeur par défaut (v5).
Nombre d’instances
À des fins de haute disponibilité et de mise à l’échelle, configurez le connecteur de pont MQTT pour utiliser plusieurs instances. Le flux de messages et les itinéraires sont automatiquement équilibrés entre différentes instances.
spec:
bridgeInstances: 2
Configuration de l’ID client
Azure IoT MQ génère un ID client pour chaque client MqttBridgeConnector, à l’aide d’un préfixe que vous spécifiez, au format {clientIdPrefix}-{routeName}. Cet ID client est important pour Azure IoT MQ afin d’atténuer la perte de messages et d’éviter les conflits ou les collisions avec les ID client existants, car la spécification MQTT n’autorise qu’une seule connexion par ID client.
Par exemple, si clientIdPrefix: "client-" et qu’il y a deux routes dans la carte de rubriques, les ID client sont : client-route1 et client-route2.
Connexion du répartiteur distant
Le champ remoteBrokerConnection définit les détails de la connexion pour établir un pont vers le répartiteur distant. Elle comprend les champs suivants :
| Champ | Requis | Description |
|---|---|---|
| endpoint | Oui | URL du point de terminaison du répartiteur distant avec le port. Par exemple : example.westeurope-1.ts.eventgrid.azure.net:8883. |
| tls | Oui | Spécifie si la connexion est chiffrée avec TLS et un certificat d’autorité de certification approuvé. Consultez Prise en charge de TLS. |
| authentification | Oui | Détails de l’authentification pour Azure IoT MQ à utiliser avec le répartiteur. Doit être l’une des valeurs suivantes : identité managée affectée par le système ou X.509. Voir Authentification. |
| protocol | Non | Valeur de chaîne définissant l’utilisation de MQTT ou de MQTT sur WebSockets. Peut être mqtt ou webSocket. La valeur par défaut est mqtt. |
Authentification
Le champ d’authentification définit la méthode d’authentification pour Azure IoT MQ à utiliser avec le répartiteur distant. Elle comprend les champs suivants :
| Champ | Requis | Description |
|---|---|---|
| systemAssignedManagedIdentity | Non | L’authentification utilise une identité managée affectée par le système. Consultez Identité managée. |
| x509 | Non | Détails de l’authentification à l’aide de certificats X.509. Consultez X.509. |
Identité gérée
Le champ systemAssignedManagedIdentity comprend les champs suivants :
| Champ | Requis | Description |
|---|---|---|
| audience | Oui | Audience du jeton. Obligatoire si vous utilisez l’identité managée. Pour Event Grid, il s’agit de https://eventgrid.azure.net. |
Si Azure IoT MQ est déployé en tant qu’extension Azure Arc, il obtient par défaut une identité managée affectée par le système. Vous devez utiliser une identité managée pour Azure IoT MQ afin d’interagir avec les ressources Azure, notamment Event Grid MQTT broker, car cela vous évite de gérer les informations d’identification tout en conservant une haute disponibilité.
Pour utiliser l’identité managée pour l’authentification avec les ressources Azure, attribuez d’abord un rôle RBAC Azure approprié comme EventGrid TopicSpaces Publisher à l’identité managée d’Azure IoT MQ fournie par Arc.
Ensuite, spécifiez MQTTBridgeConnector avec une identité managée comme méthode d’authentification :
spec:
remoteBrokerConnection:
authentication:
systemAssignedManagedIdentity:
audience: https://eventgrid.azure.net
Quand vous utilisez une identité managée, l’ID client n’est pas configurable et équivaut à l’ID de ressource Azure Resource Manager de l’extension Azure IoT MQ Azure Arc dans Azure.
L’identité managée affectée par le système est fournie par Azure Arc. Le certificat associé à l’identité managée doit être renouvelé au moins tous les 90 jours pour éviter un processus de récupération manuel. Pour en savoir plus, consultez Comment faire pour traiter des ressources Kubernetes avec Azure Arc arrivées à expiration ?.
X.509
Le champ x509 comprend les champs suivants :
| Champ | Requis | Description |
|---|---|---|
| secretName | Oui | Secret Kubernetes contenant le certificat client et la clé privée. Vous pouvez utiliser Azure Key Vault pour gérer les secrets pour Azure IoT MQ au lieu des secrets Kubernetes. Pour en savoir plus, consultez Gérer les secrets en utilisant Azure Key Vault ou les secrets Kubernetes. |
De nombreux répartiteurs MQTT comme Event Grid prennent en charge l’authentification X.509. Le pont MQTT d’Azure IoT MQ peut présenter un certificat X.509 client et négocier la communication TLS. Utilisez un secret Kubernetes pour stocker le certificat client X.509, la clé privée et l’autorité de certification intermédiaire.
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
Et référencez-le avec secretName :
spec:
remoteBrokerConnection:
authentication:
x509:
secretName: bridge-client-cert
Connexion de répartiteur local
Le champ localBrokerConnection définit les détails de la connexion pour établir un pont vers le répartiteur local.
| Champ | Requis | Description |
|---|---|---|
| endpoint | Oui | URL du point de terminaison du répartiteur distant avec le port. |
| tls | Oui | Spécifie si la connexion est chiffrée avec TLS et un certificat d’autorité de certification approuvé. Consultez Prise en charge de TLS. |
| authentification | Oui | Détails de l’authentification pour Azure IoT MQ à utiliser avec le répartiteur. La seule méthode prise en charge est le jeton de compte de service Kubernetes (SAT). Pour utiliser SAT, spécifiez kubernetes: {}. |
Par défaut, IoT MQ est déployé dans l’espace de noms azure-iot-operations avec TLS activé et l’authentification SAT.
Ensuite, le paramètre de connexion du répartiteur local MqttBridgeConnector doit être configuré pour le faire correspondre. Le fichier YAML de déploiement pour MqttBridgeConnector doit avoir localBrokerConnection au même niveau que remoteBrokerConnection. Par exemple, pour utiliser TLS avec l’authentification SAT afin de correspondre au déploiement IoT MQ par défaut :
spec:
localBrokerConnection:
endpoint: aio-mq-dmqtt-frontend:8883
tls:
tlsEnabled: true
trustedCaCertificateConfigMap: aio-ca-trust-bundle-test-only
authentication:
kubernetes: {}
Ici, trustedCaCertifcateName est le ConfigMap pour l’autorité de certification racine d’Azure IoT MQ, comme le ConfigMap pour l’autorité de certification racine du répartiteur distant. L’autorité de certification racine par défaut est stockée dans un ConfigMap nommé aio-ca-trust-bundle-test-only.
Pour plus d’informations sur l’obtention de l’autorité de certification racine, consultez Configurer TLS avec la gestion automatique des certificats pour sécuriser la communication MQTT.
Prise en charge de TLS
Le champ tls définit la configuration TLS pour la connexion du répartiteur distant ou local. Elle comprend les champs suivants :
| Champ | Requis | Description |
|---|---|---|
| tlsEnabled | Oui | Indique si TLS est activé ou non. |
| trustedCaCertificateConfigMap | Non | Certificat d’autorité de certification à approuver lors de la connexion au répartiteur. Obligatoire si TLS est activé. |
La prise en charge du chiffrement TLS est disponible pour les connexions des répartiteurs distant et local.
- Pour la connexion du répartiteur distant : si TLS est activé, un certificat d’autorité de certification approuvé doit être spécifié comme référence Kubernetes ConfigMap. Si ce n’est pas le cas, il est probable que l’établissement d’une liaison TLS échoue, sauf si le point de terminaison distant est largement approuvé et qu’un certificat d’autorité de certification approuvé se trouve déjà dans le magasin de certificats du système d’exploitation. Par exemple, Event Grid utilisant la racine d’autorité de certification largement approuvée, la spécification n’est pas nécessaire.
- Pour la connexion du répartiteur local (Azure IoT MQ) : si TLS est activé pour l’écouteur du répartiteur Azure IoT MQ, le certificat d’autorité de certification ayant émis le certificat de serveur de l’écouteur doit être spécifié en tant que référence Kubernetes ConfigMap.
Quand la spécification d’une autorité de certification approuvée est requise, créez un ConfigMap contenant la portion publique de l’autorité de certification et spécifiez le nom du ConfigMap dans la propriété trustedCaCertificateConfigMap. Par exemple :
kubectl create configmap client-ca-configmap --from-file ~/.step/certs/root_ca.crt
Configurer MqttBridgeTopicMap
La ressource MqttBridgeTopicMap définit le mappage de rubriques entre les répartiteurs local et distant. Elle doit être utilisée avec une ressource MqttBridgeConnector. Celle-ci comprend les composants suivants :
- Nom de la ressource MqttBridgeConnector vers laquelle établir un lien.
- Liste des itinéraires pour le pontage.
- Configuration d’abonnement partagé facultative.
Un MqttBridgeConnector peut utiliser plusieurs MqttBridgeTopicMaps liés à celui-ci. Quand une ressource MqttBridgeConnector est déployée, l’opérateur Azure IoT MQ commence à analyser l’espace de noms à la recherche de MqttBridgeTopicMaps liés à celui-ci et gère automatiquement le flux de messages entre les instances MqttBridgeConnector. Ensuite, une fois déployé, le MqttBridgeTopicMap est lié au MqttBridgeConnector. Chaque MqttBridgeTopicMap ne peut être lié qu’à un seul MqttBridgeConnector.
L’exemple suivant montre une configuration MqttBridgeTopicMap pour ponter les messages de la rubrique distante remote-topic vers la rubrique locale 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
Le tableau suivant décrit les champs de la ressource MqttBridgeTopicMap :
| Champs | Requis | Description |
|---|---|---|
| mqttBridgeConnectorRef | Oui | Nom de la ressource MqttBridgeConnector vers laquelle établir un lien. |
| itinéraires | Oui | Liste des itinéraires pour le pontage. Pour plus d’informations, consultez Itinéraires. |
Itinéraires
Un MqttBridgeTopicMap peut avoir plusieurs itinéraires. Le champ routes définit la liste des itinéraires. Elle comprend les champs suivants :
| Champs | Requis | Description |
|---|---|---|
| direction | Oui | Direction du flux de messages. Il peut s’agir de remote-to-local ou de local-to-remote. Pour plus d’informations, consultez Direction. |
| name | Oui | Nom de la route. |
| Qualité de service (QoS) | Non | Qualité de service (QoS) de MQTT. La valeur par défaut est de 1. |
| source | Oui | Rubrique MQTT source. Peut avoir des caractères génériques comme # et +. Consultez Caractères génériques dans la rubrique source. |
| cible | Non | Rubrique MQTT cible. Ne peux pas avoir de caractères génériques. Si elle n’est pas spécifiée, elle est identique à la source. Consultez Référencer la rubrique source dans la cible. |
| sharedSubscription | Non | Configuration de l’abonnement partagé. Active un nombre configuré de clients pour une mise à l’échelle supplémentaire. Pour plus d’informations, consultez Abonnements partagés. |
Sens
Par exemple, si la direction est « local à distant », Azure IoT MQ publie tous les messages relatifs à la rubrique locale spécifiée sur la rubrique distante :
routes:
- direction: local-to-remote
name: "send-alerts"
source: "alerts"
target: "factory/alerts"
Si la direction est inversée, Azure IoT MQ reçoit les messages d’un répartiteur distant. Ici, la cible est omise et tous les messages de la rubrique commands/factory sur le répartiteur distant sont publiés sur la même rubrique localement.
routes:
- direction: remote-to-local
name: "receive-commands"
source: "commands/factory"
Caractères génériques dans la rubrique source
Pour établir un pont à partir de rubriques non statiques, utilisez des caractères génériques pour définir la façon dont les modèles de rubrique doivent être mis en correspondance et la règle de traduction du nom de la rubrique. Par exemple, pour ponter tous les messages dans toutes les sous-rubriques sous telemetry, utilisez le caractère générique multiniveau # :
routes:
- direction: local-to-remote
name: "wildcard-source"
source: "telemetry/#"
target: "factory/telemetry"
Dans l’exemple, si un message est publié sur n’importe quelle rubrique sous telemetry, comme telemetry/furnace/temperature, Azure IoT MQ le publie sur le répartiteur ponté distant sous la rubrique statique factory/telemetry.
Pour un caractère générique de rubrique mono-niveau, utilisez plutôt +, comme telemetry/+/temperature.
Le connecteur de pont MQTT doit connaître la rubrique exacte dans le répartiteur cible (distant ou Azure IoT MQ), sans aucune ambiguïté. Les caractères génériques ne sont disponibles que dans le cadre de la rubrique source.
Référencer la rubrique source dans la cible
Pour référencer l’intégralité de la rubrique source, omettez complètement la configuration de la rubrique cible dans l’itinéraire. Les caractères génériques sont pris en charge.
Par exemple, tout message publié sous la rubrique my-topic/#, comme my-topic/foo ou my-topic/bar, est ponté vers le répartiteur distant sous la même rubrique :
routes:
- direction: local-to-remote
name: "target-same-as-source"
source: "my-topic/#"
# No target
Les autres méthodes de référence de rubrique source ne sont pas prises en charge.
Abonnements partagés
Le champ sharedSubscription définit la configuration d’abonnement partagé pour l’itinéraire. Elle comprend les champs suivants :
| Champs | Requis | Description |
|---|---|---|
| groupMinimumShareNumber | Oui | Nombre de clients à utiliser pour un abonnement partagé. |
| groupName | Oui | Nom du groupe d’abonnements partagés. |
Les abonnements partagés permettent à Azure IoT MQ de créer davantage de clients pour le pont MQTT. Vous pouvez configurer un abonnement partagé différent pour chaque itinéraire. Azure IoT MQ s’abonne aux messages de la rubrique source et les envoie à un client à la fois à l’aide d’un tourniquet (round robin). Ensuite, le client publie les messages sur le répartiteur ponté.
Par exemple, si vous configurez un itinéraire avec un abonnement partagé et que vous définissez groupMinimumShareNumber sur 3 :
routes:
- direction: local-to-remote
qos: 1
source: "shared-sub-topic"
target: "remote/topic"
sharedSubscription:
groupMinimumShareNumber: 3
groupName: "sub-group"
Le pont MQTT d’Azure IoT MQ crée trois clients abonnés, quel que soit le nombre d’instances. Un seul client obtient chaque message de $share/sub-group/shared-sub-topic. Ensuite, le même client publie le message sur le répartiteur distant ponté sous la rubrique remote/topic. Le message suivant est envoyé au client suivant.
Cela vous permet d’équilibrer le trafic de messages pour le pont entre plusieurs clients avec différents ID. Cela est utile si votre répartiteur ponté limite le nombre de messages que chaque client peut envoyer.
Prise en charge d’Azure Event Grid MQTT broker
Pour réduire la gestion des informations d’identification, il est recommandé d’utiliser l’identité managée affectée par le système et Azure RBAC pour ponter Azure IoT MQ avec la fonctionnalité MQTT broker d’Azure Event Grid.
Pour obtenir un didacticiel complet, consultez Tutoriel : configurer un pont MQTT entre Azure IoT MQ Preview et Azure Event Grid.
Se connecter au MQTT broker Event Grid avec une identité managée
Pour commencer, avec az k8s-extension show, recherchez l’ID principal de l’extension Azure IoT MQ Arc. Notez la valeur de sortie pour identity.principalId, qui doit ressembler à 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
Ensuite, utilisez Azure CLI pour attribuer les rôles à l’identité managée de l’extension Azure IoT MQ Arc. Remplacez <MQ_ID> par l’ID principal que vous avez trouvé à l’étape précédente. Par exemple, pour attribuer le rôle EventGrid TopicSpaces Publisher :
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>
Conseil
Pour optimiser le principe du privilège minimum, vous pouvez attribuer le rôle à un espace de rubrique au lieu de l’espace de noms Event Grid en entier. Pour en savoir plus, consultez Event Grid RBAC et Espaces de rubriques.
Enfin, créez un MQTTBridgeConnector et choisissez Identité managée comme méthode d’authentification. Créez MqttBridgeTopicMaps et déployez le pont MQTT avec kubectl.
Nombre maximal de sessions clientes par nom d’authentification
Si bridgeInstances est défini avec une valeur supérieure à 1, configurez Event Grid MQTT broker avec une valeur correspondant au nombre d’instances (Configuration>Nombre maximal de sessions clientes par nom d’authentification). Cette configuration permet d’éviter des problèmes du type Erreur 151 : quota dépassé.
Limite par connexion
Si l’utilisation d’une identité managée n’est pas possible, gardez à l’esprit les limites par connexion pour Event Grid MQTT broker lors de la conception de votre configuration. Au moment de la publication, la limite est de 100 messages/secondes dans chaque direction pour une connexion. Pour augmenter le débit du pont MQTT, utilisez des abonnements partagés pour augmenter le nombre de clients desservant chaque itinéraire.
Pont d’un autre répartiteur vers Azure IoT MQ (préversion)
Azure IoT MQ est un répartiteur MQTT conforme, et d’autres répartiteurs peuvent établir un pont à celui-ci avec les informations d’identification d’authentification et d’autorisation appropriées. Par exemple, consultez la documentation du pont MQTT pour HiveMQ, VerneMQ, EMQX et Mosquitto.
Contenu connexe
Commentaires
Prochainement : Tout au long de l'année 2024, nous supprimerons progressivement les GitHub Issues en tant que mécanisme de retour d'information pour le contenu et nous les remplacerons par un nouveau système de retour d'information. Pour plus d’informations, voir: https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour