Criar e provisionar um IoT Edge para Linux em dispositivo Windows usando certificados X.509

Aplica-se a: IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 são versões suportadas. O IoT Edge 1.4 LTS termina a vida útil em 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

Este artigo fornece instruções completas para registrar e provisionar um IoT Edge para Linux no dispositivo Windows.

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 o nome do host do hub IoT, o ID 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, 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 certificados X.509 como método de autenticação. Se você quiser usar chaves simétricas, consulte Criar e provisionar um IoT Edge para Linux em dispositivo Windows usando chaves simétricas.

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:

• Crie e provisione dispositivos IoT Edge em escala usando certificados X.509
• Crie e provisione dispositivos IoT Edge em escala com um TPM
• Crie e provisione dispositivos IoT Edge em escala usando chaves simétricas

Pré-requisitos

Este artigo aborda o registro do dispositivo IoT Edge e a instalação do IoT Edge para Linux no Windows. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de ter todos os pré-requisitos cobertos antes de prosseguir.

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:

Portal

Um hub IoT gratuito ou padrão em sua assinatura do Azure.

Visual Studio Code

• Um hub IoT gratuito ou padrão em sua assinatura do Azure
• Visual Studio Code
• Extensão do Azure IoT Edge . A extensão de código das ferramentas do Azure IoT Edge para Visual Studio está no modo de manutenção.
• Extensão do Hub IoT do Azure

CLI do Azure

• Um hub IoT gratuito ou padrão em sua assinatura do Azure

• CLI do Azure em seu ambiente

  No mínimo, sua versão da CLI do Azure deve ser 2.0.70 ou mais recente. Utilize az --version para validar. Esta versão suporta az comandos de extensão e introduz a estrutura de comandos Knack.

Requisitos do dispositivo

Um dispositivo Windows com os seguintes requisitos mínimos:

• Requisitos de Sistema

  • Windows 10¹/11 (Pro, Enterprise, IoT Enterprise)
  • Windows Server 2019¹/2022
    _{1 Windows 10 e Windows Server 2019 compilação mínima 17763 com todas as atualizações cumulativas atuais instaladas.}

• Requisitos de Hardware

  • Memória livre mínima: 1 GB
  • Espaço livre mínimo em disco: 10 GB

• Suporte à virtualização

  • No Windows 10, habilite o Hyper-V. Para obter mais informações, consulte Instalar o Hyper-V no Windows 10.
  • No Windows Server, instale a função Hyper-V e crie um comutador de rede padrão. Para obter mais informações, consulte Virtualização aninhada para Azure IoT Edge para Linux no Windows.
  • Em uma máquina virtual, configure a virtualização aninhada. Para obter mais informações, consulte Virtualização aninhada.

• Suporte em rede

  • O Windows Server não vem com uma opção padrão. Antes de implantar o EFLOW em um dispositivo Windows Server, você precisa criar um comutador virtual. Para obter mais informações, consulte Criar comutador virtual para Linux no Windows.
  • As versões da área de trabalho do Windows vêm com uma opção padrão que pode ser usada para a instalação do EFLOW. Se necessário, você pode criar seu próprio comutador virtual personalizado.

Gorjeta

Se você quiser usar módulos Linux acelerados por GPU em sua implantação do Azure IoT Edge para Linux no Windows, há várias opções de configuração a serem consideradas.

Você precisará instalar os drivers corretos, dependendo da arquitetura da GPU, e talvez precise acessar uma compilação do Programa Windows Insider. Para determinar suas necessidades de configuração e satisfazer esses pré-requisitos, consulte Aceleração de GPU para Azure IoT Edge para Linux no Windows.

Certifique-se de dedicar um tempo para satisfazer os pré-requisitos para a aceleração da GPU agora. Você precisará reiniciar o processo de instalação se decidir que deseja a aceleração da GPU durante a instalação.

Ferramentas de programação

Prepare seu dispositivo de destino para a instalação do Azure IoT Edge para Linux no Windows e a implantação da máquina virtual Linux:

1. Defina a política de execução no dispositivo de destino como AllSigned. Você pode verificar a política de execução atual em um prompt do PowerShell com privilégios elevados usando o seguinte comando:

   Get-ExecutionPolicy -List
   

   Se a política de execução do não AllSignedfor , você poderá definir a política de local machine execução usando:

   Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force
   

Para obter mais informações sobre o módulo Azure IoT Edge para Linux no Windows PowerShell, consulte a referência de funções do PowerShell.

Gerar certificados de identidade de dispositivo

O provisionamento manual com certificados X.509 requer o IoT Edge versão 1.0.10 ou mais recente.

Ao provisionar um dispositivo IoT Edge com certificados X.509, você usa o que é chamado de certificado de identidade de dispositivo. Esse certificado é usado apenas para provisionar um dispositivo IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. É um certificado de folha que não assina outros certificados. O certificado de identidade do dispositivo é separado dos certificados da autoridade de certificação (CA) que o dispositivo IoT Edge apresenta aos módulos ou dispositivos downstream para verificação.

Para autenticação de certificado X.509, as informações de autenticação de cada dispositivo são fornecidas na forma de impressões digitais retiradas dos certificados de identidade do dispositivo. Essas impressões digitais são fornecidas ao Hub IoT no momento do registro do dispositivo para que o serviço possa reconhecer o dispositivo quando ele se conecta.

Para obter mais informações sobre como os certificados de CA são usados em dispositivos IoT Edge, consulte Entender como o Azure IoT Edge usa certificados.

Você precisa dos seguintes arquivos para provisionamento manual com X.509:

• Dois certificados de identidade de dispositivo com seus certificados de chave privada correspondentes nos formatos .cer ou .pem. Você precisa de dois certificados de identidade de dispositivo para rotação de certificados. 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 lhe dará tempo para alternar o certificado expirado.

  Um conjunto de arquivos de certificado e chave é fornecido para o tempo de execução do IoT Edge. Ao criar certificados de identidade de dispositivo, defina o nome comum (CN) do certificado com a ID do dispositivo que você deseja que o dispositivo tenha em seu hub IoT.

• Impressões digitais retiradas de ambos os certificados de identidade do dispositivo. O Hub IoT requer duas impressões digitais ao registrar um dispositivo IoT Edge. Só pode utilizar um certificado para o registo. Para usar um único certificado, defina a mesma impressão digital de certificado para as impressões digitais primária e secundária ao registrar o dispositivo.

  Os valores de impressão digital são caracteres hexadecimais de 40 hex para hashes SHA-1 ou caracteres de 64 hex para hashes SHA-256. Ambas as 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 deste 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, poderá Criar certificados de demonstração para testar os recursos do dispositivo IoT Edge. Siga as instruções nesse artigo para configurar scripts de criação de certificados, criar um certificado de autoridade de certificação raiz e criar um certificado de identidade de dispositivo IoT Edge. Para testes, 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.

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.

Portal

No 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 um ID de dispositivo descritivo. Anote este ID do dispositivo, à medida que o utiliza mais tarde.
   • Marque a caixa de seleção Dispositivo IoT Edge.
   • Selecione X.509 Autoassinado como o tipo de autenticação.
   • Forneça as impressões digitais do certificado de identidade primário e secundário. Os valores de impressão digital são caracteres hexadecimais de 40 hex para hashes SHA-1 ou caracteres de 64 hex para hashes SHA-256. O portal do Azure suporta apenas valores hexadecimais. 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.

   Gorjeta

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

Visual Studio Code

Atualmente, a extensão do Azure IoT para Visual Studio Code não oferece suporte ao registro de dispositivo com certificados X.509.

CLI do Azure

Use o comando az iot hub device-identity create para criar uma nova identidade de dispositivo em seu hub IoT. Por exemplo:

az iot hub device-identity create --device-id <device_id_here> --hub-name <hub_name_here> --edge-enabled --auth-method x509_thumbprint --primary-thumbprint <primary_SHA_thumbprint_here> --secondary-thumbprint <secondary_SHA_thumbprint_here>

Este comando inclui vários parâmetros:

• --device-id ou -d: Forneça um nome descritivo exclusivo para seu hub IoT. Anote este ID do dispositivo, pois irá utilizá-lo na secção seguinte.
• hub-name ou -n: Forneça o nome do seu hub IoT.
• --edge-enabled ou --ee: Declare que o dispositivo é um dispositivo IoT Edge.
• --auth-method ou --am: Declare o tipo de autorização que o dispositivo vai usar. Neste caso, estamos usando impressões digitais de certificado X.509.
• --primary-thumbprint ou --ptp: Forneça uma impressão digital de certificado X.509 para usar como chave primária. Apenas valores hexadecimais são suportados. Remova separadores de coluna e espaços do valor de impressão digital. 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.
• --secondary-thumbprint ou --stp: Forneça uma impressão digital de certificado X.509 para usar como chave secundária. Remova separadores de coluna e espaços do valor de impressão digital. Se você estiver testando e quiser usar um certificado, poderá usar o mesmo certificado para as impressões digitais primária e secundária.

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

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam autenticação de certificado X.509 precisam do nome do hub IoT, do nome do dispositivo e dos arquivos de certificado para concluir a instalação e o provisionamento do tempo de execução do IoT Edge.

Portal

Os dispositivos habilitados para borda que se conectam ao seu hub IoT estão listados na página Dispositivos . Você pode filtrar a lista por tipo de dispositivo Dispositivos IoT Edge.

Visual Studio Code

Embora não haja suporte para registro de dispositivo com certificados X.509 por meio do Visual Studio Code, você ainda pode exibir seus dispositivos IoT Edge se precisar.

Todos os dispositivos que se conectam ao seu hub IoT estão listados na seção Hub IoT do Visual Studio Code Explorer. Os dispositivos IoT Edge são distinguíveis dos dispositivos que não são Edge com um ícone diferente e o fato de que os módulos $edgeAgent e $edgeHub são implantados em cada dispositivo IoT Edge.

CLI do Azure

Use o comando az iot hub device-identity list para exibir todos os dispositivos em seu hub IoT. Por exemplo:

az iot hub device-identity list --hub-name <hub_name_here>

Qualquer dispositivo registrado como um dispositivo IoT Edge tem a propriedade capabilities.iotEdge definida como true.

Instalar o IoT Edge

Implante o Azure IoT Edge para Linux no Windows em seu dispositivo de destino.

Nota

O processo PowerShell a seguir descreve como implantar o IoT Edge para Linux no Windows no dispositivo local. Para implantar em um dispositivo de destino remoto usando o PowerShell, você pode usar o PowerShell Remoto para estabelecer uma conexão com um dispositivo remoto e executar esses comandos remotamente nesse dispositivo.

1. Em uma sessão do PowerShell com privilégios elevados, execute um dos seguintes comandos, dependendo da arquitetura do dispositivo de destino, para baixar o IoT Edge para Linux no Windows.

   • X64/AMD64

     $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
     $ProgressPreference = 'SilentlyContinue'
     Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_X64" -OutFile $msiPath
     

   • ARM64

     $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
     $ProgressPreference = 'SilentlyContinue'
     Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_ARM64" -OutFile $msiPath
     

2. Instale o IoT Edge para Linux no Windows no seu dispositivo.

   Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"
   

   Você pode especificar diretórios personalizados de instalação do IoT Edge para Linux no Windows e VHDX adicionando INSTALLDIR="<FULLY_QUALIFIED_PATH>" parâmetros e VHDXDIR="<FULLY_QUALIFIED_PATH>" ao comando install. Por exemplo, se você quiser usar a pasta D:\EFLOW para instalação e D :\EFLOW-VHDX para o VHDX, poderá usar o seguinte cmdlet do PowerShell.

   Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn","INSTALLDIR=D:\EFLOW", "VHDXDIR=D:\EFLOW-VHDX"
   

3. Defina a política de execução no dispositivo de destino como AllSigned se ainda não estiver. Consulte os pré-requisitos do PowerShell para comandos para verificar a política de execução atual e definir a política de execução como AllSigned.

4. Crie a implantação do IoT Edge para Linux no Windows. A implantação cria sua máquina virtual Linux e instala o tempo de execução do IoT Edge para você.

   Deploy-Eflow
   

   Gorjeta

   Por padrão, o Deploy-Eflow comando cria sua máquina virtual Linux com 1 GB de RAM, 1 núcleo vCPU e 16 GB de espaço em disco. No entanto, os recursos de que sua VM precisa dependem muito das cargas de trabalho implantadas. Se sua VM não tiver memória suficiente para suportar suas cargas de trabalho, ela não será iniciada.

   Você pode personalizar os recursos disponíveis da máquina virtual usando os Deploy-Eflow parâmetros opcionais do comando. Isso é necessário para implantar o EFLOW em um dispositivo com os requisitos mínimos de hardware.

   Por exemplo, o comando abaixo cria uma máquina virtual com 1 núcleo vCPU, 1 GB de RAM (representado em MB) e 2 GB de espaço em disco:

   Deploy-Eflow -cpuCount 1 -memoryInMB 1024 -vmDataSize 2
   

   Para obter informações sobre todos os parâmetros opcionais disponíveis, consulte Funções do PowerShell para IoT Edge para Linux no Windows.

   Aviso

   Por padrão, a máquina virtual EFLOW Linux não tem configuração de DNS. As implantações usando DHCP tentarão obter a configuração DNS propagada pelo servidor DHCP. Verifique a configuração do DNS para garantir a conectividade com a Internet. Para obter mais informações, consulte AzEFLOW-DNS.

   Você pode atribuir uma GPU à sua implantação para habilitar módulos Linux acelerados por GPU. Para obter acesso a esses recursos, você precisará instalar os pré-requisitos detalhados em Aceleração de GPU para o Azure IoT Edge para Linux no Windows.

   Para usar uma passagem de GPU, adicione os parâmetros gpuName, gpuPassthroughType e gpuCount ao comando Deploy-Eflow . Para obter informações sobre todos os parâmetros opcionais disponíveis, consulte Funções do PowerShell para IoT Edge para Linux no Windows.

   Aviso

   Habilitar a passagem de dispositivo de hardware pode aumentar os riscos de segurança. A Microsoft recomenda um driver de mitigação de dispositivo do fornecedor da GPU, quando aplicável. Para obter mais informações, consulte Implantar dispositivos gráficos usando atribuição de dispositivo discreto.

5. Digite 'Y' para aceitar os termos da licença.

6. Digite 'O' ou 'R' para ativar ou desativar os dados de diagnóstico opcionais, dependendo da sua preferência.

7. Quando a implantação estiver concluída, a janela do PowerShell relatará a implantação bem-sucedida.

   

   Após uma implantação bem-sucedida, você estará pronto para provisionar seu dispositivo.

Provisionar o dispositivo com sua identidade na nuvem

Você está pronto para configurar seu dispositivo com sua identidade na nuvem e informações de autenticação.

Para provisionar seu dispositivo usando certificados X.509, você precisará do nome do hub IoT, da ID do dispositivo e dos caminhos absolutos para o certificado de identidade e a chave privada na máquina host Windows.

Tenha o certificado de identidade do dispositivo e sua chave privada correspondente prontos no dispositivo de destino. Conheça o caminho absoluto para ambos os arquivos.

Execute o seguinte comando em uma sessão elevada do PowerShell no dispositivo de destino. Substitua o texto do espaço reservado pelos seus próprios valores.

Provision-EflowVm -provisioningType ManualX509 -iotHubHostname "HUB_HOSTNAME_HERE" -deviceId "DEVICE_ID_HERE" -identityCertPath "ABSOLUTE_PATH_TO_IDENTITY_CERT_HERE" -identityPrivKeyPath "ABSOLUTE_PATH_TO_PRIVATE_KEY_HERE"

Para obter mais informações sobre o Provision-EflowVM comando, consulte Funções do PowerShell para IoT Edge para Linux no Windows.

Verificar a configuração bem-sucedida

Verifique se o IoT Edge para Linux no Windows foi instalado e configurado com êxito no seu dispositivo IoT Edge.

1. Faça login na máquina virtual do IoT Edge para Linux no Windows usando o seguinte comando na sessão do PowerShell:

   Connect-EflowVm
   

   Nota

   A única conta permitida para SSH para a máquina virtual é o usuário que a criou.

2. Depois de fazer login, você pode verificar a lista de módulos do IoT Edge em execução usando o seguinte comando do Linux:

   sudo iotedge list
   

3. Se você precisar solucionar problemas do serviço IoT Edge, use os seguintes comandos do Linux.

   1. Recupere os logs de serviço.

      sudo iotedge system logs
      

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

      sudo iotedge check
      

   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 - Erro

   Nã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 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 IoT Edge Hub.

Quando você cria um novo dispositivo IoT Edge, ele exibirá o código 417 -- The device's deployment configuration is not set de status no portal do Azure. Esse status é normal e significa que o dispositivo está pronto para receber uma implantação de módulo.

Desinstalar o IoT Edge para Linux no Windows

Se você quiser remover a instalação do Azure IoT Edge para Linux no Windows do seu dispositivo, use os comandos a seguir.

1. Abrir Definições no Windows
2. Selecione Adicionar ou remover programas
3. Selecione o aplicativo Azure IoT Edge
4. Selecione Desinstalar

Próximos passos

• Continue a implantar módulos do IoT Edge para saber como implantar módulos em seu dispositivo.
• Saiba como gerenciar certificados em sua máquina virtual IoT Edge para Linux no Windows e transferir arquivos do sistema operacional host para sua máquina virtual Linux.
• Saiba como configurar seus dispositivos IoT Edge para se comunicarem por meio de um servidor proxy.