Implantar e monitorar módulos do IoT Edge em escala usando a CLI do Azure

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS 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.

Crie uma implantação automática do Azure IoT Edge usando a CLI do Azure para gerenciar implantações contínuas para muitos dispositivos ao mesmo tempo. As implantações automáticas para o IoT Edge fazem parte do recurso de gerenciamento de dispositivos do Hub IoT do Azure. As implantações são processos dinâmicos que permitem implantar vários módulos em vários dispositivos, controlar o status e a integridade dos módulos e fazer alterações quando necessário.

Neste artigo, você configura a CLI do Azure e a extensão IoT. Em seguida, você aprenderá como implantar módulos em um conjunto de dispositivos IoT Edge e monitorar o progresso usando os comandos da CLI disponíveis.

Pré-requisitos

• Um hub IoT em sua assinatura do Azure.

• Um ou mais dispositivos IoT Edge.

  Se você não tiver um dispositivo IoT Edge configurado, poderá criar um em uma máquina virtual do Azure. Siga as etapas em um destes artigos de início rápido: Criar um dispositivo Linux virtual ou Criar um dispositivo virtual Windows.

• A CLI do Azure em seu ambiente. Sua versão da CLI do Azure deve ser 2.0.70 ou posterior. Utilize az --version para validar. Esta versão suporta comandos de extensão az e apresenta a arquitetura de comandos Knack.

• A extensão IoT para CLI do Azure.

Configurar um manifesto de implantação

Um manifesto de implantação é um documento JSON que descreve quais módulos implantar, como os dados fluem entre os módulos e as propriedades desejadas dos gêmeos de módulo. Para obter mais informações, consulte Saiba como implantar módulos e estabelecer rotas no IoT Edge.

Para implantar módulos usando a CLI do Azure, salve o manifesto de implantação localmente como um arquivo de .txt. Use o caminho do arquivo na próxima seção quando executar o comando para aplicar a configuração ao seu dispositivo.

Aqui está um manifesto de implantação básica com um módulo como exemplo:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Este exemplo de manifesto de implantação usa o esquema versão 1.1 para o agente e o hub do IoT Edge. A versão 1.1 do esquema foi lançada junto com a versão 1.0.10 do IoT Edge. Ele permite recursos como ordem de inicialização do módulo e priorização de rota.

Implantação em camadas

As implantações em camadas são um tipo de implantação automática que pode ser empilhada umas sobre as outras. Para obter mais informações sobre implantações em camadas, consulte Compreender as implantações automáticas do IoT Edge para dispositivos únicos ou em escala.

As implantações em camadas podem ser criadas e gerenciadas com a CLI do Azure como qualquer implantação automática, com apenas algumas diferenças. Depois que uma implantação em camadas é criada, a CLI do Azure funciona para implantações em camadas da mesma forma que funciona para qualquer implantação. Para criar uma implantação em camadas, adicione o sinalizador --layered ao comando create.

A segunda diferença está na construção do manifesto de implantação. Enquanto a implantação automática padrão deve conter os módulos de tempo de execução do sistema, além de quaisquer módulos de usuário, as implantações em camadas podem conter apenas módulos de usuário. As implantações em camadas também precisam de uma implantação automática padrão em um dispositivo para fornecer os componentes necessários de cada dispositivo IoT Edge, como os módulos de tempo de execução do sistema.

Aqui está um manifesto de implantação em camadas básico com um módulo como exemplo:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Esse manifesto de implantação em camadas tem um formato ligeiramente diferente de um manifesto de implantação padrão. As propriedades desejadas dos módulos de tempo de execução são recolhidas e usam notação de ponto. Essa formatação é necessária para que o portal do Azure reconheça uma implantação em camadas. Por exemplo:

• properties.desired.modules.<module_name>
• properties.desired.routes.<route_name>

O exemplo anterior mostrou a configuração properties.desired de implantação em camadas para um módulo. Se essa implantação em camadas visasse um dispositivo em que o mesmo módulo já estivesse aplicado, ele substituiria quaisquer propriedades desejadas existentes. Para atualizar as propriedades desejadas em vez de substituí-las, você pode definir uma nova subseção. Por exemplo:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

O mesmo pode também ser expresso com:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Nota

Atualmente, todas as implantações em camadas devem incluir um edgeAgent objeto para serem consideradas válidas. Mesmo que uma implantação em camadas atualize apenas as propriedades do módulo, inclua um objeto vazio. Por exemplo: "$edgeAgent":{}. Uma implantação em camadas com um objeto vazio edgeAgent será mostrada como direcionada no módulo gêmeo edgeAgent , não aplicada.

Em resumo, para criar uma implantação em camadas:

• Adicione o sinalizador --layered ao comando create da CLI do Azure.
• Não inclua módulos do sistema.
• Use a notação de ponto completo em $edgeAgent e $edgeHub.

Para obter mais informações sobre como configurar gêmeos de módulo em implantações em camadas, consulte Implantação em camadas.

Identificar dispositivos usando tags

Antes de criar uma implantação, você precisa ser capaz de especificar quais dispositivos deseja afetar. O Azure IoT Edge identifica dispositivos usando marcas no gêmeo de dispositivo.

Cada dispositivo pode ter várias tags que você define de qualquer maneira que faça sentido para sua solução. Por exemplo, se gerir um campus de edifícios inteligentes, pode adicionar as seguintes etiquetas a um dispositivo:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Para obter mais informações sobre gêmeos de dispositivo e tags, consulte Compreender e usar gêmeos de dispositivo no Hub IoT.

Criar uma implantação

Você implanta módulos em seus dispositivos de destino criando uma implantação que consiste no manifesto de implantação e em outros parâmetros.

Use o comando az iot edge deployment create para criar uma implantação:

az iot edge deployment create --deployment-id [deployment id] --hub-name [hub name] --content [file path] --labels "[labels]" --target-condition "[target query]" --priority [int]

Use o mesmo comando com o --layered sinalizador para criar uma implantação em camadas.

O comando create para implantação usa os seguintes parâmetros:

• --em camadas. Um sinalizador opcional para identificar a implantação como uma implantação em camadas.
• --deployment-id. O nome da implantação que será criada no hub IoT. Dê à sua implantação um nome exclusivo com até 128 letras minúsculas. Evite espaços e os seguintes caracteres inválidos: & ^ [ ] { } \ | " < > /. Este parâmetro é obrigatório.
• --conteúdo. Caminho do arquivo para o manifesto de implantação JSON. Este parâmetro é obrigatório.
• --nome do hub. Nome do hub IoT no qual a implantação será criada. O hub deve estar na assinatura atual. Altere sua assinatura atual usando o az account set -s [subscription name] comando.
• --rótulos. Pares nome/valor que descrevem e ajudam você a acompanhar suas implantações. Os rótulos usam formatação JSON para os nomes e valores. Por exemplo: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --condição-alvo. A condição que determina quais dispositivos serão direcionados com essa implantação. A condição é baseada em tags de gêmeos de dispositivo ou propriedades relatadas de gêmeos de dispositivo e deve corresponder ao formato de expressão. Por exemplo: tags.environment='test' and properties.reported.devicemodel='4000x'. Se a condição de destino não for especificada, a implantação não será aplicada a nenhum dispositivo.
• --prioridade. Um número inteiro positivo. Se duas ou mais implantações forem direcionadas ao mesmo dispositivo, a implantação com o maior valor numérico de prioridade será aplicada.
• --métricas. Métricas que consultam as edgeHub propriedades relatadas para acompanhar o status de uma implantação. As métricas usam a entrada JSON ou um caminho de arquivo. Por exemplo: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Para monitorar uma implantação usando a CLI do Azure, consulte Monitorar implantações do IoT Edge.

Nota

Quando uma nova implantação do IoT Edge é criada, às vezes pode levar até 5 minutos para que o Hub IoT processe a nova configuração e propague as novas propriedades desejadas para os dispositivos de destino.

Modificar uma implantação

Quando você modifica uma implantação, as alterações são replicadas imediatamente para todos os dispositivos de destino.

Se você atualizar a condição de destino, as seguintes atualizações ocorrerão:

• Se um dispositivo não atender à condição de destino antiga, mas atender à nova condição de destino, e essa implantação for a prioridade mais alta para esse dispositivo, essa implantação será aplicada ao dispositivo.
• Se um dispositivo que atualmente executa essa implantação não atender mais à condição de destino, ele desinstalará essa implantação e assumirá a implantação de prioridade mais alta.
• Se um dispositivo atualmente executando essa implantação não atender mais à condição de destino e não atender à condição de destino de nenhuma outra implantação, nenhuma alteração ocorrerá no dispositivo. O dispositivo continua executando seus módulos atuais em seu estado atual, mas não é mais gerenciado como parte dessa implantação. Depois que o dispositivo atende à condição de destino de qualquer outra implantação, ele desinstala essa implantação e assume a nova.

Não é possível atualizar o conteúdo de uma implantação, que inclui os módulos e rotas definidos no manifesto de implantação. Se você quiser atualizar o conteúdo de uma implantação, crie uma nova implantação direcionada aos mesmos dispositivos com uma prioridade mais alta. Você pode modificar determinadas propriedades de um módulo existente, incluindo a condição de destino, rótulos, métricas e prioridade.

Use o comando az iot edge deployment update para atualizar uma implantação:

az iot edge deployment update --deployment-id [deployment id] --hub-name [hub name] --set [property1.property2='value']

O comando deployment update usa os seguintes parâmetros:

• --deployment-id. O nome da implantação que existe no hub IoT.
• --nome do hub. O nome do hub IoT no qual a implantação existe. O hub deve estar na assinatura atual. Mude para a subscrição pretendida utilizando o comando az account set -s [subscription name].
• --conjunto. Atualize uma propriedade na implantação. Você pode atualizar as seguintes propriedades:
  • targetCondition (por exemplo, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --adicionar. Adicione uma nova propriedade à implantação, incluindo condições de destino ou rótulos.
• --remover. Remova uma propriedade existente, incluindo condições ou rótulos de destino.

Excluir uma implantação

Quando você exclui uma implantação, todos os dispositivos assumem sua implantação de prioridade mais alta. Se seus dispositivos não atenderem à condição de destino de qualquer outra implantação, os módulos não serão removidos quando a implantação for excluída.

Use o comando az iot edge deployment delete para excluir uma implantação:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

O deployment delete comando usa os seguintes parâmetros:

• --deployment-id. O nome da implantação que existe no hub IoT.
• --nome do hub. O nome do hub IoT no qual a implantação existe. O hub deve estar na assinatura atual. Mude para a subscrição pretendida utilizando o comando az account set -s [subscription name].

Próximos passos

Saiba mais sobre como implantar módulos em dispositivos IoT Edge.