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

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Crie uma implantação automática do Azure IoT Edge usando CLI do Azure para gerenciar de uma só vez implantações contínuas de diversos dispositivos. As implantações automáticas para IoT Edge fazem parte do recurso degerenciamento de dispositivo do Hub IoT do Azure. Implantações são processos dinâmicos que 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ê aprende a implantar módulos em um conjunto de dispositivos do IoT Edge e a monitorar o progresso usando os comandos da CLI disponíveis.

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 validar. 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 módulos gêmeos. 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. Use o caminho do arquivo na próxima seção quando executar o comando para aplicar a configuração ao dispositivo.

A seguir, é apresentado um manifesto básico de implantação com um módulo como um 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. A versão 1.1 do esquema foi lançada com a versão 1.0.10 do IoT Edge. Ela habilita recursos como a ordem de inicialização de módulo e a priorização de rota.

Implantação em camadas

Implantações em camadas são um tipo de implantação automática que pode ser empilhada uma sobre a outra. 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.

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 ela da mesma forma que para qualquer outra implantação. Para criar uma implantação em camadas, adicione o sinalizador --layered ao comando create.

A segunda diferença corresponde à criação do manifesto de implantação. Enquanto a implantação automática padrão precisa conter os módulos de runtime do sistema e quaisquer módulos de usuário, as implantações em camadas podem conter somente os módulos do 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.

Este é 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 contém uma configuração properties.desired de implantação em camadas para um módulo. Se essa implantação em camadas tiver como destino um dispositivo em que o mesmo módulo já foi aplicado, ela substituirá 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
  }
}

O mesmo também pode ser expresso com:

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

Observação

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

Resumindo, 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 conseguir 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ê gerencia um campus de edifícios inteligentes, poderá adicionar as seguintes marcações 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

Você implanta módulos nos dispositivos de destino criando uma implantação que consiste no manifesto de implantação, bem como 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 sinalizador --layered para criar uma implantação em camadas.

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

• --layered. 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ê um nome exclusivo à implantação com até 128 letras minúsculas. Evite usar espaços e os seguintes caracteres inválidos: & ^ [ ] { } \ | " < > /. Este parâmetro é necessário.
• --content. Caminho de arquivo para o JSON do manifesto de implantação. Este parâmetro é necessário.
• --hub-name. Nome do Hub IoT no qual a implantação será criada. O hub deve estar na assinatura atual. Altere a assinatura atual usando o comando az account set -s [subscription name].
• --labels. Pares de nome/valor que descrevem e ajudam você a acompanhar suas implantações. Os rótulos usam a formatação JSON para os nomes e valores. Por exemplo: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --target-condition. A condição que determina quais dispositivos serão direcionados com essa implantaçã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 a condição de destino não for especificada, a implantação não será aplicada a nenhum dispositivo.
• --priority. Um número inteiro positivo. Se duas ou mais implantações forem direcionadas no mesmo dispositivo, será aplicada a implantação com o valor numérico mais alto para prioridade.
• --metrics. Métricas que consultam as propriedades relatadas pelo edgeHub 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, veja Monitorar implantações do IoT Edge.

Observação

Quando uma nova implantação do IoT Edge é criada, às vezes pode levar até 5 minutos para o Hub IoT processar a nova configuração e propagar 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 direcionados.

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

• Uma implantação é aplicada ao dispositivo quando ela é a prioridade mais alta para ele e ele atende à nova condição de destino, apesar de não atender à antiga.
• Se um dispositivo que está executando esta implantação não atende mais à condição de destino, ele desinstala esta implantação e assume a próxima de maior prioridade.
• Caso um dispositivo que executa essa implantação no momento não atenda mais à condição de destino e não atenda à condição de destino de todas as outras implantações, nenhuma alteração ocorrerá no dispositivo. O dispositivo continua executando os módulos atuais neste estado, mas não é mais gerenciado como parte da implantação. Depois de atender à condição de destino de qualquer outra implantação, o dispositivo desinstalará essa implantação e usará 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 que vise os mesmos dispositivos com uma 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 deployment update 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].
• --set. Atualize uma propriedade na implantação. Atualize as seguintes propriedades:
  • targetCondition (por exemplo, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Adicione uma nova propriedade à implantação, incluindo rótulos ou condições de destino.
• --remove. Remova uma propriedade existente, incluindo rótulos ou condições de destino.

Excluir uma implantação

Ao excluir uma implantação, todos os dispositivos usam a próxima implantação com a prioridade mais alta. Se os dispositivos não atenderem à condição de destino de alguma 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 comando deployment delete 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.