Criar e provisionar um dispositivo do Azure IoT Edge usando certificados X.509

Aplica-se a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

A versão com suporte é a IoT Edge 1.4. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este artigo fornece instruções de ponta a ponta para registrar e provisionar um dispositivo Linux IoT Edge, incluindo a instalação do IoT Edge.

Cada dispositivo que se conecta a um hub IoT tem uma identidade do dispositivo que é usada para controlar as comunicações da nuvem para dispositivo ou do dispositivo para nuvem. Você configura um dispositivo com suas informações de conexão, o que inclui o nome do host do hub IoT, a identidade do dispositivo e as informações que o dispositivo usa para autenticar no Hub IoT.

As etapas neste artigo percorrem um processo chamado provisionamento manual, no qual você conecta um único dispositivo ao seu hub IoT. No provisionamento manual, você tem duas opções para autenticar dispositivos do IoT Edge:

  • Chaves simétricas: quando você cria uma identidade do dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e apresenta a chave para o Hub IoT durante a autenticação.

    Esse método de autenticação é mais rápido para começar a usar, mas não tão seguro.

  • X.509 autoassinado: você cria dois certificados de identidade X.509 e os coloca no dispositivo. Ao criar uma nova identidade do dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo é autenticado no Hub IoT, ele apresenta um certificado e o Hub IoT verifica se o certificado corresponde à sua impressão digital.

    Esse método de autenticação é mais seguro e recomendado para cenários de produção.

Este artigo aborda o uso de certificados X.509 como seu método de autenticação. Se você quiser usar chaves simétricas, consulte Criar e provisionar um dispositivo de Azure IoT Edge no Linux usando chaves simétricas.

Observação

Se você tiver muitos dispositivos a serem configurados e não quiser provisionar manualmente cada um deles, use um dos artigos a seguir para saber como IoT Edge funciona com o Serviço de Provisionamento de Dispositivos no Hub IoT:

Pré-requisitos

Este artigo aborda o registro do dispositivo do IoT Edge e a instalação do IoT Edge nesse dispositivo. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de que você tenha todos os pré-requisitos listados antes de continuar.

Ferramentas de gerenciamento de dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure nas etapas para registrar o dispositivo. Cada utilitário tem seus próprios pré-requisitos ou pode precisar ser instalado:

Um hub IoT gratuito ou padrão na assinatura do Azure.

Requisitos do dispositivo

Um dispositivo Linux X64, ARM32, ou ARM64.

A Microsoft publica pacotes de instalação para uma variedade de sistemas operacionais.

Para ver as informações mais recentes sobre quais sistemas operacionais têm suporte para cenários de produção, confira Sistemas com suporte do Azure IoT Edge.

Gerar certificados de identidade do dispositivo

O provisionamento manual com certificados X.509 requer IoT Edge versão 1.0.10 ou mais recente.

Ao provisionar um dispositivo do IoT Edge com certificados X.509, você usa o certificado de identidade do dispositivo. Estes certificados são usados apenas para provisionar um dispositivo do IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. É um certificado secundário que não assina outros certificados. O certificado de identidade do dispositivo é separado dos certificados de AC (autoridade de certificação) que o dispositivo do IoT Edge apresenta aos módulos ou dispositivos downstream para verificação.

Para a autenticação de certificado X.509, as informações de autenticação de cada dispositivo são fornecidas na forma de impressões digitais obtidas dos certificados de identidade do dispositivo. Essas impressões digitais são fornecidas ao Hub IoT no registro do dispositivo para que o serviço possa reconhecer o dispositivo quando ele se conectar.

Para obter mais informações sobre como os certificados AC são usados nos dispositivos do IoT Edge, consulte Entenda como o Azure IoT Edge usa certificados.

Você precisa dos seguintes arquivos para o provisionamento manual com X.509:

  • Dois certificados de identidade do dispositivo com seus certificados de chave privada correspondentes nos formatos .cer ou .pem. Você precisa de dois certificados de identidade do dispositivo para rotação de certificado. A melhor prática é preparar dois certificados de identidade do dispositivo diferentes com datas de validade diferentes. Se um certificado vencer, o outro ainda será válido e dará tempo para girar o certificado vencido.

    Um conjunto de arquivos de certificado e chave é fornecido para o runtime do IoT Edge. Ao criar certificados de identidade do dispositivo, defina o CN (nome comum) do certificado com a identidade do dispositivo que você deseja que o dispositivo tenha no hub IoT.

  • Impressões digitais obtidas de ambos os certificados de identidade do dispositivo. O Hub IoT exige duas impressões digitais ao registrar um dispositivo IoT Edge. Você pode usar apenas um certificado para registro. Para usar um único certificado, defina a mesma impressão digital do certificado para as impressões digitais primária e secundária ao registrar o dispositivo.

    Os valores de impressão digital são caracteres 40-hex para hashes SHA-1 ou caracteres 64-hex para hashes SHA-256. As duas impressões digitais são fornecidas ao Hub IoT no momento do registro do dispositivo.

    Uma maneira de recuperar a impressão digital de um certificado é com o seguinte comando openssl:

    openssl x509 -in <certificate filename>.pem -text -fingerprint
    

    A impressão digital está incluída na saída desse comando. Por exemplo:

    SHA1 Fingerprint=D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12
    

Se você não tiver certificados disponíveis, você poderá Criar certificados de demonstração para testar recursos do dispositivo do IoT Edge. Siga as instruções neste artigo para configurar scripts de criação de certificado, criar um certificado AC raiz e criar um certificado de identidade do dispositivo do IoT Edge. Para teste, você pode criar um único certificado de identidade do dispositivo e usar a mesma impressão digital para valores de impressão digital primária e secundária ao registrar o dispositivo no Hub IoT.

Registre seu dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure para registrar seu dispositivo, dependendo da preferência.

No hub IoT do portal do Azure, os dispositivos do IoT Edge são criados e gerenciados separadamente dos dispositivos de IoT que não são habilitados para a borda.

  1. Entre no Portal do Azure e navegue até o Hub IoT.

  2. No painel esquerdo, selecione Dispositivos no menu e, em seguida, Adicionar dispositivo.

  3. Na página Criar um dispositivo, forneça as seguintes informações:

    • Crie uma ID do dispositivo descritivo. Anote a identidade desse dispositivo, pois você a usará depois.
    • Marque a caixa de seleção Dispositivo do IoT Edge.
    • Selecione X.509 autoassinado como o tipo de autenticação.
    • Forneça as impressões digitais do certificado de identidade primária e secundária. Os valores de impressão digital são caracteres 40-hex para hashes SHA-1 ou caracteres 64-hex para hashes SHA-256. O portal do Azure só dá suporte a valores hexadecimais. Remova os separadores de coluna e espaços dos valores de impressão digital antes de inseri-los no portal. Por exemplo, D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12 é inserido como D268D9049F1A4D6AFD8477687BC633C032375112.

    Dica

    Se você estiver testando e quiser usar um certificado, poderá usar o mesmo certificado para as impressões digitais primária e secundária.

  4. Selecione Salvar.

Agora que você tem um dispositivo registrado no Hub IoT, recupere as informações que você usa para concluir a instalação e o provisionamento do runtime do IoT Edge.

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam a autenticação de certificado de cliente X.509 precisam do seu nome do hub IoT, seu nome do dispositivo e seus arquivos de certificado para concluir a instalação e o provisionamento do runtime do IoT Edge.

Todos os dispositivos habilitados para borda que se conectam ao hub IoT são listados na página Dispositivos. Você pode filtrar a lista por tipo de Dispositivo do IoT Edge.

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.

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

  • 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 único 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.

Instale o mecanismo de Moby.

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

Por padrão, o mecanismo de contêiner Moby 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 (se o arquivo ainda não estiver lá) ou abra o Docker arquivo de configuração do daemon em /etc/docker/daemon.json.

  2. Defina o driver de log padrão para o driver de log local, conforme mostrado no exemplo abaixo.

       {
          "log-driver": "local"
       }
    
  3. Reinicie o mecanismo de contêiner para que as alterações entrem em vigor.

    sudo systemctl restart docker
    

    Dica

    Se receber erros ao instalar o mecanismo de contêiner Moby, verifique a compatibilidade de kernel Linux com Moby. Alguns fabricantes de dispositivos inseridos fornecem imagens de dispositivos que contêm kernels Linux personalizados sem os recursos necessários para compatibilidade com mecanismos de contêiner. Execute o seguinte comando, que usa o script check-config fornecido pelo Moby, para verificar a configuração do kernel:

    curl -ssl https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh -o check-config.sh
    chmod +x check-config.sh
    ./check-config.sh
    

    Na saída do script, verifique se todos os itens em Generally Necessary e Network Drivers estão habilitados. Se algum recurso estiver faltando, habilite-o recompilando o kernel da fonte e selecionando os módulos associados para inclusão no .config do kernel adequado. De maneira semelhante, se estiver usando um gerador de configuração de kernel como defconfig ou menuconfig, localize e habilite os respectivos recursos e recompile o kernel. Após a implantação do kernel recém-modificado, execute o script check-config novamente para verificar se todos os recursos necessários foram habilitados com êxito.

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 defender-iot-micro-agent-edge
    

O pacote opcional defender-iot-micro-agent-edge inclui o microagente de segurança Microsoft Defender para IoT que fornece visibilidade de ponto de extremidade sobre gerenciamento de postura de segurança, vulnerabilidades, detecção de ameaças, gerenciamento de frota e muito mais para ajudá-lo a proteger seus dispositivos IoT Edge. É recomendável instalar o micro agente com o agente do Edge para habilitar o monitoramento de segurança e a proteção de seus dispositivos do Edge. Para saber mais sobre o Microsoft Defender para IoT, consulte O que é o Microsoft Defender para IoT para compiladores de dispositivos.

Provisionar o dispositivo com a identidade de nuvem dele

Agora que o mecanismo de contêiner e o runtime do IoT Edge estão instalados no dispositivo, você está pronto para a próxima etapa, que consiste na configuração do dispositivo com a identidade de nuvem e as informações de autenticação dele.

Crie um arquivo de configuração para o 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

No dispositivo IoT Edge, abra o arquivo de configuração.

sudo nano /etc/aziot/config.toml

Localize a seção Provisioning do arquivo e remova as marcas de comentário das linhas de provisionamento manual com o certificado de identidade X.509. Todas as outras seções de provisionamento devem ter as marcas de comentário removidas.

# Manual provisioning with x.509 certificates
[provisioning]
source = "manual"
iothub_hostname = "REQUIRED_IOTHUB_HOSTNAME"
device_id = "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"

[provisioning.authentication]
method = "x509"

identity_cert = "REQUIRED_URI_OR_POINTER_TO_DEVICE_IDENTITY_CERTIFICATE"

identity_pk = "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Atualize os seguintes campos:

  • iothub_hostname: nome do host do Hub IoT ao qual o dispositivo se conectará. Por exemplo, {IoT hub name}.azure-devices.net.
  • device_id: a ID que você forneceu quando registrou o dispositivo.
  • identity_cert: URI para um certificado de identidade no dispositivo, por exemplo: file:///path/identity_certificate.pem. Você também pode emitir dinamicamente o certificado usando EST ou uma autoridade de certificação local.
  • identity_pk: URI para o arquivo de chave privada para o certificado de identidade fornecido, por exemplo: file:///path/identity_key.pem. Ou forneça um URI PKCS#11 e forneça as informações de configuração na seção PKCS#11 posteriormente no arquivo de configuração.

Salve e feche o arquivo.

CTRL + X, Y, Enter

Depois de inserir as informações de provisionamento no arquivo de configuração, aplique as alterações:

sudo iotedge config apply

Verificar configuração bem-sucedida

Verifique se o runtime foi instalado e configurado com êxito em seu dispositivo IoT Edge.

Dica

Você precisa de privilégios elevados para executar comandos iotedge. Depois que você sair da sua máquina e fizer login novamente na primeira vez após instalar o runtime do IoT Edge, suas permissões serão atualizadas automaticamente. Até lá, use sudo na frente dos comandos.

Verifique se o serviço do sistema do IoT Edge está sendo executado.

sudo iotedge system status

Uma resposta de status bem-sucedida é Ok.

Se você precisar solucionar problemas do serviço, recupere os logs de serviço.

sudo iotedge system logs

Use a ferramenta check para verificar a configuração e o status de conexão do dispositivo.

sudo iotedge check

Dica

Sempre use sudo para executar a ferramenta de verificação, mesmo após suas permissões serem atualizadas. A ferramenta precisa de privilégios elevados para acessar o arquivo de configuração e verificar o status da configuração.

Observação

Em um dispositivo recém-provisionado, você pode ver um erro relacionado ao Hub do IoT Edge:

× preparação para produção: o diretório de armazenamento do Hub do Edge é persistente no sistema de arquivos do host – erro

Não foi possível verificar o estado atual do contêiner edgeHub

Esse erro é esperado em um dispositivo recém-provisionado, pois o módulo do Hub do IoT Edge não está em execução. Para resolver o erro, no Hub IoT, defina os módulos para o dispositivo e crie uma implantação. A criação de uma implantação para o dispositivo inicia os módulos no dispositivo, incluindo o módulo Hub do IoT Edge.

Exiba todos os módulos em execução no seu dispositivo IoT Edge. Quando o serviço for iniciado pela primeira vez, você verá somente o módulo edgeAgent em execução. O módulo edgeAgent é executado por padrão e ajuda a instalar e a iniciar quaisquer módulos adicionais que você implante em seu dispositivo.

sudo iotedge list

Quando você criar um novo dispositivo do IoT Edge, ele exibirá o código de status 417 -- The device's deployment configuration is not set no portal do Azure. Esse status é normal e significa que o dispositivo está pronto para receber uma implantação do módulo.

Instalação offline ou de versão específica (opcional)

As etapas nesta seção são destinadas a cenários não cobertos pelas etapas de instalação padrão. Isso pode incluir:

  • Instalar o IoT Edge offline
  • Instalar a versão Release Candidate

Use as etapas nesta seção se quiser instalar uma versão específica do runtime do Azure IoT Edge que não está disponível por meio do seu gerenciador de pacotes. A lista de pacotes da Microsoft contém somente um conjunto limitado de versões recentes e suas subversões, portanto, estas etapas são para qualquer pessoa que queira instalar uma versão mais antiga ou uma versão Release Candidate.

Usando comandos curl, você pode direcionar os arquivos componentes diretamente do repositório do GitHub do IoT Edge.

Observação

Se o dispositivo estiver executando o IoT Edge versão 1.1 ou mais antiga, desinstale os pacotes iotedge e libiothsm-std antes de seguir as etapas nesta seção. Para obter mais informações, confira Atualizar de 1.0 ou 1.1 para a versão mais recente.

  1. Navegue até as versões do Azure IoT Edge e localize a versão que você deseja direcionar.

  2. Expanda a seção Ativos dessa versão.

  3. Toda versão deve ter novos arquivos para IoT Edge e o serviço de identidade. Se você for instalar o IoT Edge em um dispositivo offline, baixe esses arquivos com antecedência. Caso contrário, use os comandos a seguir para atualizar os componentes.

    1. Localize o arquivo aziot-identity-service que corresponde à arquitetura de seu dispositivo IoT Edge. Clique com o botão direito do mouse no link do arquivo e copie o endereço do link.

    2. Use o link copiado no seguinte comando para instalar essa versão do serviço de identidade:

      curl -L <identity service link> -o aziot-identity-service.deb && sudo apt-get install ./aziot-identity-service.deb
      
    3. Localize o arquivo aziot-edge que corresponde à arquitetura do dispositivo IoT Edge. Clique com o botão direito do mouse no link do arquivo e copie o endereço do link.

    4. Use o link copiado no comando a seguir para instalar essa versão do IoT Edge.

      curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb
      

Agora que o mecanismo de contêiner e o runtime do IoT Edge estão instalados em seu dispositivo, você está pronto para a próxima etapa, que é Provisionar o dispositivo com a identidade de nuvem dele.

Desinstalar o IoT Edge

Se você deseja remover a instalação do IoT Edge de seu dispositivo, use os comandos a seguir.

Remova o runtime do IoT Edge.

sudo apt-get autoremove --purge aziot-edge

Deixe de fora o sinalizador --purge se planeja reinstalar o IoT Edge e usar as mesmas informações de configuração no futuro. Os sinalizadores --purge excluem todos os arquivos associados ao IoT Edge, incluindo os arquivos de configuração.

Quando o runtime do IoT Edge é removido, os contêineres criados por ele são interrompidos, mas ainda existem no seu dispositivo. Exiba todos os contêineres para ver quais deles permanecem.

sudo docker ps -a

Exclua os contêineres do seu dispositivo, incluindo dois contêineres de runtime.

sudo docker rm -f <container name>

Por fim, remova o runtime do contêiner do seu dispositivo.

sudo apt-get autoremove --purge moby-engine

Próximas etapas

Prossiga para implantar módulos do IoT Edge para saber como implantar módulos em seu dispositivo.