Compartilhar via

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

  • Artigo

Aplica-se a: ícone sim IoT Edge 1.1

Importante

IoT Edge 1.1 a data de término do suporte foi 13 de dezembro de 2022. Confira o Ciclo de Vida do Produto da Microsoft para obter informações sobre o suporte deste produto, serviço, tecnologia ou API. Para obter mais informações sobre como atualizar para a versão mais recente do IoT Edge, consulte 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 chaves simétricas como seu método de autenticação. Se você quiser usar certificados X.509, confira Criar e provisionar um dispositivo IoT Edge no Linux usando certificados x. 509.

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 pré-requisitos próprios:

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.

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 Chave simétrica como o tipo de autenticação.
    • Use as configurações padrão para gerar automaticamente as chaves de autenticação e conectar o novo dispositivo ao hub.

  4. Clique em 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 chave simétrica precisam de suas cadeias de conexão 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.

Captura de tela de como exibir os dispositivos no portal do Azure, Hub IoT.

Quando estiver pronto para configurar o dispositivo, você precisará da cadeia de conexão que vincula o dispositivo físico à identidade no hub IoT.

As cadeias de conexão dos dispositivos que se autenticam com chaves simétricas estão disponíveis para cópia no portal.

  1. Na página Dispositivos no portal, selecione a identificação do dispositivo IoT Edge na lista.
  2. Copie o valor da Cadeia de conexão primária ou Cadeia de conexão secundária.

Instalar o Edge IoT

Nesta seção, você preparará a VM ou o dispositivo físico Linux para o 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:

  • 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

  • 18.04:

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

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

Depois que o mecanismo Moby for instalado com êxito, configure-o para usar o driver de log do local como o mecanismo de registro em log. Para saber mais sobre a configuração de log, confira Lista de verificação de implantação em produção.

  • Crie ou abra o arquivo de configuração do daemon do Docker em /etc/docker/daemon.json.

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

       {
      "log-driver": "local"
   }

  • 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 daemon de segurança do IoT Edge fornece e mantém padrões de segurança no dispositivo IoT Edge. O daemon é iniciado a cada inicialização e inicializa o dispositivo iniciando o restante do runtime do IoT Edge.

As etapas nesta seção representam o processo comum para instalar a última versão em um dispositivo conectado à 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.

Instale a versão 1.1* do IoT Edge juntamente com o pacotelibiothsm-std:

sudo apt-get update; \
  sudo apt-get install iotedge

Observação

A versão 1.1 do IoT Edge é o ramo de suporte de longo prazo do IoT Edge. Se você estiver executando uma versão mais antiga, recomendamos instalar ou atualizar para o patch mais recente, pois não há mais suporte para versões mais antigas.

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.

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

sudo nano /etc/iotedge/config.yaml

Encontre as configurações de provisionamento do arquivo e remova a marca de comentário da seção Configuração de provisionamento manual usando uma cadeia de conexão, caso isso ainda não tenha sido feito.

# Manual provisioning configuration using a connection string
provisioning:
source: "manual"
device_connection_string: "ADD_DEVICE_CONNECTION_STRING_HERE"

Atualizar o valor de device_connection_string com a cadeia de caracteres de conexão do dispositivo IoT Edge. As marcas de comentário precisam ter sido removidas de todas as outras seções de provisionamento. Verifique se a linha provisioning: não é precedida de nenhum espaço em branco e se os itens aninhados têm recuo de dois espaços.

Para colar o conteúdo da área de transferência no Nano, Shift+Right Click ou clique em Shift+Insert.

Salve e feche o arquivo.

CTRL + X, Y, Enter

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

sudo systemctl restart iotedge

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 systemctl status iotedge

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

journalctl -u iotedge

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.

  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 o daemon de segurança e o hsmlib do IoT Edge. 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 libiothsm-std 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.

    2. Use o link copiado no seguinte comando para instalar essa versão do hsmlib:

      curl -L <libiothsm-std_link> -o libiothsm-std.deb && sudo apt-get install ./libiothsm-std.deb

    3. Localize o arquivo iotedge 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 daemon de segurança do IoT Edge.

      curl -L iotedge_link_here -o iotedge.deb && sudo apt-get install ./iotedge.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 iotedge

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