Proteger a comunicação pelo agente MQTT usando o BrokerListener

1. No portal do Azure, navegue até a instância de Operações de IoT.

2. Em Componentes, selecione Agente MQTT.

   

3. Na lista de ouvintes do agente, selecione o ouvinte padrão.

   

4. 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 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 o 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 ter esta aparência, com a maioria dos metadados removidos para fins de 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 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"}}]'

1. No portal do Azure, navegue até a instância de Operações de IoT.

2. Em Componentes, selecione Agente MQTT.

3. 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.

4. 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 adicionar

5. 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

6. No painel de configuração do TLS, insira as seguintes configurações:

   Configuração	Descrição
   Modo TLS	Escolher Automático
   Nome do emissor	Inserir azure-iot-operations-aio-certificate-issuer
   Tipo de emissor	Escolher ClusterIssuer

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

7. Selecione Criar ouvinte.

   

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 o 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

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.

1. 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
   

2. Crie o certificado de AC autoassinado com o seguinte comando:

   kubectl apply -f ca.yaml
   

O cert-manager cria um certificado de AC usando os respectivos padrões. As propriedades desse certificado podem ser alteradas modificando a especificação do certificado. Confira 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 de AC em um segredo do Kubernetes chamado test-ca. O certificado no formato PEM pode ser recuperado a partir 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

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:

1. Implantar o HashiCorp Vault em um ambiente de escolha, como kubernetes. Inicialize e retire o lacre do Cofre de acordo.

2. Crie e configure o mecanismo de segredos de PKI importando seu certificado de AC.

3. Configure o Cofre com uma função e uma política para a emissão de certificados de servidor.

   A seguir temos um exemplo de função. A anotaçã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"]
   }
   

4. Configure a autenticação entre o cert-manager e o Cofre usando um método de sua escolha, como o SAT.

5. Configure o Emissor do Cofre do cert-manager.

1. No portal do Azure, navegue até a instância de Operações de IoT.

2. Em Componentes, selecione Agente MQTT.

3. 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.

4. Você pode adicionar configurações de TLS ao ouvinte selecionando o 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	O tempo de vida total do certificado do servidor TLS é padrão para 90 dias.
   Renovar antes de	Quando começar a renovar o certificado.

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

Implante o arquivo Bicep usando o 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 um Emissor 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

1. No portal do Azure, navegue até a instância de Operações de IoT.

2. Em Componentes, selecione Agente MQTT.

3. 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.

4. Você pode adicionar configurações de TLS ao ouvinte selecionando o 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.

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

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 a configuração manual do TLS referenciando o segredo do Kubernetes. Observe o nome do segredo usado para o certificado do servidor TLS (server-cert-secret no exemplo anterior).

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 do Kubernetes e implanta o ouvinte. Você pode verificar o status do serviço executando kubectl get svc.