Criar e provisionar um dispositivo IoT Edge no Linux usando chaves simétricas

  • Artigo

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

Importante

O IoT Edge 1.4 é a versão suportada. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

Este artigo fornece instruções completas para registrar e provisionar um dispositivo Linux IoT Edge que inclui a instalação do IoT Edge.

Cada dispositivo que se conecta a um hub IoT tem um ID de dispositivo que é usado para rastrear comunicações de nuvem para dispositivo ou de dispositivo para nuvem . Você configura um dispositivo com suas informações de conexão, que incluem:

  • Nome do host do hub IoT
  • ID do Dispositivo
  • Detalhes de autenticação para se conectar ao Hub IoT

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

  • Chaves simétricas: quando você cria uma nova identidade de dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e ela apresenta a chave para o Hub IoT ao autenticar.

    Este método de autenticação é mais rápido para começar, 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 de dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo se autentica 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 chaves simétricas como método de autenticação. Se você quiser usar certificados X.509, consulte Criar e provisionar um dispositivo IoT Edge no Linux usando certificados X.509.

Nota

Se você tiver muitos dispositivos para configurar e não quiser provisionar manualmente cada um, use um dos seguintes artigos para saber como o IoT Edge funciona com o serviço de provisionamento de dispositivos do Hub IoT:

Pré-requisitos

Este artigo mostra como registrar seu dispositivo IoT Edge e instalar o IoT Edge (também chamado de tempo de execução do IoT Edge) em seu dispositivo. Certifique-se de que tem a ferramenta de gestão de dispositivos à sua escolha, por exemplo, a CLI do Azure, e os requisitos do dispositivo antes de registar e instalar o dispositivo.

Ferramentas de gestão de dispositivos

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

Um hub IoT gratuito ou padrão em sua 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 obter as informações mais recentes sobre quais sistemas operacionais são suportados atualmente para cenários de produção, consulte Sistemas com suporte do Azure IoT Edge.

Extensões do Visual Studio Code

Se você estiver usando o Visual Studio Code, há extensões úteis do Azure IoT que facilitam o processo de criação e gerenciamento de dispositivos.

Instale as extensões Azure IoT Edge e Azure IoT Hub:

Registar o seu dispositivo

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

Em seu hub IoT no portal do Azure, os dispositivos IoT Edge são criados e gerenciados separadamente dos dispositivos IoT que não estão habilitados para borda.

  1. Entre no portal do Azure e navegue até seu hub IoT.

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

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

    • Crie uma ID de dispositivo descritiva, por exemplo my-edge-device-1 (todas minúsculas). Copie este ID do dispositivo, pois você o usará mais tarde.
    • Marque a caixa de seleção Dispositivo IoT Edge.
    • Selecione Chave simétrica como o tipo de autenticação.
    • Use as configurações padrão para gerar automaticamente chaves de autenticação, que conectam o novo dispositivo ao seu hub.

  4. Selecione Guardar.

Você deve ver seu novo dispositivo listado em seu hub IoT.

Agora que você tem um dispositivo registrado no Hub IoT, pode recuperar as informações de provisionamento usadas para concluir a instalação e o provisionamento do tempo de execução do IoT Edge na próxima etapa.

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam autenticação de chave simétrica precisam de suas cadeias de conexão para concluir a instalação e o provisionamento do tempo de execução do IoT Edge. A cadeia de conexão é gerada para seu dispositivo IoT Edge quando você cria o dispositivo. Para Visual Studio Code e CLI do Azure, a cadeia de conexão está na saída JSON. Se você usar o portal do Azure para criar seu dispositivo, poderá encontrar a cadeia de conexão do próprio dispositivo. Quando você seleciona seu dispositivo no hub IoT, ele é listado como Primary connection string na página do dispositivo.

Os dispositivos habilitados para borda que se conectam ao seu hub IoT estão listados na página Dispositivos do seu hub IoT. Se você tiver vários dispositivos, poderá filtrar a lista selecionando o tipo Dispositivos Iot Edge e, em seguida, selecionando Aplicar.

Quando estiver pronto para configurar seu dispositivo, você precisará da cadeia de conexão que vincula seu dispositivo físico à sua identidade no hub IoT. Os dispositivos que se autenticam com chaves simétricas têm suas cadeias de conexão disponíveis para cópia no portal. Para encontrar sua cadeia de conexão no portal:

  1. Na página Dispositivos, selecione o ID do dispositivo IoT Edge na lista.
  2. Copie o valor de Cadeia de Conexão Primária ou Cadeia de Conexão Secundária. Qualquer uma das chaves funcionará.

Instalar o IoT Edge

Nesta seção, você prepara sua máquina virtual Linux ou dispositivo físico para o IoT Edge. Em seguida, instale o IoT Edge.

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

Importante

Em 30 de junho de 2022, o Raspberry Pi OS Stretch foi retirado da lista de suporte do Tier 1 OS. Para evitar possíveis vulnerabilidades de segurança, atualize seu sistema operacional host para 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, consulte Plataformas com suporte do Azure IoT Edge.

Nota

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 no LICENSE diretório). Leia os termos de licença antes de usar um pacote. A sua instalação e utilização de um pacote constitui a sua aceitação destes termos. Se você não concorda com os termos da licença, não use esse pacote.

Instalar um mecanismo de contêiner

O Azure IoT Edge depende de um tempo de execução de contêiner compatível com OCI. Para cenários de produção, recomendamos que você use o mecanismo Moby. O mecanismo Moby é o único mecanismo de contêiner oficialmente suportado com o IoT Edge. As imagens de contêiner do Docker CE/EE são compatíveis com o tempo de execução do Moby.

Instale o motor 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. Ao longo do tempo, isto pode fazer com que o dispositivo seja preenchido com registos e fique 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, consulte Lista de verificação de implantação de produção.

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

  1. Criar ou editar o arquivo de configuração do daemon Docker existente

    sudo nano /etc/docker/daemon.json

  2. Defina o driver de log padrão para o local driver de log, 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 IoT Edge

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

Nota

A partir da versão 1.2, o serviço de identidade IoT lida com o provisionamento e o gerenciamento de identidade para o IoT Edge e para outros componentes de dispositivo que precisam se comunicar com o Hub IoT.

As etapas nesta seção representam o processo típico para instalar a versão mais recente do IoT Edge em um dispositivo com conexão com a Internet. Se você precisar instalar uma versão específica, como uma versão de pré-lançamento, ou precisar instalar offline, siga as etapas de instalação Offline ou versão específica mais adiante neste artigo.

Gorjeta

Se você já tiver um dispositivo IoT Edge executando uma versão mais antiga e quiser atualizar para a versão mais recente, use as etapas em Atualizar o daemon de segurança e o tempo de execução do IoT Edge. As versões posteriores são suficientemente diferentes das versões anteriores do IoT Edge para que etapas específicas sejam necessárias para atualizar.

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 for IoT, que fornece visibilidade de ponto final sobre gerenciamento de postura de segurança, vulnerabilidades, deteção de ameaças, gerenciamento de frota e muito mais para ajudá-lo a proteger seus dispositivos IoT Edge. É recomendável instalar o microagente com o agente Edge para habilitar o monitoramento de segurança e a proteção de seus dispositivos Edge. Para saber mais sobre o Microsoft Defender para IoT, consulte O que é o Microsoft Defender para IoT para construtores de dispositivos.

Provisionar o dispositivo com sua identidade na nuvem

Agora que o mecanismo de contêiner e o tempo de execução do IoT Edge estão instalados em seu dispositivo, você está pronto para configurar o dispositivo com sua identidade na nuvem e informações de autenticação.

Você pode configurar seu dispositivo IoT Edge com autenticação de chave simétrica usando o seguinte comando:

sudo iotedge config mp --connection-string 'PASTE_DEVICE_CONNECTION_STRING_HERE'

Este iotedge config mp comando cria um arquivo de configuração no dispositivo e insere sua cadeia de conexão no arquivo de configuração.

  1. Aplique as alterações de configuração.

    sudo iotedge config apply

  2. Para visualizar o arquivo de configuração, você pode abri-lo:

    sudo nano /etc/aziot/config.toml

Implementar módulos

Para implantar seus módulos do IoT Edge, vá para seu hub IoT no portal do Azure e, em seguida:

  1. Selecione Dispositivos no menu Hub IoT.

  2. Selecione seu dispositivo para abrir sua página.

  3. Selecione a guia Definir módulos .

  4. Como queremos implantar os módulos padrão do IoT Edge (edgeAgent e edgeHub), não precisamos adicionar nenhum módulo a esse painel, portanto, selecione Revisar + criar na parte inferior.

  5. Você vê a confirmação JSON de seus módulos. Selecione Criar para implantar os módulos.

Para obter mais informações, consulte Implantar um módulo.

Verificar a configuração bem-sucedida

Verifique se o tempo de execução foi instalado e configurado com êxito em seu dispositivo IoT Edge.

Gorjeta

Precisa de privilégios elevados para executar os comandos iotedge. Depois de terminar sessão do seu computador e iniciar sessão novamente pela primeira vez depois de instalar o runtime do IoT Edge, as suas permissões são atualizadas automaticamente. Até lá, use sudo na frente dos comandos.

  1. Verifique se o serviço do sistema IoT Edge está em execução.

    sudo iotedge system status

    Uma resposta de status bem-sucedida mostra os aziot serviços como em execução ou prontos.

  2. Se precisar de resolver problemas relacionados com o serviço, obtenha os registos do serviço.

    sudo iotedge system logs

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

    sudo iotedge check

    Você pode esperar um intervalo de respostas que podem incluir OK (verde), Aviso (amarelo) ou Erro (vermelho). Para solucionar erros comuns, consulte Soluções para problemas comuns do Azure IoT Edge.

    Screenshot of sample responses from the check command.

    Gorjeta

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

    Nota

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

    × prontidão para produção: o diretório de armazenamento do Edge Hub é mantido no sistema de arquivos host - ErroNão foi possível verificar o estado atual do contêiner edgeHub

    Esse erro é esperado em um dispositivo recém-provisionado porque o módulo IoT Edge Hub ainda não está em execução. Certifique-se de que seus módulos do IoT Edge foram implantados nas etapas anteriores. A implantação resolve esse erro.

    Como alternativa, você pode ver um código de status como 417 -- The device's deployment configuration is not set. Depois que os módulos forem implantados, esse status será alterado.

  4. Quando o serviço for iniciado pela primeira vez, você verá apenas o módulo edgeAgent em execução. O módulo edgeAgent é executado por padrão e ajuda a instalar e iniciar quaisquer módulos adicionais que você implantar em seu dispositivo.

    Verifique se o dispositivo e os módulos estão implantados e em execução, exibindo a página do dispositivo no portal do Azure.

    Screenshot of IoT Edge modules deployed and running confirmation in the Azure portal.

    Depois que os módulos forem implantados e executados, liste-os em seu dispositivo ou máquina virtual com o seguinte comando:

    sudo iotedge list

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

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

  • Instalando o IoT Edge enquanto estiver offline
  • Instalando uma versão Release Candidate

Use as etapas nesta seção se quiser instalar uma versão específica do tempo de execução do Azure IoT Edge que não esteja disponível por meio do gerenciador de pacotes. A lista de pacotes da Microsoft contém apenas um conjunto limitado de versões recentes e suas subversões, portanto, essas etapas são para quem deseja instalar uma versão mais antiga ou uma versão candidata a lançamento.

Se você estiver usando snaps do Ubuntu, você pode baixar um snap e instalá-lo offline. Para obter mais informações, consulte Baixar snaps e instalar offline.

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

Nota

Se o seu dispositivo estiver executando o IoT Edge versão 1.1 ou anterior, desinstale os pacotes iotedge e libiothsm-std antes de seguir as etapas nesta seção. Para obter mais informações, consulte Atualização da versão 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 de lançamento que você deseja segmentar.

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

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

    1. Encontre o arquivo aziot-identity-service que corresponde à arquitetura do 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 comando a seguir 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

    1. Encontre o arquivo aziot-edge que corresponde à arquitetura do 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 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

Desinstalar o IoT Edge

Se quiser remover a instalação do IoT Edge do seu dispositivo, use os seguintes comandos.

Remova o runtime do IoT Edge.

sudo apt-get autoremove --purge aziot-edge

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

Quando o tempo de execução do IoT Edge é removido, todos os contêineres criados por ele são interrompidos, mas ainda existem no seu dispositivo. Veja todos os contêineres para ver quais permanecem.

sudo docker ps -a

Exclua os contêineres do seu dispositivo, incluindo os dois contêineres de tempo de execução.

sudo docker rm -f <container ID>

Finalmente, remova o tempo de execução do contêiner do seu dispositivo.

sudo apt-get autoremove --purge moby-engine

Próximos passos

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