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

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

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 que incluem o nome de host do Hub IoT, a ID do dispositivo e as informações que o dispositivo usa para autenticar no Hub IoT.

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 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 que é chamado de 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 folha 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 em formatos .cer ou .pem. Você precisa de dois certificados de identidade do dispositivo para rotação de certificado. Uma prática recomendada é preparar dois certificados de identidade de dispositivo diferentes com datas de validade diferentes. Se um certificado expirar, o outro ainda será válido e dará tempo para girar o certificado expirado.

    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 requer duas impressões digitais ao registrar um dispositivo do 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 nesse artigo para configurar scripts de criação de certificado, criar um certificado de autoridade de certificação raiz e criar um certificado de identidade de dispositivo do IoT Edge. Para testar, você pode criar um certificado de identidade de dispositivo único 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 no portal do Azure, os dispositivos do IoT Edge são criados e gerenciados separadamente de dispositivos IoT que não estão habilitados para 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 essa ID do dispositivo, pois você a usará mais tarde.
    • 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 dá suporte somente a valores hexadecimal. Remova 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 dispositivos 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 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.

  1. Crie o arquivo de configuração do seu 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

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

    sudo nano /etc/aziot/config.toml

  3. 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 do Azure ao qual o dispositivo se conecta. 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, em seguida, forneça suas informações de configuração no arquivo

PKCS#11 seção posteriormente no arquivo de configuração.

Para obter mais informações sobre certificados, veja Gerenciar certificados IoT Edge.

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

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

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

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:

× 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ê cria um novo dispositivo IoT Edge, ele exibe 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.

Se estiver usando snaps do Ubuntu, você pode 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. Os sinalizadores --purge excluem 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 name>

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

sudo apt-get autoremove --purge moby-engine