Criar e provisionar dispositivos IoT Edge em escala no Windows usando certificados X.509

Aplica-se a: IoT Edge 1.1

Importante

A data de fim do suporte do IoT Edge 1.1 foi 13 de dezembro de 2022. Consulte o Ciclo de Vida de Produtos da Microsoft para obter informações sobre como é suportado este 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 completas para o provisionamento automático de um ou mais dispositivos Windows IoT Edge usando certificados X.509. Você pode provisionar automaticamente dispositivos do Azure IoT Edge com o serviço de provisionamento de dispositivo (DPS) do Hub IoT do Azure. Se você não estiver familiarizado com o processo de provisionamento automático, revise a visão geral do provisionamento antes de continuar.

Nota

O Azure IoT Edge com contêineres do Windows não terá suporte a partir da versão 1.2 do Azure IoT Edge.

Considere usar o novo método para executar o IoT Edge em dispositivos Windows, Azure IoT Edge para Linux no Windows.

Se quiser usar o Azure IoT Edge para Linux no Windows, siga as etapas no guia de instruções equivalente.

As tarefas são as seguintes:

1. Gere certificados e chaves.
2. Crie um registro individual para um único dispositivo ou um registro de grupo para um conjunto de dispositivos.
3. Instale o tempo de execução do IoT Edge e registre o dispositivo no Hub IoT.

Usar certificados X.509 como um mecanismo de atestado é uma excelente maneira de dimensionar a produção e simplificar o provisionamento de dispositivos. Normalmente, os certificados X.509 são organizados em uma cadeia de confiança de certificados. Começando com um certificado raiz autoassinado ou confiável, cada certificado na cadeia assina o próximo certificado inferior. Esse padrão cria uma cadeia delegada de confiança do certificado raiz até o certificado de dispositivo downstream final instalado em um dispositivo.

Pré-requisitos

Recursos na nuvem

• Um hub IoT ativo
• Uma instância do serviço de provisionamento de dispositivo do Hub IoT no Azure, vinculada ao seu hub IoT
  • Se você não tiver uma instância de serviço de provisionamento de dispositivo, poderá seguir as instruções nas seções Criar um novo serviço de provisionamento de dispositivo do Hub IoT e Vincular o hub IoT e o serviço de provisionamento de dispositivo do início rápido do serviço de provisionamento de dispositivos do Hub IoT.
  • Depois de executar o serviço de provisionamento de dispositivo, copie o valor de ID Scope da página de visão geral. Você usa esse valor ao configurar o tempo de execução do IoT Edge.

Requisitos do dispositivo

Um dispositivo Windows físico ou virtual para ser o dispositivo IoT Edge.

Gerar certificados de identidade de dispositivo

O certificado de identidade do dispositivo é um certificado de dispositivo downstream que se conecta por meio de uma cadeia de confiança de certificados ao certificado de autoridade de certificação (CA) X.509 superior. O certificado de identidade do dispositivo deve ter seu nome comum (CN) definido como a ID do dispositivo que você deseja que o dispositivo tenha em seu hub IoT.

Os certificados de identidade de dispositivo são usados apenas para provisionar o dispositivo IoT Edge e autenticar o dispositivo com o Hub IoT do Azure. Eles não estão assinando certificados, ao contrário dos certificados de CA que o dispositivo IoT Edge apresenta aos módulos ou dispositivos downstream para verificação. Para obter mais informações, consulte Detalhes de uso do certificado do Azure IoT Edge.

Depois de criar o certificado de identidade do dispositivo, você deve ter dois arquivos: um arquivo .cer ou .pem que contém a parte pública do certificado e um arquivo .cer ou .pem com a chave privada do certificado. Se você planeja usar o registro de grupo no DPS, também precisará da parte pública de um certificado de CA intermediário ou raiz na mesma cadeia de confiança de certificados.

Você precisa dos seguintes arquivos para configurar o provisionamento automático com X.509:

• O certificado de identidade do dispositivo e seu certificado de chave privada. O certificado de identidade do dispositivo é carregado no DPS se você criar um registro individual. A chave privada é passada para o tempo de execução do IoT Edge.
• Um certificado de cadeia completa, que deve conter, pelo menos, a identidade do dispositivo e os certificados intermédios. O certificado de cadeia completa é passado para o tempo de execução do IoT Edge.
• Um certificado de autoridade de certificação intermediário ou raiz da cadeia de confiança de certificados. Este certificado é carregado no DPS se você criar um registro de grupo.

Nota

Atualmente, uma limitação no libiothsm impede o uso de certificados que expiram em ou após 1º de janeiro de 2038.

Usar certificados de teste (opcional)

Se você não tiver uma autoridade de certificação disponível para criar novos certificados de identidade e quiser experimentar esse cenário, o repositório git do Azure IoT Edge contém scripts que você pode usar para gerar certificados de teste. Esses certificados são projetados apenas para testes de desenvolvimento e não devem ser usados na produção.

Para criar certificados de teste, siga as etapas em Criar certificados de demonstração para testar os recursos do dispositivo IoT Edge. Conclua as duas seções necessárias para configurar os scripts de geração de certificado e criar um certificado de autoridade de certificação raiz. Em seguida, siga as etapas para criar um certificado de identidade de dispositivo. Quando terminar, você deverá ter a seguinte cadeia de certificados e par de chaves:

• <WRKDIR>\certs\iot-edge-device-identity-<name>-full-chain.cert.pem
• <WRKDIR>\private\iot-edge-device-identity-<name>.key.pem

Você precisa desses dois certificados no dispositivo IoT Edge. Se você vai usar o registro individual no DPS, então você carregará o arquivo .cert.pem. Se você vai usar o registro de grupo no DPS, também precisará de um certificado de CA intermediário ou raiz na mesma cadeia de confiança de certificados para carregar. Se você estiver usando certificados de demonstração, use o <WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pem certificado para inscrição em grupo.

Criar um registro DPS

Use seus certificados e chaves gerados para criar um registro no DPS para um ou mais dispositivos IoT Edge.

Se você deseja provisionar um único dispositivo IoT Edge, crie um registro individual. Se você precisar de vários dispositivos provisionados, siga as etapas para criar um registro de grupo DPS.

Ao criar um registro no DPS, você tem a oportunidade de declarar um Estado Gêmeo Inicial do Dispositivo. No gêmeo de dispositivo, você pode definir tags para agrupar dispositivos por qualquer métrica necessária em sua solução, como região, ambiente, local ou tipo de dispositivo. Essas tags são usadas para criar implantações automáticas.

Para obter mais informações sobre inscrições no serviço de provisionamento de dispositivos, consulte Como gerenciar registros de dispositivos.

Inscrição individual

Criar uma inscrição individual do DPS

As inscrições individuais tomam a parte pública do certificado de identidade de um dispositivo e fazem a correspondência com o certificado no dispositivo.

Gorjeta

As etapas neste artigo são para o portal do Azure, mas você também pode criar inscrições individuais usando a CLI do Azure. Para obter mais informações, consulte az iot dps enrollment. Como parte do comando CLI, use o sinalizador habilitado para borda para especificar que o registro é para um dispositivo IoT Edge.

1. No portal do Azure, navegue até sua instância do serviço de provisionamento de dispositivo do Hub IoT.

2. Em Configurações, selecione Gerenciar inscrições.

3. Selecione Adicionar inscrição individual e conclua as seguintes etapas para configurar o registro:

   • Mecanismo: Selecione X.509.

   • Arquivo .pem ou .cer do certificado primário: carregue o arquivo público do certificado de identidade do dispositivo. Se você usou os scripts para gerar um certificado de teste, escolha o seguinte arquivo:

     <WRKDIR>\certs\iot-edge-device-identity-<name>.cert.pem

   • ID do dispositivo do Hub IoT: forneça uma ID para o seu dispositivo, se desejar. Você pode usar IDs de dispositivo para direcionar um dispositivo individual para implantação de módulo. Se você não fornecer uma ID de dispositivo, o nome comum (CN) no certificado X.509 será usado.

   • Dispositivo IoT Edge: selecione True para declarar que o registro é para um dispositivo IoT Edge.

   • Selecione os hubs IoT aos quais este dispositivo pode ser atribuído: Escolha o hub IoT vinculado ao qual você deseja conectar seu dispositivo. Você pode escolher vários hubs e o dispositivo será atribuído a um deles de acordo com a política de alocação selecionada.

   • Estado gêmeo inicial do dispositivo: adicione um valor de tag a ser adicionado ao gêmeo do dispositivo, se desejar. Você pode usar tags para segmentar grupos de dispositivos para implantação automática. Por exemplo:

     {
         "tags": {
            "environment": "test"
         },
         "properties": {
            "desired": {}
         }
     }
     

4. Selecione Guardar.

Em Gerenciar Inscrições, você pode ver a ID de Registro da inscrição que acabou de criar. Anote isso, pois ele pode ser usado quando você provisionar seu dispositivo.

Agora que existe um registro para esse dispositivo, o tempo de execução do IoT Edge pode provisionar automaticamente o dispositivo durante a instalação.

Inscrição em grupo

Criar um registro de grupo DPS

As inscrições de grupo usam um certificado de autoridade de certificação intermediário ou raiz da cadeia de confiança de certificados usada para gerar os certificados de identidade de dispositivo individual.

Verifique seu certificado raiz

Ao criar um grupo de inscrição, você tem a opção de usar um certificado verificado. Você pode verificar um certificado com DPS provando que você tem a propriedade do certificado raiz. Para obter mais informações, consulte Como fazer prova de posse para certificados de CA X.509.

1. No portal do Azure, navegue até sua instância do serviço de provisionamento de dispositivo do Hub IoT.

2. Selecione Certificados no menu à esquerda.

3. Selecione Adicionar para adicionar um novo certificado.

4. Insira um nome amigável para seu certificado e navegue até o arquivo .cer ou .pem que representa a parte pública do seu certificado X.509.

   Se você estiver usando os certificados de demonstração, carregue o <wrkdir>\certs\azure-iot-test-only.root.ca.cert.pem certificado.

5. Selecione Guardar.

6. Seu certificado agora deve ser listado na página Certificados . Selecione-o para abrir os detalhes do certificado.

7. Selecione Gerar código de verificação e copie o código gerado.

8. Se você trouxe seu próprio certificado de CA ou está usando os certificados de demonstração, você pode usar a ferramenta de verificação fornecida no repositório do IoT Edge para verificar a prova de posse. A ferramenta de verificação usa seu certificado de autoridade de certificação para assinar um novo certificado que tem o código de verificação fornecido como o nome do assunto.

   New-CACertsVerificationCert "<verification code>"
   

9. Na mesma página de detalhes do certificado no portal do Azure, carregue o certificado de verificação recém-gerado.

10. Selecione Verificar.

Criar grupo de inscrição

Para obter mais informações sobre inscrições no serviço de provisionamento de dispositivos, consulte Como gerenciar registros de dispositivos.

Gorjeta

As etapas neste artigo são para o portal do Azure, mas você também pode criar inscrições de grupo usando a CLI do Azure. Para obter mais informações, consulte az iot dps enrollment-group. Como parte do comando CLI, use o sinalizador habilitado para borda para especificar que o registro é para dispositivos IoT Edge. Para um registro de grupo, todos os dispositivos devem ser dispositivos IoT Edge ou nenhum deles pode ser.

1. No portal do Azure, navegue até sua instância do serviço de provisionamento de dispositivo do Hub IoT.

2. Em Configurações, selecione Gerenciar inscrições.

3. Selecione Adicionar grupo de inscrição e conclua as seguintes etapas para configurar o registro:

   • Nome do grupo: forneça um nome memorável para esta inscrição de grupo.

   • Tipo de atestado: Selecione Certificado.

   • Dispositivo IoT Edge: selecione True. Para um registro de grupo, todos os dispositivos devem ser dispositivos IoT Edge ou nenhum deles pode ser.

   • Tipo de certificado: selecione Certificado da autoridade de certificação.

   • Certificado principal: escolha seu certificado na lista suspensa.

   • Selecione os hubs IoT aos quais este dispositivo pode ser atribuído: Escolha o hub IoT vinculado ao qual você deseja conectar seu dispositivo. Você pode escolher vários hubs e o dispositivo será atribuído a um deles de acordo com a política de alocação selecionada.

   • Estado gêmeo inicial do dispositivo: adicione um valor de tag a ser adicionado ao gêmeo do dispositivo, se desejar. Você pode usar tags para segmentar grupos de dispositivos para implantação automática. Por exemplo:

     {
         "tags": {
            "environment": "test"
         },
         "properties": {
            "desired": {}
         }
     }
     

4. Selecione Guardar.

Em Gerenciar Inscrições, você pode ver a ID de Registro da inscrição que acabou de criar. Anote isso, pois ele pode ser usado quando você provisionar seus dispositivos.

Agora que existe um registro para esses dispositivos, o tempo de execução do IoT Edge pode provisionar automaticamente os dispositivos durante a instalação.

Instalar o IoT Edge

Nesta seção, você prepara sua VM do Windows ou dispositivo físico para o IoT Edge. Em seguida, instale o IoT Edge.

O Azure IoT Edge depende de um tempo de execução de contêiner compatível com OCI. Moby, um mecanismo baseado em Moby, está incluído no script de instalação, o que significa que não há etapas adicionais para instalar o mecanismo.

Para instalar o tempo de execução do IoT Edge:

1. Execute o PowerShell como um administrador.

   Use uma sessão AMD64 do PowerShell, não o PowerShell(x86). Se não tiver certeza de qual tipo de sessão está usando, execute o seguinte comando:

   (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
   

2. Execute o comando Deploy-IoTEdge , que executa as seguintes tarefas:

   • Verifica se a sua máquina Windows está numa versão suportada
   • Ativa o recurso de contêineres
   • Baixa o mecanismo moby e o tempo de execução do IoT Edge

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Deploy-IoTEdge
   

3. Reinicie o dispositivo, se solicitado.

Ao instalar o IoT Edge em um dispositivo, você pode usar parâmetros adicionais para modificar o processo, incluindo:

• Tráfego direto para passar por um servidor proxy
• Aponte o instalador para um diretório local para instalação offline

Para obter mais informações sobre esses parâmetros adicionais, consulte Scripts do PowerShell para IoT Edge com contêineres do Windows.

Provisionar o dispositivo com sua identidade na nuvem

Depois que o tempo de execução estiver instalado em seu dispositivo, configure o dispositivo com as informações que ele usa para se conectar ao serviço de provisionamento do dispositivo e ao Hub IoT.

Tenha as seguintes informações prontas:

• O valor DPS ID Scope . Você pode recuperar esse valor na página de visão geral da sua instância do DPS no portal do Azure.
• O arquivo de cadeia de certificados de identidade do dispositivo no dispositivo.
• O arquivo de chave de identidade do dispositivo no dispositivo.

1. Abra uma janela do PowerShell no modo de administrador. Certifique-se de usar uma sessão AMD64 do PowerShell ao instalar o IoT Edge, não o PowerShell (x86).

2. O comando Initialize-IoTEdge configura o tempo de execução do IoT Edge em sua máquina. O comando assume como padrão o provisionamento manual com contêineres do Windows, portanto, use o sinalizador para usar o -DpsX509 provisionamento automático com autenticação de certificado X.509.

   Substitua os valores de espaço reservado para scope_id, identity cert chain pathe identity key path pelos valores apropriados da instância do DPS e dos caminhos de arquivo no dispositivo.

   Adicione o -RegistrationId paste_registration_id_here parâmetro se desejar definir o ID do dispositivo como algo diferente do nome CN do certificado de identidade.

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -DpsX509 -ScopeId paste_scope_id_here -X509IdentityCertificate paste_identity_cert_chain_path_here -X509IdentityPrivateKey paste_identity_key_path_here
   

   Gorjeta

   O arquivo de configuração armazena seu certificado e informações de chave como URIs de arquivo. No entanto, o comando Initialize-IoTEdge lida com essa etapa de formatação para você, para que você possa fornecer o caminho absoluto para o certificado e os arquivos de chave em seu dispositivo.

Verificar se a instalação foi bem-sucedida

Se o tempo de execução tiver sido iniciado com êxito, você poderá entrar no Hub IoT e começar a implantar módulos do IoT Edge no seu dispositivo.

Inscrição individual

Você pode verificar se o registro individual criado no serviço de provisionamento de dispositivo foi usado. Navegue até a instância do serviço de provisionamento de dispositivo no portal do Azure. Abra os detalhes de inscrição para o registro individual que você criou. Observe que o status do registro é atribuído e o ID do dispositivo está listado.

Inscrição em grupo

Você pode verificar se o registro de grupo criado no serviço de provisionamento de dispositivo foi usado. Navegue até a instância do serviço de provisionamento de dispositivo no portal do Azure. Abra os detalhes de inscrição para o registro de grupo que você criou. Aceda ao separador Registos de Registo para ver todos os dispositivos registados nesse grupo.

Use os seguintes comandos em seu dispositivo para verificar se o IoT Edge foi instalado e iniciado com êxito.

Verifique o estado do serviço IoT Edge.

Get-Service iotedge

Examine os logs de serviço.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

Listar módulos em execução.

iotedge list

Próximos passos

O processo de registro do serviço de provisionamento de dispositivos permite definir a ID do dispositivo e as tags gêmeas do dispositivo ao mesmo tempo em que provisiona o novo dispositivo. Você pode usar esses valores para segmentar dispositivos individuais ou grupos de dispositivos usando o gerenciamento automático de dispositivos. Saiba como Implantar e monitorar módulos do IoT Edge em escala usando o portal do Azure ou usando a CLI do Azure.