Communication sécurisée du courtier MQTT à l'aide de BrokerListener

Article
01/30/2025

Important

Cette page inclut des instructions pour la gestion des composants Azure IoT Operations à l’aide des manifestes de déploiement Kubernetes, qui sont en version préliminaire. Cette fonctionnalité est fournie avec plusieurs limitations et ne doit pas être utilisée pour les charges de travail 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.

Une ressource BrokerListener correspond à un point de terminaison réseau qui expose le courtier aux clients sur le réseau. Vous pouvez avoir une ou plusieurs ressources BrokerListener pour chaque courtier, avec plusieurs ports et un contrôle d'accès différent sur chacun.

Chaque port BrokerListener peut avoir ses propres règles d’authentification et d’autorisation qui définissent qui peut se connecter sur ce port d’écouteur et quelles actions il peut effectuer sur le répartiteur. Vous pouvez utiliser les ressources BrokerAuthentication et BrokerAuthorization pour spécifier les stratégies de contrôle d’accès pour chaque port d’écouteur. Cette flexibilité vous permet d’affiner les autorisations et les rôles de vos clients MQTT en fonction de leurs besoins et de leurs cas d’usage.

Conseil

Le déploiement du courtier MQTT par défaut est un service IP de cluster qui nécessite que les clients se connectent avec le protocole TLS (Transport Layer Security) et s'authentifient avec des jetons de compte de service. Les clients se connectant depuis l’extérieur du cluster ont besoin d’une configuration supplémentaire pour pouvoir se connecter.

Les écouteurs de répartiteur présentent les caractéristiques suivantes :

Nom : nom de l’écouteur. Ce nom est également le nom du service Kubernetes, sauf substitution.
Type de service : vous pouvez avoir jusqu’à trois écouteurs, un par type de service. L’écouteur par défaut est le type de service ClusterIp.
Ports : chaque écouteur prend en charge plusieurs ports. Les ports ne peuvent pas entrer en conflit sur différents écouteurs.
Références d’authentification et d’autorisation : BrokerAuthentication et BrokerAuthorization sont configurés par port.
TLS : la configuration TLS manuelle ou automatique est appliquée par port.
Protocole : MQTT sur WebSockets peut être activé par port.

Pour obtenir la liste des paramètres disponibles, consultez les Informations de référence sur l’API Broker Listener.

BrokerListener par défaut

Lorsque vous déployez Azure IoT Operations, le déploiement crée une ressource BrokerListener nommée default. Cet écouteur est utilisé pour la communication interne cryptée entre les composants des opérations IoT. L'écouteur par défaut fait partie du courtier par défaut.

Il expose un service ClusterIp sur le port 18883.
Il oblige les clients à utiliser l’authentification du compte de service Kubernetes.
Il dispose d'un certificat TLS géré automatiquement.
Il ne configure aucune politique d’autorisation client.

Attention

Pour éviter de perturber la communication interne des opérations IoT, conservez l'écouteur par défaut inchangé et dédié à un usage interne. Pour la communication externe, créez un écouteur. Si vous devez utiliser le service ClusterIp, ajoutez d’autres ports à l’écouteur par défaut sans modifier aucun des paramètres existants.

Pour afficher ou modifier l’écouteur par défaut, suivez ces étapes.

Dans le Portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Dans la liste des écouteurs du broker, sélectionnez l’écouteur par défaut.
Passez en revue les paramètres de l’écouteur, mais évitez de modifier les paramètres existants. Au lieu de cela, créez un port et configurez-le en fonction des besoins.

Soyez prudent lorsque vous modifiez l'écouteur par défaut en utilisant Bicep. Ne modifiez pas les paramètres existants. Ajoutez plutôt d’autres ports à l’écouteur par défaut. L'exemple suivant montre comment ajouter un nouveau port à l'écouteur par défaut :

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource defaultListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    // Don't change the service name or service type
    serviceType: 'ClusterIp'
    serviceName: 'aio-broker'
    ports: [
      // Don't modify the default port 18883 settings
      {
        port: 18883
        authenticationRef: 'default'
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
            privateKey: {
              algorithm: 'Ec256'
              rotationPolicy: 'Always'
            }
          }
        }
      }
      // Add more ports here, like the following example
      {
        port: 1884
        protocol: 'Mqtt'
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI :

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Pour afficher la ressource BrokerListener par défaut, utilisez la commande suivante :

kubectl get brokerlistener default -n azure-iot-operations -o yaml

Le résultat devrait ressembler à cet exemple, avec la plupart des métadonnées supprimées pour plus de concision :

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: default
  namespace: azure-iot-operations
  ownerReferences:
  - apiVersion: mqttbroker.iotoperations.azure.com/v1
    kind: Broker
    name: default
spec:
  serviceType: ClusterIp
  serviceName: aio-broker
  ports:
  - port: 18883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: azure-iot-operations-aio-certificate-issuer
          kind: ClusterIssuer
          group: cert-manager.io
        privateKey:
          algorithm: Ec256
          rotationPolicy: Always

Pour ajouter un nouveau port 1883, sans TLS et sans authentification, à l'écouteur par défaut, utilisez la commande kubectl patch :

kubectl patch brokerlistener default -n azure-iot-operations --type='json' -p='[{"op": "add", "path": "/spec/ports/-", "value": {"port": 1883, "protocol": "Mqtt"}}]'

Éviter de modifier l’écouteur de répartiteur par défaut

Pour éviter de perturber la communication interne des opérations IoT, conservez l'écouteur par défaut inchangé et dédié à un usage interne. Pour la communication externe, créez un écouteur.

Étant donné que l'écouteur de courtier par défaut utilise le type de service ClusterIp et que vous ne pouvez avoir qu'un seul écouteur par type de service, ajoutez d'autres ports à l'écouteur par défaut sans modifier aucun des paramètres existants si vous devez utiliser le service ClusterIp.

Créer des écouteurs de broker

Pour créer un écouteur, spécifiez les paramètres suivants :

Nom : nom de l’écouteur. Ce nom est également le nom du service Kubernetes, sauf substitution.
Type de service : type du service Kubernetes. Consultez Type de service.
Ports : Liste des ports à écouter. Consultez Ports.
Nom du service (facultatif) : remplacez le nom du service Kubernetes. Consultez Nom du service.

Exemple : Créer un écouteur avec deux ports

Cet exemple montre comment créer un nouvel écouteur avec le type de service LoadBalancer. La ressource BrokerListener définit deux ports qui acceptent les connexions MQTT venant des clients.

Le premier port écoute sur le port 1883 sans TLS ni authentification. Cette configuration convient uniquement aux tests. N’utilisez pas cette configuration en production.
Le second port écoute sur le port 8883 avec TLS et authentification activés. Seuls les clients authentifiés avec un jeton de compte de service Kubernetes peuvent se connecter. Le protocole TLS est défini sur le mode automatique, à l’aide de cert-manager pour gérer le certificat de serveur à partir de l’émetteur par défaut. Cette configuration est plus proche d’une configuration de production.

Dans le Portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.

Sélectionnez Écouteur de l’Agent MQTT pour LoadBalancer>Créer.

Entrez les paramètres suivants :

Setting	Description
Nom	Nom de la ressource BrokerListener.
Nom du service	Nom du service Kubernetes. Laissez-le vide pour utiliser le nom de l’écouteur en tant que nom de service.
Type de service	LoadBalancer déjà sélectionné.

Sous Ports, entrez les paramètres suivants pour le premier port :

Setting Description

Port Entrez 1883.

Authentification Choisissez Aucun(e).

Autorisation Choisissez Aucun(e).

Protocol Choisissez MQTT.

TLS N'ajoutez rien.
Sélectionnez Ajouter une entrée de port pour ajouter un deuxième port et entrez les paramètres suivants :

Setting Description

Port Entrez 8883.

Authentification Choisissez la valeur par défaut.

Autorisation Choisissez Aucun(e).

Protocol Choisissez MQTT.

TLS Sélectionnez Ajouter.
Dans le volet de configuration TLS, entrez les paramètres suivants :

Setting Description

Mode TLS Choisissez Automatique.

Nom de l'émetteur Saisissez azure-iot-operations-aio-certificate-issuer.

Type d’émetteur Choisissez ClusterIssuer.

Conservez les valeurs par défaut pour les autres paramètres, puis sélectionnez Appliquer.
Sélectionnez Créer un écouteur.

Setting	Description
Port	Entrez 1883.
Authentification	Choisissez Aucun(e).
Autorisation	Choisissez Aucun(e).
Protocol	Choisissez MQTT.
TLS	N'ajoutez rien.

Setting	Description
Port	Entrez 8883.
Authentification	Choisissez la valeur par défaut.
Autorisation	Choisissez Aucun(e).
Protocol	Choisissez MQTT.
TLS	Sélectionnez Ajouter.

Setting	Description
Mode TLS	Choisissez Automatique.
Nom de l'émetteur	Saisissez `azure-iot-operations-aio-certificate-issuer`.
Type d’émetteur	Choisissez ClusterIssuer.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = '<LISTENER_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        port: 1883
        protocol: 'Mqtt'
      }
      {
        authenticationRef: 'default'
        port: 8883
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI :

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: <LISTENER_NAME>
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: LoadBalancer
  ports:
  - port: 1883
    protocol: Mqtt
  - port: 8883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
            name: azure-iot-operations-aio-certificate-issuer
            kind: ClusterIssuer
            group: cert-manager.io

Type de service

Chaque ressource BrokerListener est mappée à un service Kubernetes. Le type de service détermine la façon dont le répartiteur est exposé au réseau. Les types de service pris en charge sont les suivants :

ClusterIp : expose le répartiteur sur une adresse IP interne de cluster. Les clients peuvent se connecter au répartiteur à partir du cluster. Ce type de service par défaut est destiné à l'écouteur par défaut.
NodePort : expose le répartiteur sur l’adresse IP de chaque nœud à un port statique. Les clients peuvent se connecter au répartiteur à partir de l’extérieur du cluster. Ce type de service est utile pour le développement et les tests.
LoadBalancer : expose le répartiteur en externe. Le service reçoit une adresse IP externe que les clients peuvent utiliser pour se connecter au répartiteur. Ce type de service est le plus courant pour les déploiements de production.

Un seul écouteur par type de service

Un seul écouteur par type de service est autorisé. Si vous avez besoin d’une connectivité supplémentaire du même type de service, ajoutez d’autres ports à l’écouteur existant de ce type de service.

Nom du service

Le nom du service est le nom du service Kubernetes associé au répartiteur. S’il n’est pas spécifié, le nom de l’écouteur de répartiteur est utilisé comme nom de service. Le nom du service doit être unique dans l’espace de noms.

Conseil

Pour éviter toute surcharge de gestion, nous vous recommandons de laisser le nom du service vide. Le nom de l'auditeur est unique et vous pouvez l'utiliser pour identifier le service. Utilisez le nom du service comme remplacement uniquement lorsque vous ne pouvez pas nommer le service d’après l’écouteur.

Ports

Chaque écouteur peut avoir plusieurs ports, et chaque port peut avoir ses propres paramètres pour l’authentification, l’autorisation, le protocole et TLS.

Pour utiliser votre propre paramètre d’authentification ou d’autorisation pour un port, vous devez créer les ressources correspondantes avant de l’utiliser avec un écouteur. Pour plus d’informations, consultez Configurer l’authentification de l’Agent MQTT et Configurer l’autorisation de l’Agent MQTT.

Pour utiliser TLS, consultez les sections Configurer TLS avec la gestion automatique des certificats ou Configurer TLS avec la gestion manuelle des certificats.

Utiliser le même port pour tous les écouteurs

L’utilisation du même numéro de port sur différents écouteurs n’est pas prise en charge. Chaque numéro de port doit être unique au sein du courtier MQTT IoT Operations.

Par exemple, si vous avez un écouteur sur le port 1883, vous ne pouvez pas créer un autre écouteur avec le port 1883. De même, l’écouteur par défaut utilise le port 18883. Vous ne pouvez donc pas créer un autre écouteur avec le port 18883.

Prise en charge des WebSockets

Le courtier IoT Operations MQTT prend en charge MQTT sur WebSockets. Pour activer WebSockets, définissez le protocole sur WebSockets pour le port.

Configurer TLS avec la gestion automatique des certificats

Pour activer TLS avec la gestion automatique des certificats, spécifiez les paramètres TLS sur un port d’écouteur.

Vérifier l’installation du gestionnaire de certificats

Avec la gestion automatique des certificats, vous utilisez le gestionnaire de certificats pour gérer le certificat de serveur TLS. Par défaut, cert-manager est déjà installé aux côtés d’IoT Operations dans l’espace de noms cert-manager. Vérifiez l'installation avant de continuer.

Utilisez kubectl pour vérifier les pods qui correspondent aux étiquettes de l’application cert-manager.

kubectl get pods --namespace cert-manager -l 'app in (cert-manager,cainjector,webhook)'

NAME                                           READY   STATUS    RESTARTS       AGE
aio-cert-manager-64f9548744-5fwdd              1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-cainjector-6c7c546578-p6vgv   1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-webhook-7f676965dd-8xs28      1/1     Running   4 (145m ago)   4d20h

Si vous voyez les pods affichés comme prêts et en cours d’exécution, le gestionnaire de certificats est installé et prêt à être utilisé.

Conseil

Pour vérifier davantage l'installation, consultez la documentation de cert-manager pour vérifier l'installation. N’oubliez pas d’utiliser l’espace de noms cert-manager.

Créer un émetteur pour le certificat du serveur TLS

La ressource d'émetteur cert-manager définit comment les certificats sont émis automatiquement. Cert-manager prend en charge nativement plusieurs types d'émetteurs. Il prend également en charge un type externeissuer pour étendre les fonctionnalités au-delà des émetteurs pris en charge nativement. Vous pouvez utiliser un courtier MQTT avec n’importe quel type d’émetteur de gestionnaire de certificats.

Important

Lors du déploiement initial, IoT Operations est installé avec un émetteur par défaut pour les certificats de serveur TLS. Vous pouvez utiliser cet émetteur pour le développement et le test. Pour plus d'informations, consultez Autorité de certification racine (CA) par défaut et émetteur avec Azure IoT Operations. Les étapes suivantes ne sont nécessaires que si vous souhaitez utiliser un autre émetteur.

L’approche de création de l’émetteur est différente en fonction de votre scénario. Les sections suivantes répertorient des exemples pour vous aider à commencer.

Développement ou test
Production

L’émetteur de l’autorité de certification est utile pour le développement et le test. Il doit être configuré avec un certificat et une clé privée stockés dans un secret Kubernetes.

Configurer le certificat racine en tant que secret Kubernetes

Si vous disposez d’un certificat d’autorité de certification existant, créez un secret Kubernetes avec le certificat d’autorité de certification et les fichiers PEM de clé privée d’autorité de certification. Exécutez la commande suivante pour importer le certificat d’autorité de certification en tant que secret Kubernetes et ignorez la section suivante.

kubectl create secret tls test-ca --cert tls.crt --key tls.key -n azure-iot-operations

Si vous n’avez pas de certificat d’autorité de certification, cert-manager peut générer un certificat d’autorité de certification pour vous. L’utilisation de cert-manager pour générer un certificat d’autorité de certification racine est connue sous le nom de démarrage d’un émetteur d’autorité de certification à l’aide d’un certificat auto-signé.

Commencez par créer ca.yaml :

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-ca-issuer
  namespace: azure-iot-operations
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: selfsigned-ca-cert
  namespace: azure-iot-operations
spec:
  isCA: true
  commonName: test-ca
  secretName: test-ca
  issuerRef:
    # Must match Issuer name above
    name: selfsigned-ca-issuer
    # Must match Issuer kind above
    kind: Issuer
    group: cert-manager.io
  # Override default private key config to use an EC key
  privateKey:
    rotationPolicy: Always
    algorithm: ECDSA
    size: 256

Créez le certificat d’autorité de certification auto-signé avec la commande suivante :
```
kubectl apply -f ca.yaml
```

Cert-manager crée un certificat CA en utilisant ses valeurs par défaut. Vous pouvez modifier les propriétés de ce certificat en modifiant la spécification du certificat. Pour une liste des options valides, consultez la documentation de cert-manager.

Distribuer le certificat racine

L’exemple précédent stocke le certificat d’autorité de certification dans un secret Kubernetes appelé test-ca. Vous pouvez récupérer le certificat au format PEM à partir du secret et le stocker dans le fichier ca.crt avec la commande suivante :

kubectl get secret test-ca -n azure-iot-operations -o json | jq -r '.data["tls.crt"]' | base64 -d > ca.crt

Ce certificat doit être distribué et approuvé par tous les clients. Par exemple, utilisez l’indicateur --cafile pour un client Mosquitto.

Créer un émetteur basé sur un certificat d’autorité de certification

Le gestionnaire de certificats a besoin d’un émetteur basé sur le certificat d’autorité de certification généré ou importé à l’étape précédente. Créez le fichier suivant en tant que issuer-ca.yaml :

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: my-issuer
  namespace: azure-iot-operations
spec:
  ca:
    # Must match secretName of generated or imported CA cert
    secretName: test-ca

Créez l’émetteur avec la commande suivante :

kubectl apply -f issuer-ca.yaml

La commande précédente crée un émetteur pour émettre les certificats de serveur TLS. Notez le nom et le type de l’émetteur. Dans l’exemple, le nom est my-issuer et le type est Issuer. Ces valeurs sont définies dans la ressource BrokerListener ultérieurement.

Pour la production, consultez la documentation du gestionnaire de certificats pour voir l’émetteur qui vous convient le mieux. Par exemple, avec l’émetteur de coffre :

Déployez le coffre HashiCorp dans un environnement de choix, comme Kubernetes. Initialisez et descellez Vault en conséquence.
Créez et configurez le moteur de secrets PKI en important votre certificat d’autorité de certification.
Configurez Vault avec un rôle et une politique pour l’émission de certificats de serveur.

Le rôle suivant est un exemple. Notez que cela ExtKeyUsageServerAuth fait fonctionner le certificat du serveur :
```
vault write pki/roles/my-issuer \
  allow_any_name=true \
  client_flag=false \
  ext_key_usage=ExtKeyUsageServerAuth \
  no_store=true \
  max_ttl=240h
```
Exemple de stratégie pour le rôle :
```
path "pki/sign/my-issuer" {
  capabilities = ["create", "update"]
}
```
Configurez l'authentification entre cert-manager et Vault en utilisant une méthode de votre choix, comme SAT.
Configurez l'émetteur du coffre-fort du gestionnaire de certificats.

Activer la gestion automatique des certificats TLS pour un port

L'exemple suivant est une ressource BrokerListener qui active TLS sur le port 8884 avec gestion automatique des certificats.

Dans le Portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Sélectionnez ou créez un écouteur. Vous ne pouvez créer qu'un seul écouteur par type de service. Si vous avez déjà un écouteur du même type de service, vous pouvez ajouter d’autres ports à l’écouteur existant.

Vous pouvez ajouter des paramètres TLS à l'écouteur en sélectionnant TLS sur un port existant ou en ajoutant un nouveau port.

Entrez les paramètres suivants :

Setting	Description
Nom	Nom de la ressource BrokerListener. Saisissez `aio-broker-loadbalancer-tls`.
Port	Numéro de port sur lequel BrokerListener écoute les connexions MQTT. Entrez 8884.
Authentification	Les informations de référence sur les ressources d’authentification.
Autorisation	Les informations de référence sur les ressources d’autorisation.
TLS	Cliquez sur le bouton Ajouter.
Nom de l'émetteur	Nom de l’émetteur du gestionnaire de certificats. Obligatoire.
Type d’émetteur	Type de l’émetteur du gestionnaire de certificats. Obligatoire.
Groupe d’émetteurs	Groupe de l’émetteur du gestionnaire de certificats. Obligatoire.
Algorithme de clé privée	Algorithme de la clé privée.
Stratégie de rotation de clé privée	Stratégie de rotation de la clé privée.
Noms DNS	Autres noms de l’objet DNS pour le certificat.
Adresses IP	Adresses IP des autres noms de l’objet pour le certificat.
Nom du secret	Secret Kubernetes contenant un certificat client X.509.
Durée	La durée de vie totale du certificat du serveur TLS est par défaut de 90 jours.
Renouveler avant	Quand commencer le renouvellement du certificat.

Sélectionnez Appliquer pour enregistrer les paramètres TLS.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = 'aio-broker-loadbalancer-tls'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8884
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'my-issuer'
              kind: 'Issuer'
            }
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI :

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Modifiez le paramètre tls dans une ressource BrokerListener pour spécifier un port TLS et Issuer pour les front-ends.

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer
  ports:
  - port: 8884 # Avoid conflicts with default port 18883
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: my-issuer
          kind: Issuer

Une fois la ressource BrokerListener configurée, le courtier MQTT crée automatiquement un nouveau service avec le port spécifié et TLS activé.

Facultatif : Configurer les paramètres de certificat de serveur

Les seuls paramètres requis sont le nom Issuer et le type Issuer. Toutes les autres propriétés des certificats de serveur TLS générés sont choisies automatiquement. Cependant, le courtier MQTT permet de personnaliser certaines propriétés en suivant la même syntaxe que les certificats cert-manager. Par exemple, vous pouvez spécifier l’algorithme de clé privée et la stratégie de rotation. Ces paramètres se trouvent sous tls.certManagerCertificateSpec ou sur le volet de configuration TLS dans le Portail Microsoft Azure.

Pour obtenir la liste complète de ces paramètres, consultez les Informations de référence sur l’API CertManagerCertificateSpec de l’écouteur de répartiteur.

Vérifier le déploiement

Utilisez kubectl pour vérifier que le service associé à la ressource BrokerListener est en cours d’exécution. Dans l’exemple précédent, le nom du service est aio-broker-loadbalancer-tls et l’espace de noms est azure-iot-operations. La commande suivante vérifie l’état du service :

$ kubectl get service my-new-tls-listener -n azure-iot-operations
NAME                           TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
aio-broker-loadbalancer-tls    LoadBalancer   10.X.X.X        172.X.X.X     8884:32457/TCP   33s

Se connecter au répartiteur avec TLS

Une fois le certificat du serveur configuré, TLS est activé. Pour tester avec Mosquitto :

mosquitto_pub -h $HOST -p 8884 -V mqttv5 -i "test" -t "test" -m "test" --cafile ca.crt

L'argument --cafile active TLS sur le client Mosquitto et spécifie que le client doit faire confiance à tous les certificats de serveur émis par le fichier spécifique. Vous devez spécifier un fichier qui contient l’émetteur du certificat de serveur TLS configuré.

Remplacez $HOST par l’hôte approprié :

Si vous vous connectez depuis le même cluster, remplacez par le nom de service donné (my-new-tls-listener dans l'exemple) ou le service CLUSTER-IP.
Si vous vous connectez depuis l'extérieur du cluster, utilisez le service EXTERNAL-IP.

N’oubliez pas de spécifier les méthodes d’authentification si nécessaire.

Autorité de certification racine et émetteur par défaut

Pour vous aider à démarrer, IoT Operations est déployé avec un certificat CA « de démarrage rapide » par défaut et un émetteur pour les certificats de serveur TLS. Vous pouvez utiliser cet émetteur pour le développement et le test. Pour plus d’informations, voir AC racine par défaut et émetteur des certificats de serveur TLS.

Pour la production, vous devez configurer un émetteur d’autorité de certification avec un certificat d’une autorité de certification approuvée, comme décrit dans les sections précédentes.

Configurer TLS avec la gestion manuelle des certificats

Pour configurer manuellement un courtier MQTT pour utiliser un certificat TLS spécifique, spécifiez-le dans une ressource BrokerListener avec une référence à un secret Kubernetes et déployez-le à l'aide de kubectl. Cet article montre un exemple de configuration du protocole TLS avec des certificats auto-signés à des fins de test.

Créer une autorité de certification avec Step CLI

Step est un gestionnaire de certificats qui peut vous aider à démarrer rapidement lorsque vous créez et gérez votre propre autorité de certification privée.

Installez Step CLI et créez un certificat et une clé d’autorité de certification racine.
```
step certificate create --profile root-ca "Example Root CA" root_ca.crt root_ca.key
```

Créez un certificat d’autorité de certification intermédiaire et une clé signés par l’autorité de certification racine.

step certificate create --profile intermediate-ca "Example Intermediate CA" intermediate_ca.crt intermediate_ca.key \
--ca root_ca.crt --ca-key root_ca.key

Créer un certificat de serveur

Utilisez l’étape CLI pour créer un certificat de serveur à partir du certificat et de la clé de l’autorité de certification intermédiaire.

step certificate create mqtts-endpoint mqtts-endpoint.crt mqtts-endpoint.key \
--profile leaf \
--not-after 8760h \
--san mqtts-endpoint \
--san localhost \
--ca intermediate_ca.crt --ca-key intermediate_ca.key \
--no-password --insecure

Voici les noms alternatifs de sujet (SAN) mqtts-endpoint et localhost pour le frontend du courtier MQTT dans Kubernetes et les clients locaux, respectivement. Pour vous connecter via Internet, ajoutez un --san avec une adresse IP externe. Les indicateurs --no-password --insecure sont utilisés pour le test pour ignorer les invites de mot de passe et désactiver la protection par mot de passe pour la clé privée, car elles sont stockées dans un secret Kubernetes. Pour la production, utilisez un mot de passe et stockez la clé privée dans un emplacement sécurisé comme Azure Key Vault.

Exigences relatives à l’algorithme de clé de certificat

Les clés EC et RSA sont prises en charge, mais tous les certificats de la chaîne doivent utiliser le même algorithme de clé. Si vous importez vos propres certificats d’autorité de certification, vérifiez que le certificat de serveur utilise le même algorithme de clé que les autorités de certification.

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Créez une chaîne de certificats de serveur complète, où l’ordre des certificats est important. Le certificat du serveur est le premier du fichier et le certificat intermédiaire est le deuxième.
```
cat  mqtts-endpoint.crt intermediate_ca.crt  > server_chain.crt
```

Créez un secret Kubernetes avec la chaîne de certificats du serveur et la clé du serveur à l'aide de kubectl.

kubectl create secret tls server-cert-secret -n azure-iot-operations \
--cert server_chain.crt \
--key mqtts-endpoint.key

Activer la gestion manuelle des certificats TLS pour un port

L'exemple suivant montre une ressource BrokerListener qui active TLS sur le port 8884 avec une gestion manuelle des certificats.

Dans le Portail Azure, accédez à votre instance Opérations IoT.
Sous Composants, sélectionnez Agent MQTT.
Sélectionnez ou créez un écouteur. Vous ne pouvez créer qu'un seul écouteur par type de service. Si vous avez déjà un écouteur du même type de service, vous pouvez ajouter d’autres ports à l’écouteur existant. Pour suivre l’exemple, spécifiez le nom du service d’écouteur en tant que mqtts-endpoint.

Vous pouvez ajouter des paramètres TLS à l'écouteur en sélectionnant TLS sur un port existant ou en ajoutant un nouveau port.

Entrez les paramètres suivants :

Setting	Description
Port	Numéro de port sur lequel BrokerListener écoute les connexions MQTT. Obligatoire.
Authentification	Les informations de référence sur les ressources d’authentification.
Autorisation	Les informations de référence sur les ressources d’autorisation.
TLS	Cliquez sur le bouton Ajouter.
Nom du secret	Secret Kubernetes contenant un certificat client X.509.

Sélectionnez Appliquer pour enregistrer les paramètres TLS.

Modifiez le paramètre tls dans une ressource BrokerListener pour spécifier une configuration TLS manuelle référençant le secret Kubernetes. Notez le nom du secret utilisé pour le certificat du serveur TLS (server-cert-secret dans l'exemple précédent).

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerServiceName string = 'mqtts-endpoint'
param listenerName string = '<LISTENER_NAME>' // Match the SAN in the server certificate

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceName: listenerServiceName
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8885 // Avoid port conflict with default listener at 18883
        tls: {
          mode: 'Manual'
          manual: {
            secretRef: 'server-cert-secret'
          }
        }
      }
    ]
  }
}

Déployez le fichier Bicep à l’aide d’Azure CLI :

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: loadbalancer-tls
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer # Optional, defaults to clusterIP
  serviceName: mqtts-endpoint # Match the SAN in the server certificate
  ports:
  - port: 8885 # Avoid port conflict with default listener at 18883
    tls:
      mode: Manual
      manual:
        secretRef: server-cert-secret

Une fois la ressource BrokerListener créée, l’opérateur crée automatiquement un service Kubernetes et déploie l’écouteur. Vous pouvez vérifier l’état du service en exécutant kubectl get svc.

Se connecter au répartiteur avec TLS

Pour tester la connexion TLS avec le client Mosquitto, publiez un message et transmettez le certificat CA racine dans le paramètre --cafile.

mosquitto_pub -d -h localhost -p 8885 -i "my-client" -t "test-topic" -m "Hello" --cafile root_ca.crt

N'oubliez pas de spécifier des éléments tels que le nom d'utilisateur et le mot de passe si l'authentification du courtier MQTT est activée.

Client my-client sending CONNECT
Client my-client received CONNACK (0)
Client my-client sending PUBLISH (d0, q0, r0, m1, 'test-topic', ... (5 bytes))
Client my-client sending DISCONNECT

Conseil

Pour utiliser localhost, le port doit être disponible sur l’ordinateur hôte. par exemple kubectl port-forward svc/mqtts-endpoint 8885:8885 -n azure-iot-operations. Avec certaines distributions Kubernetes comme K3d, vous pouvez ajouter un port transféré avec k3d cluster edit $CLUSTER_NAME --port-add 8885:8885@loadbalancer.

Pour vous connecter au répartiteur, vous devez distribuer la racine de confiance, également connu sous le nom de pack d’approbation, à tous les clients. Dans ce cas, la racine de confiance est l’autorité de certification racine auto-signée créée par Step CLI. La distribution de la racine de confiance est requise pour que le client puisse vérifier la chaîne de certificats de serveur. Si vos clients MQTT sont des charges de travail sur le cluster Kubernetes, vous devez également créer un ConfigMap avec l'autorité de certification racine et le monter dans votre pod.

Utiliser une adresse IP externe pour le certificat de serveur

Pour se connecter à TLS sur Internet, le certificat du serveur du courtier MQTT doit avoir son nom d'hôte externe ou son adresse IP en tant que SAN. En production, ces informations sont généralement un nom DNS ou une adresse IP bien connue. Pendant le développement/test, vous ne savez peut-être pas quel nom d’hôte ou quelle adresse IP externe est attribué avant le déploiement. Pour résoudre ce problème, déployez d’abord l’écouteur sans le certificat du serveur, créez le certificat du serveur et le secret avec l’IP externe, puis importez le secret dans l’écouteur.

Si vous essayez de déployer l’exemple d’écouteur TLS manual-tls-listener mais que le secret Kubernetes référencé server-cert-secret n’existe pas, le service associé est créé, mais les pods ne démarrent pas. Le service est créé, car l’opérateur doit réserver l’adresse IP externe pour l’écouteur.

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

Ce comportement est attendu lors de l'importation du certificat du serveur. Les journaux du gestionnaire de santé mentionnent que le courtier MQTT attend le certificat du serveur.

kubectl logs -l app=health-manager -n azure-iot-operations

...
<6>2023-11-06T21:36:13.634Z [INFO] [1] - Server certificate server-cert-secret not found. Awaiting creation of secret.

Remarque

En règle générale, dans un système distribué, les journaux des pods ne sont pas déterministes et doivent être utilisés avec précaution. La bonne façon d’obtenir des informations comme celle-ci consiste à utiliser des événements Kubernetes et l’état des ressources personnalisées, qui se trouve dans le backlog. Considérez l’étape précédente comme solution de contournement temporaire.

Même si les pods frontaux ne sont pas en cours, l’adresse IP externe est déjà disponible.

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

À partir de là, suivez les mêmes étapes que celles indiquées précédemment pour créer un certificat de serveur avec cette adresse IP externe --san et créer le secret Kubernetes de la même manière. Une fois le secret créé, il est automatiquement importé dans l'écouteur.

Partager via

Communication sécurisée du courtier MQTT à l'aide de BrokerListener

BrokerListener par défaut

Éviter de modifier l’écouteur de répartiteur par défaut

Créer des écouteurs de broker

Exemple : Créer un écouteur avec deux ports

Type de service

Un seul écouteur par type de service

Nom du service

Ports

Utiliser le même port pour tous les écouteurs

Prise en charge des WebSockets

Configurer TLS avec la gestion automatique des certificats

Vérifier l’installation du gestionnaire de certificats

Créer un émetteur pour le certificat du serveur TLS

Configurer le certificat racine en tant que secret Kubernetes

Distribuer le certificat racine

Créer un émetteur basé sur un certificat d’autorité de certification

Activer la gestion automatique des certificats TLS pour un port

Facultatif : Configurer les paramètres de certificat de serveur

Vérifier le déploiement

Se connecter au répartiteur avec TLS

Autorité de certification racine et émetteur par défaut

Configurer TLS avec la gestion manuelle des certificats

Créer une autorité de certification avec Step CLI

Créer un certificat de serveur

Exigences relatives à l’algorithme de clé de certificat

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Activer la gestion manuelle des certificats TLS pour un port

Se connecter au répartiteur avec TLS

Utiliser une adresse IP externe pour le certificat de serveur

Commentaires

Ressources supplémentaires

Partager via

Communication sécurisée du courtier MQTT à l'aide de BrokerListener

BrokerListener par défaut

Éviter de modifier l’écouteur de répartiteur par défaut

Créer des écouteurs de broker

Exemple : Créer un écouteur avec deux ports

Type de service

Un seul écouteur par type de service

Nom du service

Ports

Utiliser le même port pour tous les écouteurs

Prise en charge des WebSockets

Configurer TLS avec la gestion automatique des certificats

Vérifier l’installation du gestionnaire de certificats

Créer un émetteur pour le certificat du serveur TLS

Configurer le certificat racine en tant que secret Kubernetes

Distribuer le certificat racine

Créer un émetteur basé sur un certificat d’autorité de certification

Activer la gestion automatique des certificats TLS pour un port

Facultatif : Configurer les paramètres de certificat de serveur

Vérifier le déploiement

Se connecter au répartiteur avec TLS

Autorité de certification racine et émetteur par défaut

Configurer TLS avec la gestion manuelle des certificats

Créer une autorité de certification avec Step CLI

Créer un certificat de serveur

Exigences relatives à l’algorithme de clé de certificat

Importer une chaîne de certificats de serveur en tant que secret Kubernetes

Activer la gestion manuelle des certificats TLS pour un port

Se connecter au répartiteur avec TLS

Utiliser une adresse IP externe pour le certificat de serveur

Contenu connexe

Commentaires

Ressources supplémentaires