Proteja a comunicação do broker MQTT usando o BrokerListener

Artigo
11/20/2024

Importante

Esta página inclui instruções para gerenciar componentes do Azure IoT Operations usando manifestos de implantação do Kubernetes, que está em visualização. Esse recurso é fornecido com várias limitações e não deve ser usado para cargas de trabalho de produção.

Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

Um BrokerListener corresponde a um ponto de extremidade de rede que expõe o broker aos clientes pela rede. Você pode ter um ou mais recursos BrokerListener para cada Broker, com várias portas e controle de acesso diferente em cada uma delas.

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

Gorjeta

A implantação padrão do broker MQTT é um serviço IP de cluster que requer que os clientes se conectem com TLS e se autentiquem com tokens de conta de serviço. Os clientes que se conectam de fora do cluster precisam de configuração extra antes de poderem se conectar.

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

Nome: Nome do ouvinte. Esse nome também é o nome do serviço Kubernetes, a menos que seja 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 ClusterIpde serviço .
Portas: cada ouvinte suporta várias portas. As portas não podem entrar em conflito entre ouvintes diferentes.
Referências de autenticação e autorização: BrokerAuthentication e BrokerAuthorization são configurados por porta.
TLS: A configuração TLS manual ou automática é aplicada por porta.
Protocolo: MQTT sobre WebSockets pode ser ativado por porta.

Para obter uma lista de todas as configurações disponíveis, consulte a referência da API do Broker Listener.

BrokerListener padrão

Quando você implanta o Azure IoT Operations, a implantação cria um recurso BrokerListener chamado default. Esse ouvinte é usado para comunicação interna criptografada entre os componentes do Azure IoT Operations. O ouvinte padrão faz parte do Broker padrão.

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

Atenção

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

Para visualizar ou editar o ouvinte padrão:

No portal do Azure, navegue até sua instância de Operações IoT.
Em Componentes, selecione MQTT Broker.
Na lista de ouvintes do broker, selecione o ouvinte padrão .
Revise 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 o 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'
      }
    ]
  }
}

Implante 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 esta, com a maioria dos metadados removidos por brevidade:

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 autenticação desativada para o ouvinte padrão, use o kubectl patch comando:

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 do broker padrão

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

Como o ouvinte do broker padrão 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 novos ouvintes de corretor

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

Nome: Nome do ouvinte. Esse nome também é o nome do serviço Kubernetes, a menos que seja substituído.
Tipo de serviço: Tipo do serviço Kubernetes. Consulte Tipo de serviço.
Portas: Lista de portas nas quais escutar. Veja Portos.
(Opcional) Nome do serviço: substitua o nome do serviço Kubernetes. Consulte Nome do serviço.

Exemplo: Criar um novo ouvinte com duas portas

Este exemplo mostra como criar um novo ouvinte com o tipo de serviço de balanceador de carga. 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. Esta configuração é adequada apenas para testes. Não use essa configuração na produção.
A segunda porta escuta na porta 8883 com TLS e autenticação habilitados. Somente clientes autenticados com um token de conta de serviço Kubernetes podem se conectar. TLS é definido para o modo automático, usando cert-manager para gerenciar o certificado do servidor a partir do emissor padrão. Esta configuração está mais próxima de uma configuração de produção.

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

Selecione o ouvinte do broker MQTT para LoadBalancer>Create.

Introduza as seguintes definições:

Definição	Description
Name	Nome do recurso BrokerListener.
Nome do serviço	Nome do serviço Kubernetes. Deixe em branco para usar o nome do ouvinte como nome do serviço.
Tipo de serviço	LoadBalancer já selecionado.

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

Definição Descrição

Porta Digite 1883

Autenticação Selecione Nenhum

Autorização Selecione Nenhum

Protocolo Escolha MQTT

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

Definição Descrição

Porta Digite 8883

Autenticação Escolha o padrão

Autorização Selecione Nenhum

Protocolo Escolha MQTT

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

Definição Descrição

Modo TLS Escolha Automático

Nome do emissor Introduzir azure-iot-operations-aio-certificate-issuer

Tipo de emitente Escolha ClusterIssuer

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

Definição	Descrição
Porta	Digite 1883
Autenticação	Selecione Nenhum
Autorização	Selecione Nenhum
Protocolo	Escolha MQTT
TLS	Não adicionar

Definição	Descrição
Porta	Digite 8883
Autenticação	Escolha o padrão
Autorização	Selecione Nenhum
Protocolo	Escolha MQTT
TLS	Selecione Adicionar

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

Implante 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 BrokerListener mapeia para um serviço Kubernetes. O tipo de serviço determina como o broker é exposto à rede. Os tipos de serviço suportados são:

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

Apenas um ouvinte por tipo de serviço

Apenas 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 broker. Se não for especificado, o nome do ouvinte do broker será usado como o nome do serviço. O nome do serviço deve ser exclusivo dentro do namespace.

Gorjeta

Para evitar sobrecarga de gerenciamento, recomendamos deixar o nome do serviço vazio. O nome do ouvinte é exclusivo e pode ser usado para identificar o serviço. Use o nome do serviço como uma substituição somente quando não for possível nomear o serviço após o ouvinte.

Portas

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á-la 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, consulte as seções Configurar TLS com gerenciamento automático de certificados ou Configurar TLS com gerenciamento manual de certificados.

Usando a mesma porta entre ouvintes

Não há suporte para o uso do mesmo número de porta em ouvintes diferentes. Cada número de porta deve ser exclusivo dentro do agente MQTT do Azure IoT Operations.

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, portanto, você não pode criar outro ouvinte com a porta 18883.

Suporte a WebSockets

O agente MQTT do Azure IoT Operations suporta MQTT sobre WebSockets. Para habilitar WebSockets, defina o protocolo para WebSockets a porta.

Configurar TLS com gerenciamento automático de certificados

Para habilitar o TLS com 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á é instalado junto com as Operações IoT do cert-manager Azure no namespace. Verifique a instalação antes de continuar.

Use kubectl para verificar se os pods 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ê vir os pods mostrados como prontos e em execução, o cert-manager está instalado e pronto para uso.

Gorjeta

Para verificar melhor a instalação, verifique a documentação do cert-manager verificar a instalação. Lembre-se de usar o cert-manager namespace.

Criar um emissor para o certificado do servidor TLS

O recurso Emissor cert-manager define como os certificados são emitidos automaticamente. O Cert-manager suporta vários tipos de Emissores nativamente. Ele também suporta um tipo de emissor externo para estender a funcionalidade além dos emissores suportados nativamente. O corretor MQTT pode ser usado com qualquer tipo de emissor cert-manager.

Importante

Durante a implantação inicial, as Operações IoT do Azure 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, consulte CA raiz padrão e emissor com operações do Azure IoT. As etapas abaixo só são necessárias se você quiser usar um emissor diferente.

A abordagem para criar o emissor é diferente dependendo do seu cenário. As seções a seguir listam exemplos para ajudá-lo a começar.

Desenvolvimento ou teste
Produção

O emissor da autoridade de certificação é útil para desenvolvimento e testes. Ele deve ser configurado com um certificado e uma chave privada armazenados 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 da autoridade de certificação e os arquivos PEM da chave privada da autoridade de certificação. Execute o seguinte comando para importar o certificado da autoridade de certificação como um segredo do Kubernetes e ignore 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 cert-manager poderá gerar um certificado de autoridade de certificação para você. Usar o cert-manager para gerar um certificado de CA é conhecido como inicializar um emissor de CA com um certificado autoassinado.

Comece por criar 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 autoridade de certificação autoassinado com o seguinte comando:
```
kubectl apply -f ca.yaml
```

O Cert-manager cria um certificado de CA usando seus padrões. As propriedades deste certificado podem ser alteradas modificando a especificação do certificado. Consulte a documentação do cert-manager para obter uma lista de opções válidas.

Distribuir o certificado raiz

O exemplo anterior armazena o certificado da autoridade de certificação em um segredo do Kubernetes chamado test-ca. O certificado em formato PEM pode ser recuperado do segredo e armazenado em um 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

Este certificado deve ser distribuído e confiável por todos os clientes. Por exemplo, use o --cafile sinalizador para um cliente mosquitto.

Criar emissor com base no certificado da autoridade de certificação

O Cert-manager precisa de um emissor com base no certificado de autoridade de certificação 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 são definidos no recurso BrokerListener posteriormente.

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

Implante o HashiCorp Vault em um ambiente de escolha, como o Kubernetes. Inicialize e deslacre o Vault de acordo.
Crie e configure o mecanismo de segredos PKI importando seu certificado de autoridade de certificação.

Configure o Vault com função e política para emitir certificados de servidor.

Segue-se um exemplo de função. Observação 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 Vault usando um método de escolha, como o SAT.
Configure o emissor do Vault cert-manager.

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

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

No portal do Azure, vá para sua instância de Operações IoT.
Em Componentes, selecione MQTT Broker.
Selecione ou crie um ouvinte. Você só pode criar 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 o TLS em uma porta existente ou adicionando uma nova porta.

Introduza as seguintes definições:

Definição	Description
Name	Nome do recurso BrokerListener. Introduzir `aio-broker-loadbalancer-tls`.
Porta	Número da porta na qual o BrokerListener escuta conexões MQTT. Digite 8884.
Autenticação	A referência do recurso de autenticação.
Autorização	A referência do recurso de autorização.
TLS	Selecione o botão Adicionar.
Nome do emissor	Nome do emissor do gestor de certificados. Obrigatório.
Tipo de emitente	Tipo de emissor do gestor de certificados. Obrigatório.
Grupo de emitentes	Grupo do emitente do gestor de certificados. Obrigatório.
Algoritmo de chave privada	Algoritmo para a chave privada.
Política de rotação de chave privada	Política de rotação da chave privada.
Nomes DNS	Nomes alternativos de entidade DNS para o certificado.
Endereços IP	Endereços IP da entidade nomes alternativos para o certificado.
Nome do segredo	Segredo do Kubernetes contendo um certificado de cliente X.509.
Duração	Tempo de vida total do certificado do servidor TLS O padrão é de 90 dias.
Renovar antes	Quando começar a renovar o certificado.

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

Implante o arquivo Bicep usando a CLI do Azure.

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

Modifique a tls configuração em um recurso BrokerListener para especificar uma porta TLS e um Emissor para os frontends.

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 é configurado, o broker MQTT cria automaticamente um novo serviço com a porta especificada e o TLS habilitado.

Opcional: Configurar parâmetros de certificado do servidor

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

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

Verificar a implementação

Use kubectl para verificar se o serviço associado ao recurso BrokerListener está em execução. No exemplo acima, 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

Conecte-se ao corretor com TLS

Depois que o certificado do servidor estiver 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 --cafile argumento habilita o TLS no cliente mosquitto e especifica que o cliente deve confiar em todos os certificados de servidor emitidos pelo arquivo fornecido. Você deve especificar um arquivo que contenha o emissor do certificado do servidor TLS configurado.

Substitua $HOST pelo host apropriado:

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

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

CA raiz padrão e emissor

Para ajudá-lo a começar, o Azure IoT Operations é implantado com um certificado de CA de "início rápido" padrão e um emissor para certificados de servidor TLS. Você pode usar esse emissor para desenvolvimento e testes. Para obter mais informações, consulte CA raiz padrão e emissor para certificados de servidor TLS.

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

Configurar TLS com gerenciamento manual de certificados

Para configurar manualmente o broker 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 autoridade de certificação com a CLI da Etapa

O Step é um gerenciador de certificados que pode rapidamente colocá-lo em funcionamento ao criar e gerenciar sua própria CA privada.

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

Crie um certificado de autoridade de certificação intermediário e uma chave assinada pela autoridade de certificação 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 certificado de servidor

Use a CLI de etapa para criar um certificado de servidor a partir do assinado pela 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 estão os nomes alternativos de assunto (SANs) para o frontend do broker MQTT no Kubernetes e clientes locais, respectivamente. Para se conectar pela Internet, adicione um --san com um IP externo. Os --no-password --insecure sinalizadores são usados para testes para ignorar prompts de senha e desabilitar a proteção por 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 Cofre de Chaves do Azure.

Requisitos do algoritmo de chave de certificado

As chaves EC e RSA são suportadas, mas todos os certificados na cadeia devem usar o mesmo algoritmo de chave. Se você importar seus próprios certificados de autoridade de certificação, certifique-se de que o certificado do servidor use o mesmo algoritmo de chave que as autoridades de certificação.

Importar cadeia de certificados do servidor como um segredo do Kubernetes

Crie uma cadeia de certificados de servidor completa, onde a ordem dos certificados é importante: o certificado do servidor é o primeiro no arquivo, 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

A seguir está um exemplo de um recurso BrokerListener que habilita o TLS na porta 8884 com gerenciamento manual de certificados.

No portal do Azure, navegue até sua instância de Operações IoT.
Em Componentes, selecione MQTT Broker.
Selecione ou crie um ouvinte. Você só pode criar 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 de ouvinte como mqtts-endpoint.

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

Introduza as seguintes definições:

Definição	Descrição
Porta	Número da porta na qual o BrokerListener escuta conexões MQTT. Obrigatório.
Autenticação	A referência do recurso de autenticação.
Autorização	A referência do recurso de autorização.
TLS	Selecione o botão Adicionar.
Nome do segredo	Segredo do Kubernetes contendo um certificado de cliente X.509.

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

Modifique a configuração em um recurso BrokerListener para especificar a tls configuração TLS manual fazendo referência ao segredo do Kubernetes. Observe o nome do segredo usado 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'
          }
        }
      }
    ]
  }
}

Implante 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 é criado, o operador cria automaticamente um serviço Kubernetes e implanta o ouvinte. Você pode verificar o status do serviço executando kubectl get svc.

Conecte-se ao corretor com TLS

Para testar a conexão TLS com o cliente mosquitto, publique uma mensagem e passe o certificado de autoridade de certificação 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 nome de usuário, senha, etc. se a autenticação do agente MQTT estiver ativada.

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

Gorjeta

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

Nota

Para se conectar ao broker, você precisa distribuir root of trust, também conhecido como trust bundle, para todos os clientes. Nesse caso, a raiz da confiança é a autoridade de certificação raiz autoassinada criada pela CLI da etapa. A distribuição da raiz de confiança é necessária para que o cliente verifique a cadeia de certificados do servidor. Se seus clientes MQTT são cargas de trabalho no cluster Kubernetes, você também precisa criar um ConfigMap com a CA raiz e montá-lo em seu Pod.

Usar IP externo para o certificado do servidor

Para se conectar ao TLS pela Internet, o certificado do servidor do broker MQTT deve ter seu nome de host externo ou endereço IP como uma SAN. Na produção, este é geralmente um nome DNS ou um endereço IP bem conhecido. No entanto, durante o desenvolvimento/teste, talvez você não saiba qual nome de host ou IP externo é atribuído antes da implantação. Para resolver isso, implante o ouvinte sem o certificado do servidor primeiro, crie o certificado e o segredo do servidor com o IP externo e importe o segredo para o ouvinte.

Se você tentar implantar o ouvinte manual-tls-listener TLS de exemplo, mas o segredo server-cert-secret do Kubernetes referenciado não existir, o serviço associado será criado, mas os pods não serão iniciados. 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

No entanto, esse comportamento é esperado enquanto importamos o certificado do servidor. Os logs do gerenciador de integridade mencionam que o corretor 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.

Nota

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

Mesmo que os pods de frontend 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 anteriores para criar um certificado de servidor com esse IP externo e --san criar o segredo do Kubernetes da mesma maneira. Uma vez que o segredo é criado, ele é automaticamente importado para o ouvinte.

Partilhar via

Proteja a comunicação do broker MQTT usando o BrokerListener

BrokerListener padrão

Evite modificar o ouvinte do broker padrão

Criar novos ouvintes de corretor

Exemplo: Criar um novo ouvinte com duas portas

Tipo de serviço

Apenas um ouvinte por tipo de serviço

Nome do serviço

Portas

Usando a mesma porta entre ouvintes

Suporte a WebSockets

Configurar TLS com gerenciamento automático de certificados

Verificar a instalação do cert-manager

Criar um emissor para o certificado do servidor TLS

Configurar o certificado raiz como um segredo do Kubernetes

Distribuir o certificado raiz

Criar emissor com base no certificado da autoridade de certificação

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

Opcional: Configurar parâmetros de certificado do servidor

Verificar a implementação

Conecte-se ao corretor com TLS

CA raiz padrão e emissor

Configurar TLS com gerenciamento manual de certificados

Criar autoridade de certificação com a CLI da Etapa

Criar certificado de servidor

Requisitos do 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

Conecte-se ao corretor com TLS

Usar IP externo para o certificado do servidor

Comentários

Recursos adicionais

Partilhar via

Proteja a comunicação do broker MQTT usando o BrokerListener

BrokerListener padrão

Evite modificar o ouvinte do broker padrão

Criar novos ouvintes de corretor

Exemplo: Criar um novo ouvinte com duas portas

Tipo de serviço

Apenas um ouvinte por tipo de serviço

Nome do serviço

Portas

Usando a mesma porta entre ouvintes

Suporte a WebSockets

Configurar TLS com gerenciamento automático de certificados

Verificar a instalação do cert-manager

Criar um emissor para o certificado do servidor TLS

Configurar o certificado raiz como um segredo do Kubernetes

Distribuir o certificado raiz

Criar emissor com base no certificado da autoridade de certificação

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

Opcional: Configurar parâmetros de certificado do servidor

Verificar a implementação

Conecte-se ao corretor com TLS

CA raiz padrão e emissor

Configurar TLS com gerenciamento manual de certificados

Criar autoridade de certificação com a CLI da Etapa

Criar certificado de servidor

Requisitos do 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

Conecte-se ao corretor com TLS

Usar IP externo para o certificado do servidor

Conteúdos relacionados

Comentários

Recursos adicionais