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

Aplica-se a: IoT Edge 1.5

Importante

O IoT Edge 1.5 LTS é a versão com suporte. O IoT Edge 1.4 LTS atingirá o fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Use a CLI do Azure para criar uma implantação automática do Azure IoT Edge e gerenciar implantações para muitos dispositivos ao mesmo tempo. As implantações automáticas para IoT Edge fazem parte do recurso degerenciamento de dispositivo do Hub IoT do Azure. As implantações permitem implantar vários módulos em vários dispositivos, acompanhar 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 do IoT. Em seguida, você implanta módulos em um conjunto de dispositivos do IoT Edge e monitora o progresso usando comandos da CLI.

Pré-requisitos

• Um Hub IoT na 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 virtual do Linux ou Criar um dispositivo virtual do Windows.

• A CLI do Azure em seu ambiente. A versão da CLI do Azure deve ser 2.0.70 ou mais recente. Use az --version para verificar. Esta versão dá suporte aos comandos da extensão az e introduz a estrutura de comandos Knack.

• A extensão de IoT para a 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 do módulo. Para obter mais informações, confira Aprenda a 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 .txt. Você usará 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ásico 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
        }
      }
    }
  }
}

Observação

Este exemplo de manifesto de implantação usa a versão 1.1 do esquema para o hub e o agente IoT Edge. O esquema versão 1.1 é lançado junto com o IoT Edge versão 1.0.10. Ele permite que você use recursos como ordem de inicialização de módulo e priorização de rota.

Implantação em camadas

Implantações em camadas são um tipo de implantação automática que você pode empilhar entre si. Para obter mais informações sobre implantações em camadas, confira Noções básicas sobre implantações automáticas do IoT Edge para dispositivos únicos ou em escala.

Você pode criar e gerenciar implantações em camadas com a CLI do Azure como qualquer implantação automática, com apenas algumas diferenças. Depois de criar uma implantação em camadas, a CLI do Azure funciona para implantações em camadas da mesma forma que em qualquer implantação. Para criar uma implantação em camadas, adicione o sinalizador --layered ao comando create.

A segunda diferença é na forma como você constrói o manifesto de implantação. As implantações automáticas padrão devem incluir os módulos de runtime do sistema e todos os módulos de usuário. As implantações em camadas podem incluir apenas módulos de usuário. Essas implantações também precisam de uma implantação automática padrão em um dispositivo para fornecer os componentes necessários de cada dispositivo do IoT Edge, como os módulos de runtime do sistema.

Aqui está um manifesto básico de implantação em camadas 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
        }
      }
    }
  }
}

Observação

Esse manifesto de implantação em camadas tem um formato um pouco diferente de um manifesto de implantação padrão. As propriedades desejadas dos módulos de runtime são recolhidas e usam a 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 mostra a configuração properties.desired de implantação em camadas para um módulo. Se essa implantação em camadas for direcionada a um dispositivo em que o mesmo módulo já está aplicado, ela substituirá todas as propriedades desejadas existentes. Para atualizar as propriedades desejadas em vez de substituí-las, defina uma nova subseção. Por exemplo:

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

Você também pode expressar o mesmo com a seguinte sintaxe:

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

Observação

Atualmente, todas as implantações em camadas devem incluir um edgeAgent objeto para serem 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 edgeAgent vazio será mostrada como direcionada no módulo gêmeo edgeAgent, não como aplicada.

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 completa em $edgeAgent e em $edgeHub.

Para saber como configurar módulos gêmeos nas implantações em camadas, veja Implantação em camadas.

Identificar dispositivos usando marcações

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

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

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

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

Criar uma implantação

Implante módulos para dispositivos de destino criando uma implantação que tenha o manifesto de implantação e outros parâmetros.

Execute 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 <priority>

Adicione a --layered flag para criar uma implantação em camadas.

O az iot edge deployment create comando usa os seguintes parâmetros:

• --layered: sinalizador opcional que identifica a implantação como uma implantação em camadas.
• --deployment-id: nome da implantação criada no Hub IoT. Use um nome exclusivo com até 128 letras minúsculas. Evite espaços e estes caracteres inválidos: & ^ [ ] { } \ | " < > /. Este parâmetro é necessário.
• --content: caminho do arquivo para o JSON do manifesto de implantação. Este parâmetro é necessário.
• --hub-name: nome do hub IoT em que a implantação é criada. O hub deve estar na assinatura atual. Altere sua assinatura atual executando az account set -s <subscription-name>.
• --labels: pares de nome/valor que descrevem e ajudam você a acompanhar implantações. Os rótulos usam a formatação JSON para nomes e valores. Por exemplo: {"HostPlatform":"Linux", "Version":"3.0.1"}.
• --target-condition: Condição que determina quais dispositivos são alvo desta implementação. A condição se baseia nas marcas ou nas propriedades reportadas do dispositivo gêmeo e deve corresponder ao formato da expressão. Por exemplo: tags.environment='test' and properties.reported.devicemodel='4000x'. Se você não especificar a condição de destino, a implantação não será aplicada a nenhum dispositivo.
• --priority: inteiro positivo. Se duas ou mais implantações forem direcionadas ao mesmo dispositivo, a implantação com a prioridade mais alta se aplicará.
• --metrics: Métricas que consultam as edgeHub propriedades relatadas para acompanhar o status de uma implantação. As métricas usam uma 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 com a CLI do Azure, consulte Monitorar implantações do IoT Edge.

Observação

Quando você cria uma nova implantação do IoT Edge, pode levar até 5 minutos para que o Hub IoT processe a nova configuração e envie as novas propriedades desejadas para os dispositivos de destino.

Modificar uma implantação

Quando você altera 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 alteraçõ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 está executando essa implantação não atender mais à condição de destino, ele desinstala essa implantação e assume a próxima implantação de prioridade mais alta .
• Se um dispositivo que está executando essa implantação não atender mais à condição de destino e não atender à condição de destino de qualquer 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 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 as rotas definidos no manifesto de implantação. Para atualizar o conteúdo de uma implantação, crie uma nova implantação direcionada aos mesmos dispositivos com prioridade mais alta. Você pode modificar determinadas propriedades de um módulo existente, incluindo a condição de destino, os rótulos, as métricas e a 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 de atualização de implantação usa os seguintes parâmetros:

• --deployment-id: o nome da implantação no Hub IoT.
• --hub-name: o nome do hub IoT em que a implantação existe. O hub deve estar na assinatura atual. Para alternar para outra assinatura, execute az account set -s <subscription-name>.
• --set: alterar uma propriedade na implantação. Você pode alterar as seguintes propriedades:
  • targetCondition (por exemplo, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add: adicionar uma nova propriedade à implantação, incluindo condições ou rótulos de destino.
• --remove: remova uma propriedade existente, incluindo condições de destino ou rótulos.

Excluir uma implantação

Quando você exclui uma implantação, os dispositivos usam a próxima implantação de prioridade mais alta. Se os dispositivos não atenderem à condição de destino de outra implantação, os módulos não serão removidos quando você excluir a implantação.

Execute o comando az iot edge deployment delete para deletar 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.
• --hub-name. O nome do Hub IoT no qual a implantação se encontra. O hub deve estar na assinatura atual. Alterne para a assinatura desejada usando o comando az account set -s [subscription name].

Próximas etapas

Saiba como implantar módulos em dispositivos do IoT Edge.