Saiba como implantar módulos e estabelecer rotas no IoT Edge

Aplica-se a: IoT Edge 1.5

Cada dispositivo IoT Edge executa pelo menos dois módulos: $edgeAgent e $edgeHub, que fazem parte do runtime IoT Edge. Um dispositivo IoT Edge pode executar vários módulos para processos diferentes. Use um manifesto de implantação para informar ao dispositivo quais módulos instalar e como configurá-los para trabalhar em conjunto.

O manifesto de implantação é um documento JSON que descreve:

• O IoT Edge agent módulo gêmeo, que inclui três componentes:
  • A imagem de contêiner para cada módulo executado no dispositivo.
  • As credenciais para usar repositórios de contêiner privados que contêm imagens de módulo.
  • Instruções sobre como cada módulo é criado e gerenciado.
• O IoT Edge hub módulo gêmeo, que inclui como as mensagens fluem entre módulos e IoT Hub.
• As propriedades desejadas de qualquer módulo gêmeo extra (opcional).

Todos os dispositivos IoT Edge precisam de um manifesto de implantação. Um runtime de IoT Edge recém-instalado mostra um código de erro até que você configure um manifesto válido.

Nos tutoriais do Azure IoT Edge, você cria um manifesto de implantação usando um assistente no portal Azure IoT Edge. Você também pode aplicar um manifesto de implantação programaticamente usando REST ou o SDK do Serviço de IoT Hub. Para obter mais informações, consulte Compreenda as implantações do IoT Edge.

Criar um manifesto de implantação

Um manifesto de implantação é uma lista de módulos gêmeos definidos com suas propriedades desejadas. Ele informa a um IoT Edge dispositivo ou grupo de dispositivos quais módulos instalar e como configurá-los. Manifestos de implantação incluem as propriedades desejadas para cada módulo gêmeo. Dispositivos IoT Edge relatam as propriedades reportadas para cada módulo.

Cada manifesto de implantação requer dois módulos: $edgeAgent e $edgeHub. Esses módulos fazem parte do runtime IoT Edge que gerencia o dispositivo IoT Edge e os módulos em execução nele. Para obter mais informações sobre esses módulos, consulte Compreender o IoT Edge runtime e sua arquitetura.

Você pode adicionar até 50 módulos adicionais para serem executados em um dispositivo IoT Edge, além dos dois módulos de runtime.

Um manifesto de implantação que tem apenas o runtime de IoT Edge ($edgeAgent e $edgeHub) é válido.

Os manifestos de implantação usam este formato:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configurar módulos

Defina como o IoT Edge runtime instala os módulos em sua implantação. O agente IoT Edge é o componente de runtime que gerencia a instalação, atualizações e relatórios de status de um dispositivo IoT Edge. Portanto, o $edgeAgent módulo gêmeo tem as informações de configuração e gerenciamento para todos os módulos. Essas informações incluem os parâmetros de configuração do próprio agente IoT Edge.

As $edgeAgent propriedades usam este formato:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

O esquema do agente IoT Edge versão 1.1 foi lançado com IoT Edge versão 1.0.10 e permite definir a ordem de inicialização do módulo. Use o esquema versão 1.1 para qualquer implantação IoT Edge executando a versão 1.0.10 ou posterior.

Configuração e gerenciamento do módulo

Defina quais módulos são executados em um dispositivo IoT Edge e como configurá-los e gerenciá-los na lista de propriedades desejadas do agente IoT Edge.

Para obter uma lista completa das propriedades desejadas que você pode ou deve incluir, consulte Properties do agente IoT Edge e IoT Edge hub.

Por exemplo:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Cada módulo tem uma propriedade de configurações com a imagem do módulo, um endereço para a imagem de contêiner em um registro de contêiner e qualquer createOptions para configurar a imagem na inicialização. Para obter mais informações, consulte Como configurar as opções de criação de contêineres para módulos IoT Edge.

O módulo edgeHub e os módulos personalizados também têm três propriedades que informam ao agente IoT Edge como gerenciá-los:

• Status: se o módulo é executado ou interrompido quando implantado pela primeira vez. Obrigatória.

• RestartPolicy: quando e se o agente IoT Edge reiniciar o módulo se ele parar. Se o módulo for interrompido sem erros, ele não será reiniciado automaticamente. Para obter mais informações, consulte Documentos do Docker – Iniciar contêineres automaticamente. Obrigatória.

• StartupOrder: introduzido no IoT Edge versão 1.0.10. A ordem que o agente IoT Edge usa para iniciar os módulos na primeira implantação. A ordem usa inteiros, em que um módulo com um valor de inicialização de 0 começa primeiro e, em seguida, números mais altos seguem. O módulo $edgeAgent não tem um valor de inicialização porque ele sempre começa primeiro. Opcional.

  O agente de IoT Edge inicia os módulos na ordem do valor de inicialização, mas não aguarda que cada módulo seja concluído antes de iniciar o próximo.

  A ordem de inicialização ajuda se alguns módulos dependem de outros. Por exemplo, talvez você queira que o módulo edgeHub seja iniciado primeiro para que ele esteja pronto para rotear mensagens quando os outros módulos forem iniciados. Ou talvez você queira iniciar um módulo de armazenamento antes de iniciar módulos que enviam dados para ele. Mas sempre projete seus módulos para lidar com falhas de outros módulos. Os contêineres podem parar e reiniciar a qualquer momento e em qualquer número de vezes.

  Observação

  Alterar as propriedades de um módulo reinicia esse módulo. Por exemplo, uma reinicialização ocorrerá se você alterar as propriedades para:

  • imagem do módulo
  • Opções de criação de docker
  • variáveis de ambiente
  • política de reinicialização
  • política de pull de imagem
  • versão
  • ordem de inicialização

  Se você não alterar nenhuma propriedade do módulo, uma reinicialização do módulo não será disparada.

Declarar rotas

IoT Edge hub gerencia a comunicação entre módulos, IoT Hub e dispositivos downstream. O módulo gêmeo $edgeHub tem uma propriedade desejada chamada routes que define como as mensagens se movem dentro de uma implantação. Você pode configurar várias rotas na mesma implantação.

Declare rotas nas propriedades desejadas do $edgeHub usando esta sintaxe:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

IoT Edge esquema de hub versão 1 lançado com IoT Edge versão 1.0.10 e permite definir a priorização da rota e o tempo de vida útil. Use o esquema versão 1.1 para qualquer implantação IoT Edge executando a versão 1.0.10 ou posterior.

Cada rota precisa de uma origem para mensagens de entrada e um coletor para mensagens de saída. A condição é opcional e permite filtrar mensagens.

Atribua prioridade às rotas para processar mensagens importantes primeiro. Esse recurso ajuda quando a conexão upstream é fraca ou limitada e você precisa priorizar dados críticos em relação às mensagens de telemetria padrão.

Origem

A origem especifica de onde as mensagens são provenientes. IoT Edge pode rotear mensagens de módulos ou dispositivos downstream.

Usando os SDKs do IoT, os módulos podem definir filas de saída específicas para suas mensagens usando a ModuleClient classe. As filas de saída não são necessárias, mas ajudam a gerenciar várias rotas. Os dispositivos downstream usam a classe DeviceClient nos SDKs de IoT para enviar mensagens para dispositivos de gateway IoT Edge, assim como enviam mensagens para o IoT Hub. Para obter mais informações, consulte Compreenda e utilize os SDKs do Azure IoT Hub.

A propriedade de origem pode usar qualquer um desses valores:

Condição

A condição é opcional em uma declaração de rota. Para passar todas as mensagens da origem para o coletor, omita a cláusula WHERE . Ou use a linguagem de consulta IoT Hub para filtrar mensagens ou tipos de mensagem que atendam à condição. IoT Edge rotas não dão suporte à filtragem de mensagens baseadas em tags ou propriedades de gêmeos digitais.

As mensagens que se movem entre módulos em IoT Edge usam o mesmo formato que as mensagens entre seus dispositivos e Azure IoT Hub. Todas as mensagens usam o formato JSON e têm systemProperties, appProperties e parâmetros de corpo .

Crie consultas em torno de qualquer um dos três parâmetros usando essa sintaxe:

• Propriedades do sistema: $<propertyName> ou {$<propertyName>}
• Propriedades do aplicativo: <propertyName>
• Propriedades do corpo: $body.<propertyName>

Para obter exemplos de como criar consultas para propriedades de mensagem, consulte expressões de consulta de rotas de mensagens de dispositivo para nuvem.

Por exemplo, talvez você queira filtrar mensagens que chegam a um dispositivo de gateway de um dispositivo downstream. As mensagens enviadas dos módulos incluem uma propriedade do sistema chamada connectionModuleId. Para rotear mensagens de dispositivos downstream diretamente para o IoT Hub e excluir mensagens de módulo, use esta rota:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Coletor

O coletor define para onde enviar mensagens. Somente módulos e IoT Hub podem receber mensagens. Você não pode rotear mensagens para outros dispositivos. A propriedade do coletor não dá suporte a curingas.

A propriedade do coletor pode usar qualquer um desses valores:

IoT Edge fornece garantias pelo menos uma vez. IoT Edge hub armazena mensagens localmente se uma rota não puder entregar a mensagem ao destino. Por exemplo, se IoT Edge hub não puder se conectar ao IoT Hub ou o módulo de destino não estiver conectado.

IoT Edge hub armazena mensagens até o tempo definido na propriedade storeAndForwardConfiguration.timeToLiveSecs das propriedades desejadas do IoT Edge hub.

Prioridade e tempo de vida útil

Declare rotas como uma cadeia de caracteres que define a rota ou como um objeto com uma cadeia de caracteres de rota, um inteiro de prioridade e um inteiro de vida útil.

Opção 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Opção 2 (introduzida na versão 1.0.10 do IoT Edge com o esquema do hub do IoT Edge na versão 1.1)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Os valores de prioridade variam de 0 a 9, em que 0 é a prioridade mais alta. O sistema enfileira mensagens pelos seus pontos de extremidade. O sistema processa todas as mensagens de prioridade 0 para um ponto de extremidade específico antes de processar qualquer mensagem de prioridade 1 para o mesmo ponto de extremidade. Se várias rotas para o mesmo ponto de extremidade tiverem a mesma prioridade, o sistema processará as mensagens na ordem em que chegam. Se você não definir uma prioridade, a rota usará a prioridade mais baixa.

A propriedade timeToLiveSecs usa o valor de storeAndForwardConfiguration do hub IoT Edge, a menos que você o defina diretamente. O valor pode ser qualquer número inteiro positivo.

Para obter detalhes sobre como as filas de prioridade são gerenciadas, consulte Route priority and time-to-live.

Definir ou atualizar as propriedades desejadas

O manifesto de implantação define as propriedades desejadas para cada módulo implantado no dispositivo IoT Edge. Quando as propriedades no manifesto de implantação substituem qualquer propriedade desejada atualmente no gêmeo do módulo.

Se você não definir as propriedades desejadas de um módulo gêmeo no manifesto de implantação, IoT Hub não alterará o módulo gêmeo. Em vez disso, defina as propriedades desejadas programaticamente.

Os mesmos mecanismos que permitem alterar dispositivos gêmeos também permitem que você altere os módulos gêmeos. Para obter mais informações, consulte o guia do desenvolvedor do módulo gêmeo.

Exemplo de manifesto de implantação

O exemplo a seguir mostra a aparência de um documento de manifesto de implantação válido.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Próximas etapas

• Para obter uma lista completa das propriedades que você pode ou deve incluir em $edgeAgent e $edgeHub, consulte Properties do agente IoT Edge e do hub IoT Edge.
• Agora que você sabe como IoT Edge módulos funcionam, aprende sobre os requisitos e as ferramentas para desenvolver módulos IoT Edge.