Instalar ou desinstalar o Azure IoT Edge para Linux

Aplica-se a: ícone de sim IoT Edge 1.1 Outras versões: IoT Edge 1.2

Aplica-se a: ícone de sim IoT Edge 1.2 Outras versões: IoT Edge 1.1

O runtime do Azure IoT Edge é o que transforma um dispositivo em um dispositivo do IoT Edge. O runtime pode ser implantado em dispositivos pequenos como um Raspberry Pi ou grandes como um servidor industrial. Após um dispositivo ser configurado com o runtime do IoT Edge, você pode começar a implantar a lógica de negócios nele da nuvem. Para saber mais, confira Entender o runtime do Azure IoT Edge e sua arquitetura.

Este artigo lista as etapas para instalar o runtime do Azure IoT Edge em dispositivos Linux.

Pré-requisitos

  • Uma ID de dispositivo registrado

    Se você registrou o dispositivo com a autenticação de chave simétrica, tenha a cadeia de conexão do dispositivo pronta.

    Se você registrou o dispositivo com a autenticação de certificado autoassinado X.509, tenha pelo menos um dos certificados de identidade usados para registrar o dispositivo e a chave privada correspondente disponíveis no dispositivo.

  • Um dispositivo Linux

    Tenha um dispositivo Linux X64, ARM32 ou ARM64. A Microsoft fornece pacotes de instalação para os sistemas operacionais Ubuntu Server 18.04 e Raspberry Pi OS Stretch.

    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

    Observação

    O suporte para dispositivos ARM64 está na versão prévia pública.

  • Prepare o dispositivo para acessar os pacotes de instalação da Microsoft.

    Instale a configuração do repositório que corresponde ao sistema operacional do seu dispositivo.

    • Ubuntu Server 18.04:

      curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
      
    • Ampliação do SO do Raspberry Pi:

      curl https://packages.microsoft.com/config/debian/stretch/multiarch/prod.list > ./microsoft-prod.list
      

    Copie a lista gerada para o diretório sources.list.d.

    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
    

    Instale a chave pública do Microsoft GPG.

    curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
    sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
    

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. Para cenários de produção, recomendamos que você use o mecanismo Moby. Esse é 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.

Atualize as listas de pacotes no dispositivo.

sudo apt-get update

Instale o mecanismo de Moby.

sudo apt-get install moby-engine

Se receber erros ao tentar instalar o mecanismo de contêiner Moby, verifique a compatibilidade de seu kernel Linux com o 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 compilando novamente o kernel da origem e selecionando os módulos associados para inclusão no .config do kernel apropriado. 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. Depois de implantar o kernel recém-modificado, execute o script check-config novamente para verificar se todos os recursos necessários foram habilitados com êxito.

Instalar o Edge IoT

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.

Atualize as listas de pacotes no dispositivo.

sudo apt-get update

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

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.

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.

O serviço de identidade de IoT foi introduzido com a versão 1.2 do IoT Edge. Esse serviço cuida do provisionamento e gerenciamento de identidades 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 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.

Observação

As etapas nesta seção mostram como instalar o IoT Edge versão 1.2.

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

Atualize as listas de pacotes no dispositivo.

sudo apt-get update

Verifique quais versões do IoT Edge e do serviço de identidade IoT estão disponíveis.

apt list -a aziot-edge aziot-identity-service

Para instalar a versão mais recente do IoT Edge e o pacote do serviço de identidade IoT, use o seguinte comando:

sudo apt-get install aziot-edge

Ou, se você optar por instalar uma versão diferente IoT Edge que não a mais recente, instale a mesma versão para os serviços aziot-edge e aziot-identity-service.

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.

Escolha a próxima seção com base no tipo de autenticação que será usado:

Opção 1: autenticar com chaves simétricas

Neste ponto, o runtime do IoT Edge está instalado em seu dispositivo Linux e você precisa provisionar o dispositivo com as informações de autenticação e a identidade de nuvem dele.

Esta seção descreve as etapas para provisionar um dispositivo com a autenticação de chave simétrica. Você deve ter registrado o dispositivo no Hub IoT e recuperado a cadeia de conexão nas informações dele. Caso contrário, siga as etapas em Registrar um dispositivo IoT Edge no Hub IoT.

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

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 cadeia de conexão.

# Manual provisioning with connection string
[provisioning]
source = "manual"
connection_string = "<ADD DEVICE CONNECTION STRING HERE>"

Atualize o valor de connection_string com a cadeia de conexão de seu dispositivo IoT Edge.

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, aplique as alterações:

sudo iotedge config apply

Opção 2: autenticar com certificados X.509

Neste ponto, o runtime do IoT Edge está instalado em seu dispositivo Linux e você precisa provisionar o dispositivo com as informações de autenticação e a identidade de nuvem dele.

Esta seção descreve as etapas para provisionar um dispositivo com a autenticação de certificado X.509. Você deve ter registrado o dispositivo no Hub IoT, fornecendo impressões digitais que correspondam ao certificado e à chave privada localizados no dispositivo IoT Edge. Caso contrário, siga as etapas em Registrar um dispositivo IoT Edge no Hub IoT.

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

sudo nano /etc/iotedge/config.yaml

Encontre a seção de configurações de provisionamento do arquivo e remova a marca de comentário da seção Configuração de provisionamento manual usando um certificado de identidade X.509. 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.

# Manual provisioning configuration using an x.509 identity certificate
provisioning:
  source: "manual"
  authentication:
    method: "x509"
    iothub_hostname: "<REQUIRED IOTHUB HOSTNAME>"
    device_id: "<REQUIRED DEVICE ID PROVISIONED IN IOTHUB>"
    identity_cert: "<REQUIRED URI 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.
  • identity_pk: URI para o arquivo de chave privada para o certificado de identidade fornecido. Por exemplo, file:///path/identity_key.pem.

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

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

journalctl -u iotedge
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.

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

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

  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 remove iotedge
sudo apt-get remove aziot-edge

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

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 remove --purge moby-cli
sudo apt-get remove --purge moby-engine

Próximas etapas

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