Gerenciar um dispositivo FPGA do Azure Stack Edge Pro por meio do Windows PowerShell

A solução FPGA do Azure Stack Edge Pro permite processar dados e enviá-los pela rede para o Azure. Este artigo descreve algumas das tarefas de configuração e gerenciamento para seu dispositivo FPGA Azure Stack Edge Pro. Você pode usar o portal do Azure, a interface do usuário da Web local ou a interface do Windows PowerShell para gerenciar seu dispositivo.

Este artigo se concentra nas tarefas que você faz usando a interface do PowerShell.

Este artigo inclui os seguintes procedimentos:

• Ligue-se à interface do PowerShell
• Criar um pacote de suporte
• Carregar certificado
• Repor o dispositivo
• Ver informações do dispositivo
• Obter logs de computação
• Monitorar e solucionar problemas de módulos de computação

Ligue-se à interface do PowerShell

Dependendo do sistema operacional do cliente, os procedimentos para se conectar remotamente ao dispositivo são diferentes.

Conectar-se remotamente a partir de um cliente Windows

Antes de começar, verifique se o cliente Windows está executando o Windows PowerShell 5.0 ou posterior.

Siga estas etapas para se conectar remotamente a partir de um cliente Windows.

1. Execute uma sessão do Windows PowerShell como administrador.

2. Certifique-se de que o serviço de Gestão Remota do Windows está em execução no seu cliente. Na linha de comandos, escreva:

   winrm quickconfig

   Para obter mais informações, consulte Instalação e configuração do Gerenciamento Remoto do Windows.

3. Atribua uma variável ao endereço IP do dispositivo.

   $ip = "<device_ip>"

   Substitua <device_ip> pelo endereço IP do seu dispositivo.

4. Para adicionar o endereço IP do seu dispositivo à lista de hosts confiáveis do cliente, digite o seguinte comando:

   Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force

5. Inicie uma sessão do Windows PowerShell no dispositivo:

   Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell

6. Forneça a senha quando solicitado. Use a mesma senha usada para entrar na interface do usuário da Web local. A senha padrão da interface do usuário da Web local é Password1. Quando você se conecta com êxito ao dispositivo usando o PowerShell remoto, você vê a seguinte saída de exemplo:

   Windows PowerShell
   Copyright (C) Microsoft Corporation. All rights reserved.
   
   PS C:\WINDOWS\system32> winrm quickconfig
   WinRM service is already running on this machine.
   PS C:\WINDOWS\system32> $ip = "10.100.10.10"
   PS C:\WINDOWS\system32> Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
   PS C:\WINDOWS\system32> Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell
   
   WARNING: The Windows PowerShell interface of your device is intended to be used only for the initial network configuration. Please engage Microsoft Support if you need to access this interface to troubleshoot any potential issues you may be experiencing. Changes made through this interface without involving Microsoft Support could result in an unsupported configuration.
   [10.100.10.10]: PS>
   

Conecte-se remotamente a partir de um cliente Linux

No cliente Linux que você usará para se conectar:

• Instale o PowerShell Core para Linux mais recente do GitHub para obter o recurso de comunicação remota SSH.
• Instale apenas o gss-ntlmssp pacote a partir do módulo NTLM. Para clientes Ubuntu, use o seguinte comando:
  • sudo apt-get install gss-ntlmssp

Para obter mais informações, vá para Comunicação remota do PowerShell sobre SSH.

Siga estas etapas para se conectar remotamente a partir de um cliente NFS.

1. Para abrir a sessão do PowerShell, digite:

   pwsh

2. Para se conectar usando o cliente remoto, digite:

   Enter-PSSession -ComputerName $ip -Authentication Negotiate -ConfigurationName Minishell -Credential ~\EdgeUser

   Quando solicitado, forneça a senha usada para entrar no dispositivo.

Criar um pacote de suporte

Se você tiver algum problema de dispositivo, você pode criar um pacote de suporte a partir dos logs do sistema. O Suporte da Microsoft usa este pacote para solucionar os problemas. Siga estas etapas para criar um pacote de suporte:

1. Conecte-se à interface do PowerShell do seu dispositivo.

2. Use o Get-HcsNodeSupportPackage comando para criar um pacote de suporte. O uso do cmdlet é o seguinte:

   Get-HcsNodeSupportPackage [-Path] <string> [-Zip] [-ZipFileName <string>] [-Include {None | RegistryKeys | EtwLogs
           | PeriodicEtwLogs | LogFiles | DumpLog | Platform | FullDumps | MiniDumps | ClusterManagementLog | ClusterLog |
           UpdateLogs | CbsLogs | StorageCmdlets | ClusterCmdlets | ConfigurationCmdlets | KernelDump | RollbackLogs |
           Symbols | NetworkCmdlets | NetworkCmds | Fltmc | ClusterStorageLogs | UTElement | UTFlag | SmbWmiProvider |
           TimeCmds | LocalUILogs | ClusterHealthLogs | BcdeditCommand | BitLockerCommand | DirStats | ComputeRolesLogs |
           ComputeCmdlets | DeviceGuard | Manifests | MeasuredBootLogs | Stats | PeriodicStatLogs | MigrationLogs |
           RollbackSupportPackage | ArchivedLogs | Default}] [-MinimumTimestamp <datetime>] [-MaximumTimestamp <datetime>]
           [-IncludeArchived] [-IncludePeriodicStats] [-Credential <pscredential>]  [<CommonParameters>]
   

   O cmdlet coleta logs do seu dispositivo e copia esses logs para uma rede especificada ou compartilhamento local.

   Os parâmetros utilizados são os seguintes:

   • -Path - Especifique a rede ou o caminho local para o qual copiar o pacote de suporte. (necessário)
   • -Credential - Especifique as credenciais para acessar o caminho protegido.
   • -Zip - Especifique para gerar um arquivo zip.
   • -Include - Especificar para incluir os componentes a serem incluídos no pacote de suporte. Se não for especificado, Default é assumido.
   • -IncludeArchived - Especifique para incluir logs arquivados no pacote de suporte.
   • -IncludePeriodicStats - Especifique para incluir logs de estatísticas periódicos no pacote de suporte.

Carregar certificado

Um certificado SSL adequado garante que está a enviar informações encriptadas para o servidor correto. Além da encriptação, o certificado também permite a autenticação. Você pode carregar seu próprio certificado SSL confiável por meio da interface PowerShell do dispositivo.

1. Ligar à interface do PowerShell.

2. Use o Set-HcsCertificate cmdlet para carregar o certificado. Quando lhe for solicitado, indique os seguintes parâmetros:

   • CertificateFilePath - Caminho para o compartilhamento que contém o arquivo de certificado no formato .pfx .

   • CertificatePassword - Uma senha usada para proteger o certificado.

   • Credentials – o nome de utilizador para aceder à partilha que contém o certificado. Indique a palavra-passe para a partilha de rede quando lhe for pedido.

     O exemplo a seguir mostra o uso desse cmdlet:

     Set-HcsCertificate -Scope LocalWebUI -CertificateFilePath "\\myfileshare\certificates\mycert.pfx" -CertificatePassword "mypassword" -Credential "Username"
     

Também pode carregar certificados do IoT Edge para permitir uma ligação segura entre o dispositivo IoT Edge e os dispositivos a jusante que se podem ligar ao mesmo. Há três arquivos (formato .pem ) que você precisa instalar:

• Certificado de autoridade de certificação raiz ou a autoridade de certificação proprietária
• Certificado de autoridade de certificação do dispositivo
• Chave privada do dispositivo

O exemplo a seguir mostra o uso desse cmdlet para instalar certificados do IoT Edge:

Set-HcsCertificate -Scope IotEdge -RootCACertificateFilePath "\\hcfs\root-ca-cert.pem" -DeviceCertificateFilePath "\\hcfs\device-ca-cert.pem\" -DeviceKeyFilePath "\\hcfs\device-private-key.pem" -Credential "username"

Ao executar esse cmdlet, você será solicitado a fornecer a senha para o compartilhamento de rede.

Para obter mais informações sobre certificados, vá para Certificados do Azure IoT Edge ou Instalar certificados em um gateway.

Ver informações do dispositivo

1. Ligar à interface do PowerShell.

2. Use o Get-HcsApplianceInfo para obter as informações do seu dispositivo.

   O exemplo a seguir mostra o uso desse cmdlet:

   [10.100.10.10]: PS>Get-HcsApplianceInfo
   
   Id                            : b2044bdb-56fd-4561-a90b-407b2a67bdfc
   FriendlyName                  : DBE-NBSVFQR94S6
   Name                          : DBE-NBSVFQR94S6
   SerialNumber                  : HCS-NBSVFQR94S6
   DeviceId                      : 40d7288d-cd28-481d-a1ea-87ba9e71ca6b
   Model                         : Virtual
   FriendlySoftwareVersion       : Data Box Gateway 1902
   HcsVersion                    : 1.4.771.324
   IsClustered                   : False
   IsVirtual                     : True
   LocalCapacityInMb             : 1964992
   SystemState                   : Initialized
   SystemStatus                  : Normal
   Type                          : DataBoxGateway
   CloudReadRateBytesPerSec      : 0
   CloudWriteRateBytesPerSec     : 0
   IsInitialPasswordSet          : True
   FriendlySoftwareVersionNumber : 1902
   UploadPolicy                  : All
   DataDiskResiliencySettingName : Simple
   ApplianceTypeFriendlyName     : Data Box Gateway
   IsRegistered                  : False
   

   Aqui está uma tabela resumindo algumas das informações importantes do dispositivo:

   Parâmetro	Description
   FriendlyName	O nome amigável do dispositivo, conforme configurado por meio da interface do usuário da Web local durante a implantação do dispositivo. O nome amigável padrão é o número de série do dispositivo.
   SerialNumber	O número de série do dispositivo é um número exclusivo atribuído na fábrica.
   Modelo	O modelo para seu dispositivo Azure Stack Edge ou Data Box Gateway. O modelo é físico para o Azure Stack Edge e virtual para o Data Box Gateway.
   FriendlySoftwareVersion	A cadeia de caracteres amigável que corresponde à versão do software do dispositivo. Para um sistema executando a visualização, a versão de software amigável seria Data Box Edge 1902.
   HcsVersion	A versão do software HCS em execução no seu dispositivo. Por exemplo, a versão do software HCS correspondente ao Data Box Edge 1902 é 1.4.771.324.
   LocalCapacityInMb	A capacidade local total do dispositivo em Megabits.
   IsRegistered	Este valor indica se o seu dispositivo está ativado com o serviço.

Repor o dispositivo

Para repor o seu dispositivo, tem de limpar de forma segura todos os dados do disco de dados e do disco de arranque do seu dispositivo.

Utilize o cmdlet Reset-HcsAppliance para limpar tanto os discos de dados como o disco de arranque ou apenas os discos de dados. Os SecureWipeBootDisk switches e SecureWipeDataDisks permitem que você limpe o disco de inicialização e os discos de dados, respectivamente.

O comutador SecureWipeBootDisk limpa o disco de arranque e torna o dispositivo inutilizável. Só deve utilizá-lo quando tiver de devolver o dispositivo à Microsoft. Para obter mais informações, veja Devolver o dispositivo à Microsoft.

Se utilizar a reposição do dispositivo na IU da Web local, apenas os discos de dados são limpos de forma segura, mas o disco de arranque mantém-se intacto. O disco de arranque contém a configuração do dispositivo.

1. Ligar à interface do PowerShell.

2. Na linha de comandos, escreva:

   Reset-HcsAppliance -SecureWipeBootDisk -SecureWipeDataDisks

   O seguinte exemplo mostra como utilizar este cmdlet:

   [10.128.24.33]: PS>Reset-HcsAppliance -SecureWipeBootDisk -SecureWipeDataDisks
   
   Confirm
   Are you sure you want to perform this action?
   Performing the operation "Reset-HcsAppliance" on target "ShouldProcess appliance".
   [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"): N
   

Obter logs de computação

Se a função de computação estiver configurada em seu dispositivo, você também poderá obter os logs de computação por meio da interface do PowerShell.

1. Ligar à interface do PowerShell.

2. Use o Get-AzureDataBoxEdgeComputeRoleLogs para obter os logs de computação para o seu dispositivo.

   O exemplo a seguir mostra o uso desse cmdlet:

   Get-AzureDataBoxEdgeComputeRoleLogs -Path "\\hcsfs\logs\myacct" -Credential "username" -FullLogCollection
   

   Aqui está uma descrição dos parâmetros usados para o cmdlet:

   • Path: Forneça um caminho de rede para o compartilhamento onde você deseja criar o pacote de log de computação.
   • Credential: Forneça o nome de usuário para o compartilhamento de rede. Ao executar esse cmdlet, você precisará fornecer a senha de compartilhamento.
   • FullLogCollection: Este parâmetro garante que o pacote de log conterá todos os logs de computação. Por padrão, o pacote de log contém apenas um subconjunto de logs.

Monitorar e solucionar problemas de módulos de computação

Em um dispositivo Azure Stack Edge que tenha a função de computação configurada, você pode solucionar problemas ou monitorar o dispositivo usando dois conjuntos diferentes de comandos.

• Usando iotedge comandos. Estes comandos estão disponíveis para operações básicas para o seu dispositivo.
• Usando dkrdbe comandos. Estes comandos estão disponíveis para um conjunto extensivo de operações para o seu dispositivo.

Para executar qualquer um dos comandos acima, você precisa se conectar à interface do PowerShell.

Usar iotedge comandos

Para ver uma lista de comandos disponíveis, conecte-se à interface do PowerShell e use a iotedge função.

[10.100.10.10]: PS>iotedge -?                                                                                                                                                                                                 Usage: iotedge COMMAND

Commands:
   check
   list
   logs
   restart

[10.100.10.10]: PS>

A tabela a seguir tem uma breve descrição dos comandos disponíveis para iotedge:

Usar dkrdbe comandos

Para ver uma lista de comandos disponíveis, conecte-se à interface do PowerShell e use a dkrdbe função.

[10.100.10.10]: PS>dkrdbe -?
Usage: dkrdbe COMMAND

Commands:
   image [prune]
   images
   inspect
   login
   logout
   logs
   port
   ps
   pull
   start
   stats
   stop
   system [df]
   top

[10.100.10.10]: PS>

A tabela a seguir tem uma breve descrição dos comandos disponíveis para dkrdbe:

Para obter ajuda para qualquer comando disponível, use dkrdbe <command-name> --help.

Por exemplo, para entender o uso do port comando, digite:

[10.100.10.10]: P> dkrdbe port --help

Usage:  dkr port CONTAINER [PRIVATE_PORT[/PROTO]]

List port mappings or a specific mapping for the container
[10.100.10.10]: P> dkrdbe login --help

Usage:  docker login [OPTIONS] [SERVER]

Log in to a Docker registry.
If no server is specified, the default is defined by the daemon.

Options:
  -p, --password string   Password
      --password-stdin    Take the password from stdin
  -u, --username string   Username
[10.100.10.10]: PS>

Os comandos disponíveis para a dkrdbe função usam os mesmos parâmetros que os usados para os comandos docker normais. Para obter as opções e parâmetros usados com o comando docker, vá para Usar a linha de comando do Docker.

Para verificar se o módulo implantado com êxito

Os módulos de computação são contêineres que têm uma lógica de negócios implementada. Para verificar se um módulo de computação foi implantado com êxito, execute o ps comando e verifique se o contêiner (correspondente ao módulo de computação) está em execução.

Para obter a lista de todos os contêineres (incluindo os que estão pausados), execute o ps -a comando.

[10.100.10.10]: P> dkrdbe ps -a
CONTAINER ID        IMAGE                                                COMMAND                   CREATED             STATUS              PORTS                                                                  NAMES
d99e2f91d9a8        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModu…"    2 days ago          Up 2 days                                                                                  movefile
0a06f6d605e9        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModu…"    2 days ago          Up 2 days                                                                                  filemove
2f8a36e629db        mcr.microsoft.com/azureiotedge-hub:1.0               "/bin/sh -c 'echo \"$…"   2 days ago          Up 2 days           0.0.0.0:443->443/tcp, 0.0.0.0:5671->5671/tcp, 0.0.0.0:8883->8883/tcp   edgeHub
acce59f70d60        mcr.microsoft.com/azureiotedge-agent:1.0             "/bin/sh -c 'echo \"$…"   2 days ago          Up 2 days                                                                                  edgeAgent
[10.100.10.10]: PS>

Se houve um erro na criação da imagem do contêiner ou ao extrair a imagem, execute logs edgeAgent. EdgeAgent é o contêiner de tempo de execução do IoT Edge responsável pelo provisionamento de outros contêineres.

Como logs edgeAgent despeja todos os logs, uma boa maneira de ver os erros recentes é usar a opção --tail 20.

[10.100.10.10]: PS>dkrdbe logs edgeAgent --tail 20
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Util.Uds.HttpUdsMessageHandler] - Connected socket /var/run/iotedge/mgmt.sock
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Util.Uds.HttpUdsMessageHandler] - Sending request http://mgmt.sock/modules?api-version=2018-06-28
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Agent] - Getting edge agent config...
2019-02-28 23:38:23.464 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Agent] - Obtained edge agent config
2019-02-28 23:38:23.469 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Edgelet.ModuleManagementHttpClient] - Received a valid Http response from unix:///var/run/iotedge/mgmt.soc
k for List modules
--------------------CUT---------------------
--------------------CUT---------------------
08:28.1007774+00:00","restartCount":0,"lastRestartTimeUtc":"2019-02-26T20:08:28.1007774+00:00","runtimeStatus":"running","version":"1.0","status":"running","restartPolicy":"always
","type":"docker","settings":{"image":"edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64","imageHash":"sha256:47778be0602fb077d7bc2aaae9b0760fbfc7c058bf4df192f207ad6cbb96f7cc","c
reateOptions":"{\"HostConfig\":{\"Binds\":[\"/home/hcsshares/share4-dl460:/home/input\",\"/home/hcsshares/share4-iot:/home/output\"]}}"},"env":{}}
2019-02-28 23:38:28.480 +00:00 [DBG] [Microsoft.Azure.Devices.Edge.Agent.Core.Planners.HealthRestartPlanner] - HealthRestartPlanner created Plan, with 0 command(s).

Para obter logs de contêiner

Para obter logs para um contêiner específico, primeiro liste o contêiner e, em seguida, obtenha os logs para o contêiner no qual você está interessado.

1. Ligar à interface do PowerShell.

2. Para obter a lista de contêineres em execução, execute o ps comando.

   [10.100.10.10]: P> dkrdbe ps
   CONTAINER ID        IMAGE                                                COMMAND                   CREATED             STATUS              PORTS                                                                  NAMES
   d99e2f91d9a8        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModu…"    2 days ago          Up 2 days                                                                                  movefile
   0a06f6d605e9        edgecompute.azurecr.io/filemovemodule2:0.0.1-amd64   "dotnet FileMoveModu…"    2 days ago          Up 2 days                                                                                  filemove
   2f8a36e629db        mcr.microsoft.com/azureiotedge-hub:1.0               "/bin/sh -c 'echo \"$…"   2 days ago          Up 2 days           0.0.0.0:443->443/tcp, 0.0.0.0:5671->5671/tcp, 0.0.0.0:8883->8883/tcp   edgeHub
   acce59f70d60        mcr.microsoft.com/azureiotedge-agent:1.0             "/bin/sh -c 'echo \"$…"   2 days ago          Up 2 days                                                                                  edgeAgent
   

3. Anote a ID do contêiner para o qual você precisa dos logs.

4. Para obter os logs para um contêiner específico, execute o logs comando fornecendo a ID do contêiner.

   [10.100.10.10]: PS>dkrdbe logs d99e2f91d9a8
   02/26/2019 18:21:45: Info: Opening module client connection.
   02/26/2019 18:21:46: Info: Initializing with input: /home/input, output: /home/output.
   02/26/2019 18:21:46: Info: IoT Hub module client initialized.
   02/26/2019 18:22:24: Info: Received message: 1, SequenceNumber: 0 CorrelationId: , MessageId: 081886a07e694c4c8f245a80b96a252a Body: [{"ChangeType":"Created","ShareRelativeFilePath":"\\__Microsoft Data Box Edge__\\Upload\\Errors.xml","ShareName":"share4-dl460"}]
   02/26/2019 18:22:24: Info: Moving input file: /home/input/__Microsoft Data Box Edge__/Upload/Errors.xml to /home/output/__Microsoft Data Box Edge__/Upload/Errors.xml
   02/26/2019 18:22:24: Info: Processed event.
   02/26/2019 18:23:38: Info: Received message: 2, SequenceNumber: 0 CorrelationId: , MessageId: 30714d005eb048e7a4e7e3c22048cf20 Body: [{"ChangeType":"Created","ShareRelativeFilePath":"\\f [10]","ShareName":"share4-dl460"}]
   02/26/2019 18:23:38: Info: Moving input file: /home/input/f [10] to /home/output/f [10]
   02/26/2019 18:23:38: Info: Processed event.
   

Para monitorizar as estatísticas de utilização do dispositivo

Para monitorar a memória, o uso da CPU e a E/S no dispositivo, use o stats comando.

1. Ligar à interface do PowerShell.

2. Execute o stats comando de modo a desativar a transmissão ao vivo e puxar apenas o primeiro resultado.

   dkrdbe stats --no-stream
   

   O exemplo a seguir mostra o uso desse cmdlet:

   [10.100.10.10]: P> dkrdbe stats --no-stream
   CONTAINER ID        NAME          CPU %         MEM USAGE / LIMIT     MEM %         NET I/O             BLOCK I/O           PIDS
   d99e2f91d9a8        movefile      0.0           24.4MiB / 62.89GiB    0.04%         751kB / 497kB       299kB / 0B          14
   0a06f6d605e9        filemove      0.00%         24.11MiB / 62.89GiB   0.04%         679kB / 481kB       49.5MB / 0B         14
   2f8a36e629db        edgeHub       0.18%         173.8MiB / 62.89GiB   0.27%         4.58MB / 5.49MB     25.7MB / 2.19MB     241
   acce59f70d60        edgeAgent     0.00%         35.55MiB / 62.89GiB   0.06%         2.23MB / 2.31MB     55.7MB / 332kB      14
   [10.100.10.10]: PS>
   

Sair da sessão remota

Para sair da sessão remota do PowerShell, feche a janela do PowerShell.

Próximos passos

• Implante o Azure Stack Edge Pro FPGA no portal do Azure.