Compartilhar via

Criar e provisionar dispositivos de Azure IoT Edge em escala no Linux usando certificados X.509

  • Artigo

Aplica-se a: Marca de seleção do IoT Edge 1.5 IoT Edge 1.5 marca de seleção do IoT Edge 1.4 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este artigo fornece instruções de ponta a ponta para o provisionamento automático de um ou mais dispositivos Linux de Azure IoT Edge usando certificados X.509. Você pode provisionar automaticamente dispositivos do Azure IoT Edge com o serviço de provisionamento de dispositivos no Hub IoT do Azure (DPS em IoT). Se você não estiver familiarizado com o processo de provisionamento automático, reveja a visão geral de provisionamento antes de continuar.

As tarefas são as seguintes:

  1. Gerar certificados e chaves.
  2. Crie um registro individual para um único dispositivo ou um registro de grupo para um conjunto de dispositivos.
  3. Instalar o runtime do IoT Edge e registrar o dispositivo com Hub IoT.

Usar certificados X.509 como um mecanismo de atestado é uma maneira excelente de escalar a produção e simplificar o provisionamento do dispositivo. Normalmente, os certificados X.509 são organizados em uma cadeia de certificados de confiança. Começando com um certificado raiz confiável ou autoassinado, cada certificado na cadeia assina o próximo certificado inferior. Esse padrão cria uma cadeia de confiança delegada do certificado raiz até cada certificado intermediário e, em seguida, até o certificado final de dispositivo downstream instalado em um dispositivo.

Dica

Se o dispositivo tiver um HSM (Hardware Security Module), como um TPM 2.0, recomendamos armazenar as chaves X.509 com segurança no HSM. Saiba mais sobre como implementar o zero-touch provisioning em escala descrito neste blueprint com o exemplo iotedge-tpm2cloud.

Pré-requisitos

Recursos de nuvem

Requisitos do dispositivo

Um dispositivo Linux físico ou virtual que será o dispositivo de Azure IoT Edge.

Gerar certificados de identidade do dispositivo

O certificado de identidade do dispositivo é um certificado de dispositivo downstream que se conecta por meio de uma cadeia de confiança de certificados ao certificado de CA (autoridade de certificação) X.509 superior. O certificado de identidade do dispositivo deve ter um CN (nome comum) definido como a identidade do dispositivo que você deseja que o dispositivo tenha no hub IoT.

Os certificados de identidade do dispositivo são usados apenas para provisionar o dispositivo do IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. Eles não são certificados de assinatura, ao contrário dos certificados de CA apresentados pelo dispositivo IoT Edge aos módulos ou dispositivos downstream para verificação. Para saber mais, confira Detalhes do uso do certificado do Azure IoT Edge.

Depois de criar o certificado de identidade do dispositivo, você deve ter dois arquivos: um arquivo .cer ou .pem que contém a parte pública do certificado e um arquivo .cer ou .pem com a chave privada do certificado. Se você planeja usar o registro de grupo no DPS, também precisa da parte pública de um certificado de AC raiz ou intermediária na mesma cadeia de certificados de confiança.

Você precisa dos seguintes arquivos para configurar o provisionamento automático com X.509:

  • O certificado de identidade do dispositivo e seu certificado de chave privada. O certificado de identidade do dispositivo será carregado no DPS se você criar um registro individual. A chave privada é passada para o runtime do IoT Edge.
  • Um certificado de cadeia completo, que deve ter pelo menos a identidade do dispositivo e os certificados intermediários nele. O certificado de cadeia completo é passado para o runtime do IoT Edge.
  • Um certificado de AC raiz ou intermediária da cadeia de certificados de confiança. Esse certificado será carregado no DPS se você criar um registro de grupo.

Usar certificados de teste (opcional)

Se você não tem uma autoridade de certificação disponível para criar certificados de identidade e quer experimentar esse cenário, o repositório Git do Azure IoT Edge contém scripts que você pode usar para gerar certificados de teste. Esses certificados foram criados apenas para o teste de desenvolvimento e não devem ser usados na produção.

Para criar certificados de teste, siga as etapas em Criar certificados de demonstração para testar recursos do dispositivo do IoT Edge. Conclua as duas seções necessárias para configurar os scripts de geração de certificado e para criar um certificado de AC raiz. Em seguida, siga as etapas para criar um certificado de identidade do dispositivo. Quando tiver terminado, você deverá ter a cadeia de certificados e o par de chaves a seguir:

  • <WRKDIR>/certs/iot-edge-device-identity-<name>-full-chain.cert.pem
  • <WRKDIR>/private/iot-edge-device-identity-<name>.key.pem

Você precisa desses dois certificados no dispositivo do IoT Edge. Se você for usar a inscrição individual no DPS, carregue o arquivo .cert.pem. Se você for usar o registro de grupo no DPS, também precisará carregar um certificado de AC raiz ou intermediária na mesma cadeia de certificados de confiança. Se você estiver usando certificados de demonstração, use o certificado <WRKDIR>/certs/azure-iot-test-only.root.ca.cert.pem para registro de grupo.

Criar um registro de DPS

Use os certificados e chaves gerados para criar um registro no DPS de um ou mais dispositivos Azure IoT Edge.

Se você quiser provisionar um único dispositivo IoT Edge, crie um registro individual. Se você precisar de vários dispositivos provisionados, siga as etapas para criar um registro de grupo do DPS.

Ao criar uma inscrição no DPS, tem a oportunidade de declarar um Estado inicial do dispositivo duplo. No dispositivo gêmeo, você pode definir tags para agrupar dispositivos por qualquer métrica que precisar em sua solução, como região, ambiente, local ou tipo de dispositivo. Essas marcas são usadas para criar implantações automáticas.

Para saber mais sobre registros no serviço de provisionamento de dispositivos, confira Como gerenciar registros de dispositivo.

Criar um registro individual de DPS

Os registros individuais usam a parte pública do certificado de identidade de um dispositivo e correspondem ao certificado no dispositivo.

Dica

As etapas neste artigo são para o portal do Microsoft Azure, mas também é possível criar registros individuais usando a CLI do Azure. Para obter mais informações, confira Registro az iot dps. Como parte do comando da CLI, use o sinalizador habilitado para o Edge para especificar que o registro é para um dispositivo do IoT Edge.

  1. No portal do Azure, navegue até sua instância do serviço de provisionamento de dispositivos no Hub IoT.

  2. Em Configurações, selecione Gerenciar registros.

  3. Selecione adicionar registro individual, em seguida, conclua as seguintes etapas para configurar o registro:

    • Mecanismo: selecione X.509.

    • Arquivo .pem ou .cer do certificado primário: carregue o arquivo público do certificado de identidade do dispositivo. Se você usou os scripts para gerar um certificado de teste, escolha o seguinte arquivo:

      <WRKDIR>\certs\iot-edge-device-identity-<name>.cert.pem

    • ID de Dispositivo do Hub IoT: forneça uma ID para o seu dispositivo, se desejar. Você pode usar IDs de dispositivo para um dispositivo individual para a implantação do módulo de destino. Se você não fornecer uma ID de dispositivo, o CN (nome comum) no certificado X.509 será usado.

    • Dispositivo do IoT Edge: selecione True para declarar que o registro é para um dispositivo do IoT Edge.

    • Selecione os hubs IoT aos quais este dispositivo pode ser atribuído: escolha o Hub IoT vinculado ao qual você deseja conectar o dispositivo. Você pode escolher vários hubs e o dispositivo será atribuído a um deles de acordo com a política de alocação selecionada.

    • Estado inicial do dispositivo gêmeo: adicione um valor de marca a ser adicionado ao dispositivo gêmeo se desejar. Você pode usar marcas para grupos de dispositivos de destino para a implantação automática. Por exemplo:

      {
    "tags": {
       "environment": "test"
    },
    "properties": {
       "desired": {}
    }
}

  4. Selecione Salvar.

Em Gerenciar Registros, você pode ver a ID do Registro que acabou de criar. Anote-a, pois ela pode ser usada quando você provisiona seu dispositivo.

Agora que existe um registro para esse dispositivo, o runtime do IoT Edge pode provisionar automaticamente o dispositivo durante a instalação.

Instalar o Edge IoT

Nesta seção, você preparará a máquina virtual do Linux ou o dispositivo físico para Azure IoT Edge. Em seguida, você instalará o IoT Edge.

Execute os comandos a seguir para adicionar o repositório de pacotes e, em seguida, adicione a chave de assinatura de pacote da Microsoft à sua lista de chaves confiáveis.

Importante

Em 30 de junho de 2022, o Stretch do SO Raspberry Pi foi retirado da lista de suporte do SO de Camada 1. Para evitar possíveis vulnerabilidades de segurança, atualize o sistema operacional host para o Bullseye.

Para sistemas operacionais de plataforma com suporte na camada 2, os pacotes de instalação estão disponíveis em lançamentos do Azure IoT Edge. Confira as etapas de instalação em Instalação offline ou específica da versão.

A instalação pode ser feita com alguns comandos. Abra um terminal e execute os seguintes comandos:

  • 24.04:

    wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

  • 22.04:

    wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

  • 20.04:

    wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Para obter mais informações sobre versões do sistema operacional, veja Plataformas suportadas pelo Azure IoT Edge.

Observação

Os pacotes de software do Azure IoT Edge estão sujeitos aos termos de licença localizados em cada pacote (usr/share/doc/{package-name} ou o diretório LICENSE). Leia os termos da licença antes de usar o pacote. A instalação e o uso do pacote constitui a aceitação desses termos. Se você não concorda com os termos de licença, não utilize o pacote.

Instalar um mecanismo de contêiner

O Azure IoT Edge depende de um runtime de contêiner compatível com OCI. Em cenários de produção, recomendamos o uso do mecanismo Moby. O mecanismo Moby é o mecanismo de contêiner com suporte oficial do Azure IoT Edge. Imagens de contêiner do docker CE/EE são compatíveis com o runtime Moby. Se você estiver usando snaps do Ubuntu Core, o snap do Docker será atendido pela Canonical e terá suporte para cenários de produção.

Instale o mecanismo de Moby.

sudo apt-get update; \
  sudo apt-get install moby-engine

Por padrão, o mecanismo de contêiner não define limites de tamanho de log de contêiner. Com o tempo, isso pode levar ao dispositivo que está se enchendo com os logs e ficando sem espaço em disco. No entanto, você pode configurar seu log para ser exibido localmente, embora seja opcional. Para saber mais sobre a configuração de log, confira Lista de verificação de implantação em produção.

As etapas a seguir mostram como configurar seu contêiner para usar local driver de log como mecanismo de log.

  1. Crie ou edite o arquivo de configuração do daemon Docker existente

    sudo nano /etc/docker/daemon.json

  2. Configure o driver de log padrão para o driver de log local conforme mostrado no exemplo.

       {
      "log-driver": "local"
   }

  3. Reinicie o mecanismo de contêiner para que as alterações entrem em vigor.

    sudo systemctl restart docker

Instalar o runtime do Azure IoT Edge

O serviço do IoT Edge fornece e mantém padrões de segurança no dispositivo IoT Edge. O serviço é iniciado a cada inicialização e inicializa o dispositivo iniciando o restante do runtime do IoT Edge.

Observação

A partir da versão 1.2, o serviço de identidade IoT trata do fornecimento e gestão de identidade para o IoT Edge e para outros componentes do dispositivo que precisam de comunicar com o Hub IoT do Azure.

As etapas dessa seção representam o processo típico de instalação da versão mais recente do IoT Edge em um dispositivo que tenha conexão com a Internet. Se precisar instalar uma versão específica, como uma versão de pré-lançamento, ou precisar instalar enquanto estiver offline, siga as etapas de Instalação offline ou de versão específica mais adiante neste artigo.

Dica

Se você já tem um dispositivo IoT Edge executando uma versão mais antiga e quer atualizar para a versão mais recente, siga as etapas em Atualizar o daemon de segurança e o runtime do IoT Edge. As versões posteriores são diferentes o bastante das versões anteriores do IoT Edge para que etapas específicas sejam necessárias para a atualização.

Instale a versão mais recente do IoT Edge e o pacote de serviço de identidade IoT (se ainda não estiver atualizado):

  • 22.04:

    sudo apt-get update; \
   sudo apt-get install aziot-edge

  • 20.04:

    sudo apt-get update; \
   sudo apt-get install aziot-edge

Provisionar o dispositivo com a identidade de nuvem dele

Depois que o runtime for instalado no seu dispositivo, configure-o com as informações que ele usa para se conectar ao serviço de provisionamento de dispositivos e ao Hub IoT.

Prepare as seguintes informações:

  • O valor do Escopo da ID do DPS. É possível recuperar esse valor da página de visão geral da instância do DPS no portal do Azure.
  • O arquivo de cadeia de certificados de identidade do dispositivo no dispositivo.
  • A chave de identidade do dispositivo no dispositivo.

Crie um arquivo de configuração para seu dispositivo com base em um arquivo de modelo fornecido como parte da instalação do IoT Edge.

sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

Abra o arquivo de configuração no dispositivo do IoT Edge.

sudo nano /etc/aziot/config.toml

Localize a seção Provisionamento do arquivo. Remova a marca de comentário das linhas do provisionamento do certificado X.509 do DPS e verifique se todas as outras linhas de provisionamento estão com a marca de comentário.

# DPS provisioning with X.509 certificate
[provisioning]
source = "dps"
global_endpoint = "https://global.azure-devices-provisioning.net"
id_scope = "SCOPE_ID_HERE"

# Uncomment to send a custom payload during DPS registration
# payload = { uri = "PATH_TO_JSON_FILE" }

[provisioning.attestation]
method = "x509"
registration_id = "REGISTRATION_ID_HERE"

identity_cert = "DEVICE_IDENTITY_CERTIFICATE_HERE" # For example, "file:///var/aziot/device-id.pem"
identity_pk = "DEVICE_IDENTITY_PRIVATE_KEY_HERE"   # For example, "file:///var/aziot/device-id.key"

# auto_reprovisioning_mode = Dynamic

  1. Atualize o valor de id_scope com a ID de escopo que você copiou de sua instância do DPS.

  2. Forneça um registration_id para o dispositivo, que é o ID que o dispositivo possui no Hub IoT do Azure. A ID de registro deve corresponder ao CN (nome comum) do certificado de identidade.

  3. Atualize os valores de identity_cert e identity_pk com as informações do certificado e chave.

    O valor do certificado de identidade pode ser fornecido como um URI de arquivo ou pode ser emitido dinamicamente usando a EST ou uma autoridade de certificação local. Remova a marca de comentário apenas de uma linha, com base no formato que você escolher usar.

    O valor da chave privada de identidade pode ser fornecido como um URI de arquivo ou um URI PKCS#11. Remova a marca de comentário apenas de uma linha, com base no formato que você escolher usar.

    Se você usar qualquer URI do PKCS#11, localize a seção PKCS#11 no arquivo de configuração e forneça as informações sobre a sua configuração do PKCS#11.

    Para obter mais informações sobre certificados, veja Gerenciar certificados IoT Edge.

    Para obter mais informações sobre as definições de configuração de provisionamento, veja Configurar as configurações do dispositivo IoT Edge.

  4. Opcionalmente, localize a seção modo de reprovisionamento automático do arquivo. Use o parâmetro auto_reprovisioning_mode para configurar o comportamento de reprovisionamento do seu dispositivo. Dinâmico - Reprovisionar quando o dispositivo detectar que ele pode ter sido movido de um Hub IoT para outro. Esse é o padrão. AlwaysOnStartup – Reprovisionar quando o dispositivo for reinicializado ou uma falha fizer com que os daemons sejam reiniciados. OnErrorOnly – Nunca dispare o reprovisionamento de dispositivo automaticamente. Cada modo terá um fallback de reprovisionamento de dispositivo implícito se o dispositivo não puder se conectar ao Hub IoT durante o provisionamento de identidade devido a erros de conectividade. Para obter mais informações, confira Conceitos de reprovisionamento de dispositivo do Hub IoT.

  5. Opcionalmente, remova a marca de comentário do parâmetro payload para especificar o caminho para um arquivo JSON local. O conteúdo do arquivo é enviado ao DPS como dados adicionais quando o dispositivo é registrado. Isso é útil para alocação personalizada. Por exemplo, se você desejar alocar seus dispositivos com base em uma ID do modelo de IoT Plug and Play sem intervenção humana.

  6. Salve e feche o arquivo.

Aplique as alterações de configuração feitas no IoT Edge.

sudo iotedge config apply

Verifique se a instalação bem-sucedida

Se o runtime foi iniciado com êxito, você pode entrar em seu Hub IoT e iniciar a implantação de módulos do IoT Edge em seu dispositivo.

Você pode verificar se o registro individual criado no serviço de provisionamento de dispositivos foi usado. Navegue até a sua instância do serviço de provisionamento de dispositivos do portal do Azure. Abra os detalhes de registro para o registro individual que você criou. Observe que o status do registro é atribuído e a ID do dispositivo está listada.

Use os seguintes comandos em seu dispositivo para verificar se o IoT Edge foi instalado e iniciado com êxito.

Verifique o status do serviço do IoT Edge.

sudo iotedge system status

Examine os logs de serviço.

sudo iotedge system logs

Módulos de execução da lista.

sudo iotedge list

Próximas etapas

O processo de registro do serviço de provisionamento de dispositivo permite definir a ID do dispositivo e as marcas do dispositivo gêmeo ao mesmo tempo, como provisionar o novo dispositivo. Você pode usar esses valores para dispositivos individuais ou grupos de dispositivos usando o gerenciamento automático de dispositivo de destino. Saiba como Implantar e monitorar os módulos de IoT Edge em escala usando o portal do Azure ou usando a CLI do Azure.