IoT Edge에서 모듈을 배포하고 경로를 설정하는 방법 알아보기

2025-05-20

적용 대상: IoT Edge 1.5

중요합니다

IoT Edge 1.5 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일부터 수명이 종료됩니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.

각 IoT Edge 디바이스는 적어도 $edgeAgent 및 $edgeHub라는 두 개의 모듈을 실행합니다. 두 모듈은 IoT Edge 런타임의 일부입니다. IoT Edge 디바이스는 여러 프로세스에 대해 여러 모듈을 실행할 수 있습니다. 배포 매니페스트를 사용하여 설치할 모듈과 함께 작동하도록 설정하는 방법을 디바이스에 알릴 수 있습니다.

배포 매니페스트는 다음 항목을 설명하는 JSON 문서입니다.

다음 세 가지 구성 요소를 포함하는 IoT Edge 에이전트 모듈 쌍
- 디바이스에서 실행되는 각 모듈의 컨테이너 이미지
- 모듈 이미지가 있는 프라이빗 컨테이너 레지스트리를 사용하는 자격 증명
- 각 모듈을 만들고 관리하는 방법에 대한 지침
모듈과 IoT Hub 간에 메시지가 흐르는 방식을 포함하는 IoT Edge 허브 모듈 쌍
원하는 속성의 추가 모듈 트윈(선택 사항)

모든 IoT Edge 디바이스에는 배포 매니페스트가 필요합니다. 새로 설치된 IoT Edge 런타임은 유효한 매니페스트로 설정될 때까지 오류 코드를 표시합니다.

Azure IoT Edge 자습서에서는 Azure IoT Edge 포털에서 마법사를 사용하여 배포 매니페스트를 빌드합니다. REST 또는 IoT Hub 서비스 SDK를 사용하여 프로그래밍 방식으로 배포 매니페스트를 적용할 수도 있습니다. 자세한 내용은 IoT Edge 배포 이해를 참조하세요.

배포 매니페스트 만들기

배포 매니페스트는 원하는 속성을 사용하여 설정된 모듈 쌍의 목록입니다. 설치할 모듈 및 설정하는 방법을 IoT Edge 디바이스 또는 디바이스 그룹에 알려줍니다. 배포 매니페스트에는 각 모듈 쌍의 ‘원하는 속성’이 포함되어 있습니다. IoT Edge 디바이스는 각 모듈에 대해 보고된 속성을 보고합니다.

모든 배포 매니페스트에는 두 개의 모듈 $edgeAgent과 $edgeHub가 필요합니다. 두 모듈은 IoT Edge 디바이스와 이 디바이스에서 실행되는 모듈을 관리하는 IoT Edge 런타임의 일부입니다. 이러한 모듈에 대한 자세한 내용은 IoT Edge 런타임 및 해당 아키텍처 이해를 참조하세요.

두 개의 런타임 모듈 외에도 IoT Edge 디바이스에서 실행할 모듈을 최대 50개까지 추가할 수 있습니다.

IoT Edge 런타임($edgeAgent 및 $edgeHub)만 있는 배포 매니페스트는 유효합니다.

배포 매니페스트는 다음 구조를 사용합니다.

{
  "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
      }
    }
  }
}

모듈 구성

IoT Edge 런타임에서 사용자 배포에 모듈을 설치하는 방법을 정의합니다. IoT Edge 에이전트는 IoT Edge 디바이스에 대한 설치, 업데이트 및 상태 보고를 관리하는 런타임 구성 요소입니다. 따라서 $edgeAgent 모듈 쌍에는 모든 모듈에 대한 구성 및 관리 정보가 있습니다. 이 정보에는 IoT Edge 에이전트 자체에 대한 구성 매개 변수가 포함됩니다.

$edgeAgent 속성은 다음과 같은 구조를 따릅니다.

{
  "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": { ... }
  }
}

IoT Edge 에이전트 스키마 버전 1.1은 IoT Edge 버전 1.0.10과 함께 릴리스되었으며 모듈 시작 순서를 설정할 수 있습니다. 버전 1.0.10 이상을 실행하는 모든 IoT Edge 배포에 스키마 버전 1.1을 사용합니다.

모듈 구성 및 관리

IoT Edge 에이전트 원하는 속성 목록은 IoT Edge 디바이스에서 실행되는 모듈과 모듈을 설정하고 관리하는 방법을 정의하는 위치입니다.

포함될 수 있거나 포함되어야 하는 원하는 속성의 전체 목록은 IoT Edge 에이전트 및 IoT Edge 허브의 속성을 참조하세요.

예시:

{
  "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": { ... }
  }
}

모든 모듈에는 모듈 이미지가 있는 설정 속성, 컨테이너 레지스트리의 컨테이너 이미지에 대한 주소 및 시작할 때 이미지를 설정하는 모든 createOptions가 있습니다. 자세한 내용은 IoT Edge 모듈에 대한 컨테이너 만들기 옵션 구성 방법을 참조하세요.

EdgeHub 모듈 및 사용자 지정 모듈에는 IoT Edge 에이전트에 관리 방법을 알려주는 세 가지 속성도 있습니다.

상태: 모듈이 처음 배포될 때 실행 또는 중지되는지 여부입니다. 필수입니다.
RestartPolicy: IoT Edge 에이전트가 모듈이 중지되면 모듈을 다시 시작하는 시기와 경우 모듈이 오류 없이 중지되면 자동으로 시작되지 않습니다. 자세한 내용은 Docker Docs - 컨테이너 자동 시작을 참조하세요. 필수입니다.
StartupOrder: IoT Edge 버전 1.0.10에 도입되었습니다. IoT Edge 에이전트가 처음 배포될 때 모듈을 시작하는 데 사용하는 순서입니다. 순서는 정수를 사용합니다. 여기서 시작 값이 0인 모듈이 먼저 시작되고 더 높은 숫자가 뒤따릅니다. edgeAgent 모듈은 항상 먼저 시작되기 때문에 시작 값이 없습니다. 선택 사항.

IoT Edge 에이전트는 시작 값 순서대로 모듈을 시작하지만 다음 모듈을 시작하기 전에 각 모듈이 시작될 때까지 기다리지 않습니다.

시작 순서는 일부 모듈이 다른 모듈에 의존하는 경우에 도움이 됩니다. 예를 들어 edgeHub 모듈을 먼저 시작하여 다른 모듈이 시작될 때 메시지를 라우팅할 준비가 되도록 할 수 있습니다. 또는 데이터를 전송하는 모듈을 시작하기 전에 스토리지 모듈을 시작할 수 있습니다. 그러나 항상 다른 모듈의 오류를 처리하도록 모듈을 디자인합니다. 컨테이너는 언제든지, 그리고 횟수에 따라 중지 및 다시 시작할 수 있습니다.
참고 항목

모듈의 속성을 변경하면 해당 모듈이 다시 시작됩니다. 예를 들어 다음의 속성을 변경하면 다시 시작이 발생합니다.
- 모듈 이미지
- Docker 만들기 옵션
- 환경 변수
- 다시 시작 정책
- 이미지 끌어오기 정책
- 버전
- 시작 순서
모듈 속성이 변경되지 않으면 모듈 다시 시작이 트리거되지 않습니다.

경로 선언

IoT Edge 허브는 모듈, IoT Hub 및 다운스트림 디바이스 간의 통신을 관리합니다. $edgeHub 모듈 쌍에는 배포 내에서 메시지가 이동하는 방법을 정의하는 경로 라는 desired 속성이 있습니다. 동일한 배포에서 여러 경로를 설정할 수 있습니다.

다음 구문을 사용하여 $edgeHub desired 속성에서 경로를 선언합니다.

{
  "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 버전 1.0.10으로 릴리스된 IoT Edge 허브 스키마 버전 1을 사용하여 경로 우선 순위 지정 및 TTL(Time to Live)을 설정할 수 있습니다. 버전 1.0.10 이상을 실행하는 모든 IoT Edge 배포에 스키마 버전 1.1을 사용합니다.

각 경로에는 들어오는 메시지의 원본 과 나가는 메시지의 싱크 가 필요합니다. 조건은 선택 사항이며 메시지를 필터링할 수 있습니다.

먼저 중요한 메시지를 처리하는 경로에 우선 순위를 할당합니다. 이 기능은 업스트림 연결이 약하거나 제한되고 표준 원격 분석 메시지보다 중요한 데이터의 우선 순위를 지정해야 하는 경우에 도움이 됩니다.

원본

원본은 메시지가 발생한 위치를 지정합니다. IoT Edge는 모듈 또는 다운스트림 디바이스의 메시지를 라우팅할 수 있습니다.

모듈은 IoT SDK를 사용하여 ModuleClient 클래스를 사용하여 메시지에 대한 특정 출력 큐를 설정할 수 있습니다. 출력 큐는 필요하지 않지만 여러 경로를 관리하는 데 도움이 됩니다. 다운스트림 디바이스는 IoT SDK의 DeviceClient 클래스를 사용하여 IoT Hub에 메시지를 보내는 것처럼 IoT Edge 게이트웨이 디바이스에 메시지를 보냅니다. 자세한 내용은 Azure IoT Hub SDK 이해 및 사용을 참조하세요.

원본 속성은 다음 값 중에서 사용할 수 있습니다.

원본	설명
`/*`	모든 모듈 또는 다운스트림 디바이스의 모든 디바이스-클라우드 메시지 또는 트윈 변경 알림
`/twinChangeNotifications`	모든 모듈 또는 다운스트림 디바이스에서 발생하는 모든 트윈 변경(보고된 속성)
`/messages/*`	일부 출력을 통하거나 어떠한 출력도 없이 모듈 또는 다운스트림 디바이스에서 보낸 모든 디바이스-클라우드 메시지
`/messages/modules/*`	일부 출력을 통하거나 어떠한 출력도 없이 모듈에서 보낸 모든 디바이스-클라우드 메시지
`/messages/modules/<moduleId>/*`	일부 출력을 통하거나 어떠한 출력도 없이 특정 모듈에서 보낸 모든 디바이스-클라우드 메시지
`/messages/modules/<moduleId>/outputs/*`	일부 출력을 통해 특정 모듈에서 보낸 모든 디바이스-클라우드 메시지
`/messages/modules/<moduleId>/outputs/<output>`	특정 출력을 통해 특정 모듈에서 보낸 모든 디바이스-클라우드 메시지

조건

조건은 경로 선언의 선택 사항입니다. 원본에서 싱크로 모든 메시지를 전달하려면 WHERE 절을 그대로 둡니다. 또는 IoT Hub 쿼리 언어 를 사용하여 조건을 충족하는 메시지 또는 메시지 유형을 필터링합니다. IoT Edge 경로는 쌍 태그 또는 속성을 기반으로 하는 메시지 필터링을 지원하지 않습니다.

IoT Edge의 모듈 간에 이동하는 메시지는 디바이스와 Azure IoT Hub 간의 메시지와 동일한 형식을 사용합니다. 모든 메시지는 JSON 형식을 사용하며 systemProperties, appProperties 및 본문 매개 변수가 있습니다.

다음 구문을 사용하여 세 매개 변수를 중심으로 쿼리를 빌드합니다.

시스템 속성: $<propertyName> 또는 {$<propertyName>}
애플리케이션 속성: <propertyName>
본문 속성: $body.<propertyName>

메시지 속성에 대한 쿼리를 만드는 방법에 대한 예제는 디바이스-클라우드 메시지 경로 쿼리 식을 참조하세요.

예를 들어 다운스트림 디바이스에서 게이트웨이 디바이스에 도착하는 메시지를 필터링할 수 있습니다. 모듈에서 전송된 메시지에는 connectionModuleId라는 시스템 속성이 포함되어 있습니다. 다운스트림 디바이스에서 IoT Hub로 직접 메시지를 라우팅하고 모듈 메시지를 제외하려면 다음 경로를 사용합니다.

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

sink

싱크는 메시지가 전송되는 위치를 정의합니다. 모듈 및 IoT Hub만 메시지를 받을 수 있습니다. 메시지를 다른 디바이스로 라우팅할 수 없습니다. 싱크 속성은 와일드카드를 지원하지 않습니다.

싱크 속성은 다음 값 중에서 사용할 수 있습니다.

sink	설명
`$upstream`	메시지를 IoT Hub로 보냅니다.
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	특정 모듈의 특정 입력으로 메시지 보내기

IoT Edge는 한 번 이상의 보장을 제공합니다. 경로가 해당 싱크에 메시지를 전달할 수 없는 경우 IoT Edge 허브는 메시지를 로컬로 저장합니다. 예를 들어 IoT Edge 허브가 IoT Hub에 연결할 수 없거나 대상 모듈이 연결되지 않은 경우입니다.

IoT Edge 허브는 storeAndForwardConfiguration.timeToLiveSecs의 설정된 시간까지 메시지를 저장합니다.

우선 순위 및 TTL(Time to Live)

경로를 정의하는 문자열로 선언하거나 경로 문자열, 우선 순위 정수 및 TL(Time to Live) 정수가 있는 개체로 선언합니다.

옵션 1

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

옵션 2(IoT Edge 허브 스키마 버전 1.1을 사용하여 IoT Edge 버전 1.0.10에 도입됨)

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

우선 순위 값은 0에서 9까지이며 여기서 0은 가장 높은 우선 순위입니다. 메시지는 엔드포인트별로 큐에 대기됩니다. 특정 엔드포인트에 대한 모든 우선 순위 0 메시지는 동일한 엔드포인트에 대한 우선 순위 1 메시지 전에 처리됩니다. 동일한 엔드포인트에 대한 여러 경로의 우선 순위가 같으면 메시지가 도착하는 순서대로 처리됩니다. 우선 순위를 설정하지 않으면 경로에서 가장 낮은 우선 순위를 사용합니다.

timeToLiveSecs 속성은 직접 설정하지 않는 한 IoT Edge 허브의 storeAndForwardConfiguration에서 값을 사용합니다. 값은 임의의 양의 정수일 수 있습니다.

우선 순위 큐를 관리하는 방법에 대한 자세한 내용은 경로 우선 순위 및 TL(Time-to-Live)을 참조하세요.

원하는 속성 정의 또는 업데이트

배포 매니페스트는 IoT Edge 디바이스에 배포된 각 모듈에 대해 원하는 속성을 설정합니다. 배포 매니페스트의 원하는 속성은 현재 모듈 쌍에 있는 원하는 속성을 모두 덮어씁니다.

배포 매니페스트에서 모듈 트윈의 희망 속성을 설정하지 않으면 IoT Hub는 모듈 트윈을 변경하지 않습니다. 대신 원하는 속성을 프로그래밍 방식으로 설정합니다.

디바이스 쌍을 변경할 수 있는 동일한 메커니즘을 통해 모듈 쌍을 변경할 수도 있습니다. 자세한 내용은 모듈 쌍 개발자 가이드를 참조하세요.

배포 매니페스트 예제

다음 예제에서는 유효한 배포 매니페스트 문서가 어떤 모습일 수 있는지 보여줍니다.

{
  "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
        }
      }
    }
  }
}

다음 단계

$edgeAgent 및 $edgeHub 포함할 수 있거나 포함해야 하는 속성의 전체 목록은 IoT Edge 에이전트 및 IoT Edge 허브의 속성을 참조하세요.
이제 IoT Edge 모듈의 작동 방식을 확인했으므로 IoT Edge 모듈 개발을 위한 요구 사항 및 도구에 대해 알아봅니다.