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

Aplica-se a: IoT Edge 1.5

Use a CLI do Azure para criar uma implantação automática do Azure IoT Edge e gerenciar implantações para vários dispositivos de uma só vez. 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 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 IoT. Em seguida, você implanta módulos em um conjunto de dispositivos IoT Edge e monitora o progresso usando comandos da CLI.

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. Use az --version para verificar. 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. 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á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
        }
      }
    }
  }
}

Implantação em camadas

As implantações em camadas são um tipo de implantação automática que você pode empilhar 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.

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

A segunda diferença está em como você constrói o manifesto de implantação. As implantações automáticas padrão devem incluir os módulos de tempo de execução do sistema e quaisquer módulos de usuário. As implantações em camadas podem incluir 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
        }
      }
    }
  }
}

O exemplo anterior mostra a 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á esteja 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
}

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

Implante módulos em 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 o sinalizador --layered 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 é obrigatório.
• --content: Caminho do ficheiro para o manifesto de implantação JSON. Este parâmetro é obrigatório.
• --hub-name: Nome do hub IoT onde a implantação é criada. O hub deve estar na assinatura atual. Altere sua assinatura atual executando az account set -s <subscription-name>.
• --labels: pares nome/valor que descrevem e ajudam a monitorizar 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 visados 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 você não especificar a condição de destino, a implantação não será aplicada a nenhum dispositivo.
• --prioridade: Inteiro positivo. Se duas ou mais implantações tiverem como destino o mesmo dispositivo, a implantação com a prioridade mais alta será aplicada.
• --metrics: métricas que consultam as edgeHub propriedades relatadas para acompanhar o status de uma implantação. As métricas usam 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.

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, ocorrerão as seguintes alterações:

• 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 atualmente executando essa implantação não atender mais à condição de destino, ele desinstalará essa implantação e assumirá a próxima 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 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 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, 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 no hub IoT.
• --hub-name: o nome do hub IoT onde a implantação existe. O hub deve estar na assinatura atual. Para mudar para outra subscrição, execute az account set -s <subscription-name>.
• --set: altere 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-alvo ou rótulos.
• --remove: Remova uma propriedade existente, incluindo condições ou rótulos de destino.

Excluir uma implantação

Quando você exclui uma implantação, os dispositivos usam sua 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 eliminar 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.