Proteja a comunicação do Agente MQTT usando BrokerListener

Artigo
01/24/2025

Importante

Esta página inclui instruções para gerenciar componentes do serviço Operações do Azure IoT usando manifestos de implantação do Kubernetes, que estão em versão prévia. Esse recurso é fornecido com várias limitações, e não deve ser usado para cargas de trabalho 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.

Um recurso BrokerListener corresponde a um ponto de extremidade de rede que expõe o agente aos clientes pela rede. Você pode ter um ou mais recursos BrokerListener para cada agente, com várias portas e diferentes controles de acesso em cada um.

Cada porta BrokerListener pode ter suas próprias regras de autenticação e autorização que definem quem pode se conectar nessa porta do ouvinte e quais ações podem ser executadas no agente. Você pode usar os recursos BrokerAuthentication e BrokerAuthorization para especificar as políticas de controle de acesso para cada porta do ouvinte. Essa flexibilidade permite ajustar as permissões e funções para seus clientes MQTT com base em suas necessidades e casos de uso.

Dica

A implantação padrão do Agente MQTT é um serviço IP de cluster que exige que os clientes se conectem com o protocolo TLS (TLS) e se autentiquem com tokens de conta de serviço. Os clientes que se conectarem de fora do cluster precisam de configuração extra antes de poderem se conectar.

Os ouvintes do agente têm as seguintes características:

Nome: nome do ouvinte. Esse nome também é o nome do serviço kubernetes, a menos que substituído.
Tipo de serviço: você pode ter até três ouvintes, um por tipo de serviço. O ouvinte padrão é o tipo de serviço ClusterIp.
Portas: cada ouvinte dá suporte a várias portas. As portas não podem entrar em conflito com ouvintes diferentes.
Referências de autenticação e autorização: BrokerAuthentication e BrokerAuthorization são configurados por porta.
TLS: configuração TLS manual ou automática é aplicada por porta.
Protocolo: MQTT via WebSockets pode ser habilitado por porta.

Para uma lista de todas as configurações disponíveis, confira a Referência de API de Ouvinte do Broker.

BrokerListener padrão

Ao implantar as Operações do Azure IoT, a implantação cria um recurso BrokerListener chamado padrão. Esse ouvinte é utilizado para comunicação interna criptografada entre os componentes das Operações do IoT. O ouvinte padrão faz parte do agente padrão.

Ele expõe um serviço ClusterIp na porta 18883.
Exige que os clientes usem autenticação de conta de serviço do Kubernetes.
Ele tem um certificado TLS gerenciado automaticamente.
Não configura nenhuma política de autorização de cliente.

Cuidado

Para evitar a interrupção da comunicação interna das Operações do IoT, mantenha o ouvinte padrão inalterado e dedicado para uso interno. Para comunicação externa, criar um novo ouvinte. Se precisar usar o serviço ClusterIp, adicione mais portas ao ouvinte padrão sem alterar nenhuma das configurações existentes.

Para exibir ou editar o ouvinte padrão, siga estas etapas.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Na lista de ouvintes do agente, selecione o ouvinte padrão.
Examine as configurações do ouvinte, mas evite modificar qualquer uma das configurações existentes. Em vez disso, crie uma nova porta e configure-a conforme necessário.

Tenha cuidado ao modificar o ouvinte padrão usando Bicep. Não altere as configurações existentes. Em vez disso, adicione mais portas ao ouvinte padrão. O exemplo a seguir mostra como adicionar uma nova porta ao ouvinte padrão:

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'
      }
    ]
  }
}

Implantar o arquivo Bicep usando a CLI do Azure:

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

Para exibir o recurso BrokerListener padrão, use o seguinte comando:

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

A saída deve ser semelhante a este exemplo, com a maioria dos metadados removidos para facilitar a leitura:

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

Para adicionar uma nova porta 1883, sem TLS e com autenticação desativada, ao ouvinte padrão, use o comando kubectl patch:

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

Evite modificar o ouvinte de agente padrão

Para evitar a interrupção da comunicação interna das Operações do IoT, mantenha o ouvinte padrão inalterado e dedicado para uso interno. Para comunicação externa, criar um novo ouvinte.

Como o ouvinte padrão do agente usa o tipo de serviço ClusterIp e você pode ter apenas um ouvinte por tipo de serviço, adicione mais portas ao ouvinte padrão sem alterar nenhuma das configurações existentes se precisar usar o serviço ClusterIp.

Criar ouvintes do agente

Para criar um ouvinte, especifique as seguintes configurações:

Nome: nome do ouvinte. Esse nome também é o nome do serviço kubernetes, a menos que substituído.
Tipo de serviço: tipo do serviço Kubernetes. Consulte o Tipo de serviço.
Portas: Lista de portas para escuta. Confira Portas.
Nome do serviço (opcional): Substituir o nome do serviço Kubernetes. Consulte Nome do serviço.

Exemplo: criar um ouvinte com duas portas

Este exemplo mostra como criar um ouvinte com o tipo de serviço LoadBalancer. O recurso BrokerListener define duas portas que aceitam conexões MQTT de clientes.

A primeira porta escuta na porta 1883 sem TLS e autenticação. Essa configuração é adequada apenas para testes. Não use essa configuração em produção.
A segunda porta escuta na porta 8883 com TLS e autenticação habilitada. Somente clientes autenticados com um token de conta de serviço do Kubernetes podem se conectar. O TLS é definido como modo automático, usando o gerenciador de certificados para gerenciar o certificado do servidor do emissor padrão. Essa configuração está mais próxima de uma configuração de produção.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.

Selecione Ouvinte do agente MQTT para LoadBalancer>Criar.

Digite as seguintes configurações:

Configuração	Descrição
Nome	Nome do recurso BrokerListener.
Nome do serviço	Nome do serviço kubernetes. Deixe vazio para usar o nome do ouvinte como nome de serviço.
Tipo de serviço	LoadBalancer já selecionado.

Em Portas, insira as seguintes configurações para a primeira porta:

Configuração Descrição

Porta Insira 1883.

Autenticação Escolha Nenhuma.

Autorização Escolha Nenhuma.

Protocolo Escolha MQTT.

TLS Não adicione.
Selecione Adicionar entrada de porta para adicionar uma segunda porta e insira as seguintes configurações:

Configuração Descrição

Porta Insira 8883.

Autenticação Escolha padrão.

Autorização Escolha Nenhuma.

Protocolo Escolha MQTT.

TLS Selecione Adicionar.
No painel Configuração de TLS, insira as seguintes configurações:

Configuração Descrição

Modo TLS Escolha Automático.

Nome do emissor Digite azure-iot-operations-aio-certificate-issuer.

Tipo de emissor Escolha ClusterIssuer.

Deixe outras configurações como padrão e selecione Aplicar.
Selecione Criar ouvinte.

Configuração	Descrição
Porta	Insira 1883.
Autenticação	Escolha Nenhuma.
Autorização	Escolha Nenhuma.
Protocolo	Escolha MQTT.
TLS	Não adicione.

Configuração	Descrição
Porta	Insira 8883.
Autenticação	Escolha padrão.
Autorização	Escolha Nenhuma.
Protocolo	Escolha MQTT.
TLS	Selecione Adicionar.

Configuração	Descrição
Modo TLS	Escolha Automático.
Nome do emissor	Digite `azure-iot-operations-aio-certificate-issuer`.
Tipo de emissor	Escolha 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'
            }
          }
        }
      }
    ]
  }
}

Implantar o arquivo Bicep usando a CLI do Azure:

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

Tipo de serviço

Cada recurso BrokerListener é mapeado para um serviço Kubernetes. O tipo de serviço determina como o agente é exposto à rede. Os tipos de serviço com suporte são:

ClusterIp: expõe o agente em um IP interno do cluster. Os clientes podem se conectar ao agente de dentro do cluster. Esse tipo de serviço padrão é para o ouvinte padrão.
NodePort: expõe o agente no IP de cada nó em uma porta estática. Os clientes podem se conectar ao agente de fora do cluster. Esse tipo de serviço é útil para desenvolvimento e teste.
LoadBalancer: expõe o agente externamente. O serviço recebe um endereço IP externo que os clientes podem usar para se conectar ao agente. Esse tipo de serviço é o mais comum para implantações de produção.

Apenas um ouvinte por tipo de serviço

Somente um ouvinte por tipo de serviço é permitido. Se você precisar de mais conectividade do mesmo tipo de serviço, adicione mais portas ao ouvinte existente desse tipo de serviço.

Nome do serviço

O nome do serviço é o nome do serviço Kubernetes associado ao agente. Se não for especificado, o nome do ouvinte do agente será usado como o nome do serviço. O nome do serviço deve ser exclusivo dentro do namespace.

Dica

Para evitar sobrecarga de gerenciamento, recomendamos que você deixe o nome do serviço vazio. O nome do ouvinte é exclusivo e pode ser utilizado para identificar o serviço. Use o nome do serviço como uma substituição somente quando você não puder nomear o serviço após o ouvinte.

Portos

Cada ouvinte pode ter várias portas e cada porta pode ter suas próprias configurações para autenticação, autorização, protocolo e TLS.

Para usar sua própria configuração de autenticação ou autorização para uma porta, você deve criar os recursos correspondentes antes de usá-los com um ouvinte. Para obter mais informações, consulte Configurar a autenticação do agente MQTT e configurar a autorização do agente MQTT.

Para usar o TLS, confira as seções Configurar TLS com gerenciamento automático de certificado ou Configurar TLS com gerenciamento manual de certificado.

Usar a mesma porta em ouvintes

Não há suporte para o uso do mesmo número de porta entre ouvintes diferentes. Cada número de porta deve ser exclusivo no Agente MQTT de Operações de IoT.

Por exemplo, se você tiver um ouvinte usando a porta 1883, não poderá criar outro ouvinte com a porta 1883. Da mesma forma, o ouvinte padrão usa a porta 18883, para que você não possa criar outro ouvinte com a porta 18883.

Suporte a WebSockets

O Agente MQTT de Operações de IoT dá suporte a MQTT sobre WebSockets. Para habilitar WebSockets, defina o protocolo para WebSockets para a porta.

Configurar o TLS com o gerenciamento automático de certificados

Para habilitar o TLS com o gerenciamento automático de certificados, especifique as configurações do TLS em uma porta de ouvinte.

Verificar a instalação do cert-manager

Com o gerenciamento automático de certificados, você usa o cert-manager para gerenciar o certificado do servidor TLS. Por padrão, o cert-manager já está instalado junto com as Operações de IoT no namespace cert-manager. Verifique a instalação antes de prosseguir.

Use o kubectl para verificar os pods que correspondem aos rótulos do aplicativo 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

Se você estiver vendo os pods aparecerem como prontos e em execução, isso significa que o cert-manager está instalado e pronto para uso.

Dica

Para verificar ainda mais a instalação, confira a documentação do cert-manager para verificar a instalação. Lembre-se de usar o namespace de cert-manager.

Crie um emissor para o certificado do servidor TLS

O recurso emissor do cert-manager define como os certificados são emitidos automaticamente. O Cert-manager dá suporte a vários tipos de emissores nativamente. Ele também dá suporte a um tipo externo issuer para estender a funcionalidade além dos emissores com suporte nativo. Você pode usar um Agente MQTT com qualquer tipo de emissor do cert-manager.

Importante

Durante a implantação inicial, as Operações de IoT são instaladas com um emissor padrão para certificados de servidor TLS. Você pode usar esse emissor para desenvolvimento e testes. Para obter mais informações, confira Autoridade de Certificação (CA) raiz padrão e emissor com Operações de IoT do Azure. As etapas a seguir são obrigatórias somente se você quiser usar um emissor diferente.

A abordagem para criar o emissor é diferente dependendo da sua conjuntura. As seções a seguir listam exemplos que ajudarão você a começar.

Desenvolvimento ou testes
Produção

O emissor de AC é útil para desenvolvimento e testes. Precisa ser configurado com um certificado e uma chave privada armazenada em um segredo do Kubernetes.

Configurar o certificado raiz como um segredo do Kubernetes

Se você tiver um certificado de autoridade de certificação existente, crie um segredo do Kubernetes com o certificado de AC e os arquivos PEM de chave privada da AC. Execute o comando a seguir para importar o certificado de autoridade de certificação como um segredo do Kubernetes e ignorar a próxima seção.

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

Se você não tiver um certificado de autoridade de certificação, o gerenciador de certificados poderá gerar um certificado de autoridade de certificação para você. O processo de usar o cert-manager para gerar um certificado de AC é conhecido como bootstrapping (começar do zero) um emissor de AC com um certificado autoassinado.

Comece criando 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

Crie o certificado de AC autoassinado com o seguinte comando:
```
kubectl apply -f ca.yaml
```

O Cert-manager cria um certificado de autoridade de certificação usando seus padrões. Você pode alterar as propriedades deste certificado modificando a especificação do Certificado. Para obter uma lista de opções válidas, confira a documentação do cert-manager.

Distribuir o certificado raiz

O exemplo anterior armazena o certificado de AC em um segredo do Kubernetes chamado test-ca. Você pode recuperar o certificado no formato PEM do segredo e armazená-lo no arquivo ca.crt com o seguinte comando:

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

Esse certificado precisa ser distribuído e ser considerado confiável por todos os clientes. Por exemplo, use o sinalizador --cafile para um cliente Mosquitto.

Criar um emissor baseado no certificado de AC

O cert-manager precisa de um emissor baseado no certificado de AC gerado ou importado na etapa anterior. Crie o seguinte arquivo como 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

Crie o emissor com o seguinte comando:

kubectl apply -f issuer-ca.yaml

O comando anterior cria um emissor para emitir certificados de servidor TLS. Anote o nome e o tipo do emissor. No exemplo, o nome é my-issuer e o tipo é Issuer. Esses valores serão configurados no recurso BrokerListener mais tarde.

Para a produção, verifique a documentação do cert-manager para ver qual emissor funciona melhor para você. Por exemplo, com o Emissor do cofre:

Implantar o HashiCorp Vault em um ambiente de escolha, como kubernetes. Inicializar e desselar o Cofre adequadamente.
Crie e configure o mecanismo de segredos de PKI importando seu certificado de AC.
Configure o Cofre com uma função e uma política para emissão de certificados de servidor.

A função a seguir é um exemplo. Observe que ExtKeyUsageServerAuth faz o certificado do servidor funcionar:
```
vault write pki/roles/my-issuer \
  allow_any_name=true \
  client_flag=false \
  ext_key_usage=ExtKeyUsageServerAuth \
  no_store=true \
  max_ttl=240h
```
Exemplo de política para a função:
```
path "pki/sign/my-issuer" {
  capabilities = ["create", "update"]
}
```
Configure a autenticação entre o cert-manager e o Cofre usando um método de sua escolha, como SAT.
Configurar o emissor do Cofre do cert-manager.

Habilitar o gerenciamento automático de certificado TLS para uma porta

O exemplo a seguir é um recurso BrokerListener que habilita o TLS na porta 8884 com gerenciamento automático de certificados.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecionar ou criar um ouvinte. Você pode criar apenas um ouvinte por tipo de serviço. Se você já tiver um ouvinte do mesmo tipo de serviço, poderá adicionar mais portas ao ouvinte existente.

Você pode adicionar configurações de TLS ao ouvinte selecionando TLS em uma porta existente ou adicionando uma nova porta.

Digite as seguintes configurações:

Configuração	Descrição
Nome	Nome do recurso BrokerListener. Digite `aio-broker-loadbalancer-tls`.
Porta	Número da porta no qual o BrokerListener escuta conexões MQTT. Insira 8884.
Autenticação	A referência de recurso de autenticação.
Autorização	A referência de recurso da autorização.
TLS	Selecione o botão Adicionar.
Nome do emissor	Nome do emissor do cert-manager. Obrigatória.
Tipo de emissor	Tipo de emissor do cert-manager. Obrigatória.
Grupo emissor	Grupo do emissor do cert-manager. Obrigatória.
Algoritmo de chave privada	Algoritmo para a chave privada.
Política de rotação de chave privada	Política para girar a chave privada.
Nomes de DNS	Nomes alternativos da entidade DNS para o certificado.
Endereços IP	Endereços IP dos nomes alternativos da entidade para o certificado.
Nome secreto	Segredo do Kubernetes que contém um certificado de cliente X.509.
Duration	A vida útil total do certificado de servidor TLS é padrão de 90 dias.
Renovar antes de	Quando começar a renovar o certificado.

Selecione Aplicar para salvar as configurações do 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'
            }
          }
        }
      }
    ]
  }
}

Implantar o arquivo Bicep usando a CLI do Azure:

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

Modifique a configuração tls em um recurso BrokerListener para especificar uma porta TLS e Issuer para os 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

Depois que o recurso BrokerListener for configurado, o Agente MQTT criará automaticamente um novo serviço com a porta especificada e TLS habilitado.

Opcional: configurar parâmetros de certificado de servidor

Os únicos parâmetros obrigatórios são Issuer nome e Issuer tipo. Todas as outras propriedades dos certificados de servidor TLS gerados são escolhidas automaticamente. No entanto, o Agente MQTT permite que certas propriedades sejam personalizadas seguindo a mesma sintaxe dos certificados do cert-manager. Por exemplo, você pode especificar o algoritmo de chave privada e a política de rotação. Essas configurações estão em tls.certManagerCertificateSpec ou no painel Configuração de TLS no portal do Azure.

Para obter uma lista completa dessas configurações, consulte Referência da API CertManagerCertificateSpec do Broker Listener.

Verificar a implantação

Use o kubectl para verificar se o serviço associado ao recurso BrokerListener está em execução. No exemplo anterior, o nome do serviço é aio-broker-loadbalancer-tls e o namespace é azure-iot-operations. O comando a seguir verifica o status do serviço:

$ 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

Conectar-se ao agente com TLS

Depois que o certificado do servidor for configurado, o TLS será habilitado. Para testar com Mosquitto:

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

O argumento --cafile habilita o TLS no cliente Mosquitto e especifica que o cliente deve confiar em todos os certificados de servidor emitidos pelo arquivo específico. Você precisa especificar um arquivo que contenha o emissor do certificado do servidor TLS configurado.

Substitua $HOST pelo host apropriado:

Se você estiver se conectando dentro do mesmo cluster, substitua pelo nome do serviço fornecido (my-new-tls-listener no exemplo) ou pelo CLUSTER-IP do serviço.
Se você estiver se conectando de fora do cluster, use o EXTERNAL-IP do serviço.

Lembre-se de especificar os métodos de autenticação, se necessário.

AC raiz padrão e emissor

Para ajudar você a começar, as Operações de IoT são implantadas com um certificado de autoridade de certificação "início rápido" padrão e emissor para certificados de servidor TLS. Você pode usar esse emissor para desenvolvimento e testes. Para obter mais informações, consulte Autoridade de certificação raiz padrão e emissor para certificados de servidor TLS.

Para a produção, você precisa configurar um emissor de AC com um certificado de uma AC confiável, conforme descrito nas seções anteriores.

Configurar o TLS com o gerenciamento manual de certificados

Para configurar manualmente um Agente MQTT para usar um certificado TLS específico, especifique-o em um recurso BrokerListener com uma referência a um segredo do Kubernetes e implante-o usando kubectl. Este artigo mostra um exemplo que configura o TLS com certificados autoassinados para teste.

Criar uma autoridade de certificação com a CLI do Step

Step é um gerenciador de certificados que pode colocar você em funcionamento rapidamente quando você cria e gerencia sua própria autoridade de certificação privada.

Instale a CLI do Step e crie um certificado e uma chave de autoridade de certificação raiz.
```
step certificate create --profile root-ca "Example Root CA" root_ca.crt root_ca.key
```

Crie um certificado de autoridade intermediária e uma chave assinada pela AC raiz.

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

Criar um certificado do servidor

Use o CLI do Step para criar um certificado de servidor a partir do certificado e da chave da autoridade de certificação intermediária.

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

Aqui, mqtts-endpoint e localhost são os Nomes Alternativos de Assunto (SANs) para o front-end do Agente MQTT no Kubernetes e clientes locais, respectivamente. Para se conectar pela Internet, adicione um --san com um IP externo. Os sinalizadores --no-password --insecure são usados para testes para ignorar prompts de senha e desabilitar a proteção de senha para a chave privada porque ela é armazenada em um segredo do Kubernetes. Para produção, use uma senha e armazene a chave privada em um local seguro como o Azure Key Vault.

Requisitos de algoritmo de chave de certificado

Há suporte para chaves EC e RSA, mas todos os certificados na cadeia devem usar o mesmo algoritmo de chave. Se você importar seus próprios certificados de AC, verifique se o certificado do servidor usa o mesmo algoritmo de chave que as ACs.

Importar cadeia de certificados do servidor como um segredo do Kubernetes

Crie uma cadeia completa de certificados do servidor, na qual a ordem dos certificados é importante. O certificado do servidor é o primeiro no arquivo e o intermediário é o segundo.
```
cat  mqtts-endpoint.crt intermediate_ca.crt  > server_chain.crt
```

Crie um segredo do Kubernetes com a cadeia de certificados do servidor e a chave do servidor usando kubectl.

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

Habilitar o gerenciamento manual de certificados TLS para uma porta

O exemplo a seguir mostra um recurso BrokerListener que habilita o TLS na porta 8884 com gerenciamento manual de certificados.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecionar ou criar um ouvinte. Você pode criar apenas um ouvinte por tipo de serviço. Se você já tiver um ouvinte do mesmo tipo de serviço, poderá adicionar mais portas ao ouvinte existente. Para seguir o exemplo, especifique o nome do serviço do ouvinte como mqtts-endpoint.

Você pode adicionar configurações de TLS ao ouvinte selecionando TLS em uma porta existente ou adicionando uma nova porta.

Digite as seguintes configurações:

Configuração	Descrição
Porta	Número da porta no qual o BrokerListener escuta conexões MQTT. Obrigatória.
Autenticação	A referência de recurso de autenticação.
Autorização	A referência de recurso da autorização.
TLS	Selecione o botão Adicionar.
Nome secreto	Segredo do Kubernetes que contém um certificado de cliente X.509.

Selecione Aplicar para salvar as configurações do TLS.

Modifique a configuração tls em um recurso BrokerListener para especificar a configuração manual do TLS referenciando o segredo do Kubernetes. Observe o nome do segredo utilizado para o certificado do servidor TLS (server-cert-secret no exemplo anterior).

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'
          }
        }
      }
    ]
  }
}

Implantar o arquivo Bicep usando a CLI do Azure:

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

Depois que o recurso BrokerListener for criado, o operador criará automaticamente um serviço do Kubernetes e implantará o ouvinte. Você pode verificar o status do serviço executando kubectl get svc.

Conectar-se ao agente com o TLS

Para testar a conexão TLS com o cliente Mosquitto, publique uma mensagem e passe o certificado da AC raiz no parâmetro --cafile.

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

Lembre-se de especificar itens como nome de usuário e senha se a autenticação do Agente MQTT estiver habilitada.

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

Dica

Para usar o localhost, a porta deve estar disponível no computador host. Um exemplo é kubectl port-forward svc/mqtts-endpoint 8885:8885 -n azure-iot-operations. Com algumas distribuições do Kubernetes, como k3d, você pode adicionar uma porta encaminhada com k3d cluster edit $CLUSTER_NAME --port-add 8885:8885@loadbalancer.

Para se conectar ao agente, você precisa distribuir a raiz de confiança, também conhecida como pacote de confiança, para todos os clientes. Neste caso, a raiz de confiança é a AC raiz autoassinada criada pela CLI do Step. A distribuição da raiz de confiança é necessária para que o cliente verifique a cadeia de certificados do servidor. Se os clientes MQTT forem cargas de trabalho no cluster do Kubernetes, você também precisará criar um ConfigMap com a AC raiz e montá-lo no pod.

Usar IP externo para o certificado do servidor

Para conectar com TLS pela Internet, o certificado do servidor do Agente MQTT deve ter seu nome de host externo ou endereço IP como uma SAN. Em produção, essas informações geralmente são um nome DNS ou um endereço IP conhecido. Durante o desenvolvimento/teste, talvez você não saiba qual nome de host ou IP externo é atribuído antes da implantação. Para resolver esse problema, implante o ouvinte sem o certificado do servidor primeiro, crie o certificado do servidor e o segredo com o IP externo e importe o segredo para o ouvinte.

Se você tentar implantar o ouvinte TLS de exemplo manual-tls-listener, mas o segredo do Kubernetes referenciado server-cert-secret não existir, o serviço associado será criado, mas os pods não iniciarão. O serviço é criado porque o operador precisa reservar o IP externo para o ouvinte.

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

Esse comportamento é esperado enquanto importamos o certificado do servidor. Os logs do Gerenciador de Integridade mencionam que o Agente MQTT está aguardando o certificado do servidor.

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.

Observação

Geralmente, em um sistema distribuído, os logs de pods não são determinísticos e devem ser usados com cuidado. A maneira correta de informações como essa serem exibidas é por meio de eventos do Kubernetes e do status do recurso personalizado, que está na lista de pendências. Considere a etapa anterior como uma solução alternativa temporária.

Mesmo que os pods de front-end não estejam ativos, o IP externo já está disponível.

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

A partir daqui, siga as mesmas etapas mostradas anteriormente para criar um certificado de servidor com este IP externo em --san e criar o segredo do Kubernetes da mesma forma. Depois que o segredo for criado, ele será importado automaticamente para o ouvinte.

Compartilhar via

Proteja a comunicação do Agente MQTT usando BrokerListener

BrokerListener padrão

Evite modificar o ouvinte de agente padrão

Criar ouvintes do agente

Exemplo: criar um ouvinte com duas portas

Tipo de serviço

Apenas um ouvinte por tipo de serviço

Nome do serviço

Portos

Usar a mesma porta em ouvintes

Suporte a WebSockets

Configurar o TLS com o gerenciamento automático de certificados

Verificar a instalação do cert-manager

Crie um emissor para o certificado do servidor TLS

Configurar o certificado raiz como um segredo do Kubernetes

Distribuir o certificado raiz

Criar um emissor baseado no certificado de AC

Habilitar o gerenciamento automático de certificado TLS para uma porta

Opcional: configurar parâmetros de certificado de servidor

Verificar a implantação

Conectar-se ao agente com TLS

AC raiz padrão e emissor

Configurar o TLS com o gerenciamento manual de certificados

Criar uma autoridade de certificação com a CLI do Step

Criar um certificado do servidor

Requisitos de algoritmo de chave de certificado

Importar cadeia de certificados do servidor como um segredo do Kubernetes

Habilitar o gerenciamento manual de certificados TLS para uma porta

Conectar-se ao agente com o TLS

Usar IP externo para o certificado do servidor

Comentários

Recursos adicionais

Compartilhar via

Proteja a comunicação do Agente MQTT usando BrokerListener

BrokerListener padrão

Evite modificar o ouvinte de agente padrão

Criar ouvintes do agente

Exemplo: criar um ouvinte com duas portas

Tipo de serviço

Apenas um ouvinte por tipo de serviço

Nome do serviço

Portos

Usar a mesma porta em ouvintes

Suporte a WebSockets

Configurar o TLS com o gerenciamento automático de certificados

Verificar a instalação do cert-manager

Crie um emissor para o certificado do servidor TLS

Configurar o certificado raiz como um segredo do Kubernetes

Distribuir o certificado raiz

Criar um emissor baseado no certificado de AC

Habilitar o gerenciamento automático de certificado TLS para uma porta

Opcional: configurar parâmetros de certificado de servidor

Verificar a implantação

Conectar-se ao agente com TLS

AC raiz padrão e emissor

Configurar o TLS com o gerenciamento manual de certificados

Criar uma autoridade de certificação com a CLI do Step

Criar um certificado do servidor

Requisitos de algoritmo de chave de certificado

Importar cadeia de certificados do servidor como um segredo do Kubernetes

Habilitar o gerenciamento manual de certificados TLS para uma porta

Conectar-se ao agente com o TLS

Usar IP externo para o certificado do servidor

Conteúdo relacionado

Comentários

Recursos adicionais