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

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

Esse 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 do Azure

As etapas desse artigo percorrem um processo chamado provisionamento manual, onde você conecta um único dispositivo ao seu Hub IoT do Azure. 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

Esse 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 ter a ferramenta de gerenciamento de dispositivos de sua escolha, por exemplo, a CLI do Azure, e os requisitos do dispositivo antes de registrar e instalar seu dispositivo.

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.

Extensões de 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 Hub IoT do Azure:

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 um ID de dispositivo descritivo, por exemplo my-edge-device-1 (tudo em letras minúsculas). Copie este ID do dispositivo, pois você o usará mais tarde.
    • 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 chaves de autenticação, que conectam o novo dispositivo ao seu hub.

  4. Selecione Salvar.

Você deverá ver seu novo dispositivo listado em seu hub IoT.

Agora que tem um dispositivo registado no Hub IoT do Azure, pode recuperar informações de provisionamento utilizadas para concluir a instalação e o provisionamento do runtime do IoT Edge no próximo passo.

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. A cadeia de ligação é gerada para o seu dispositivo IoT Edge quando cria o dispositivo. Para Visual Studio Code e CLI do Azure, a cadeia de conexão está na saída JSON. Se utilizar o portal do Azure para criar o seu dispositivo, poderá encontrar a cadeia de ligação do próprio dispositivo. Quando você seleciona seu dispositivo no Hub IoT do Azure, ele é listado como Primary connection string na página do dispositivo.

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

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. 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 da Cadeia de conexão primária ou Cadeia de conexão secundária. Qualquer uma das teclas funcionará.

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 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 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 sua identidade de nuvem

Agora que o motor de contêiner e o tempo de execução IoT Edge estão instalados no seu dispositivo, está pronto para configurar o dispositivo com a 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'

Esse comando iotedge config mp 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

Implantar módulos

Para implementar os seus módulos IoT Edge, vá ao seu hub IoT no portal do Microsoft Azure e, em seguida:

  1. Selecione Dispositivos no menu Hub IoT do Azure.

  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 Review + create na parte inferior.

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

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

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.

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

    sudo iotedge system status

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

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

    sudo iotedge system logs

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

    sudo iotedge check

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

    Screenshot of sample responses from the check command.

    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:

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

    Esse erro é esperado num dispositivo recentemente aprovisionado porque o módulo IoT Edge Hub ainda não está em funcionamento. Certifique-se de que os seus módulos IoT Edge foram implantados nos passos anteriores. A implantação resolve esse erro.

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

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

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

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

    Depois que seus módulos estiverem implantados e em execução, 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 destinadas a cenários não cobertos pelas etapas de instalação padrão. Isso pode incluir:

  • Instalando o IoT Edge enquanto estiver offline
  • Instalando uma versão release candidate

Utilize os passos nesta secção se quiser instalar uma versão específica do tempo de execução do Azure IoT Edge que não esteja disponível através do seu gestor 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.

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

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

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

    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 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. O sinalizador --purge exclui todos os arquivos associados ao IoT Edge, incluindo seus 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 ID>

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.