Azure CLI를 사용하여 대규모로 IoT Edge 모듈 배포 및 모니터링

2025-05-20

적용 대상: IoT Edge 1.5

중요합니다

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

Azure CLI를 사용하여 Azure IoT Edge 자동 배포 를 만들고 여러 디바이스에 대한 배포를 한 번에 관리합니다. IoT Edge의 자동 배포는 Azure IoT Hub의 장치 관리 기능의 일부입니다. 배포를 통해 여러 디바이스에 여러 모듈을 배포하고, 모듈의 상태 및 상태를 추적하고, 필요할 때 변경할 수 있습니다.

이 문서에서는 Azure CLI 및 IoT 확장을 설정합니다. 그런 다음, IoT Edge 디바이스 집합에 모듈을 배포하고 CLI 명령을 사용하여 진행률을 모니터링합니다.

필수 조건

Azure 구독의 IoT Hub
하나 이상의 IoT Edge 디바이스.

IoT Edge 디바이스를 설정하지 않은 경우 Azure 가상 머신에서 만들 수 있습니다. 빠른 시작 문서(가상 Linux 디바이스 만들기 또는 가상 Windows 디바이스 만들기) 중 하나에 있는 단계를 따릅니다.
사용자 환경의 Azure CLI. Azure CLI 버전은 2.0.70 이상이어야 합니다. az --version을(를) 확인하는 데 사용합니다. 이 버전은 az extension 명령을 지원하며 Knack 명령 프레임워크를 도입했습니다.
Azure CLI용 IoT 확장.

배포 매니페스트 구성

배포 매니페스트는 배포할 모듈, 모듈 간에 데이터가 흐르는 방법 및 모듈 쌍의 원하는 속성을 설명하는 JSON 문서입니다. 자세한 내용은 IoT Edge에서 모듈 배포 및 경로를 설정하는 방법 알아보기을 참조하세요.

Azure CLI를 사용하여 모듈을 배포하려면 배포 매니페스트를 로컬에 .txt 파일로 저장합니다. 명령을 실행하여 디바이스에 구성을 적용할 때 다음 섹션의 파일 경로를 사용합니다.

다음은 하나의 모듈을 예로 들어 사용하는 기본 배포 매니페스트입니다.

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

참고 항목

이 샘플 배포 매니페스트는 IoT Edge 에이전트 및 허브용 스키마 버전 1.1을 사용합니다. 스키마 버전 1.1은 IoT Edge 버전 1.0.10과 함께 릴리스됩니다. 모듈 시작 순서 및 경로 우선 순위 지정과 같은 기능을 사용할 수 있습니다.

계층화된 배포

계층화된 배포는 서로 위에 쌓을 수 있는 자동 배포의 유형입니다. 계층화된 배포에 대한 자세한 내용은 단일 디바이스 또는 대규모 IoT Edge 자동 배포에 대한 이해를 참조하세요.

몇 가지 차이점만 있으면 자동 배포와 같은 Azure CLI를 사용하여 계층화된 배포를 만들고 관리할 수 있습니다. 계층화된 배포를 만든 후 Azure CLI는 모든 배포와 동일한 계층화된 배포에 대해 작동합니다. 계층화된 배포를 만들려면 create 명령에 --layered 플래그를 추가합니다.

두 번째 차이점은 배포 매니페스트를 생성하는 방법에 있습니다. 표준 자동 배포에는 시스템 런타임 모듈 및 모든 사용자 모듈이 포함되어야 합니다. 계층화된 배포에는 사용자 모듈만 포함될 수 있습니다. 계층화된 배포는 시스템 런타임 모듈과 같은 모든 IoT Edge 디바이스의 필수 구성 요소를 제공하기 위해 디바이스에 표준 자동 배포가 필요합니다.

다음은 하나의 모듈을 예로 들어 사용하는 기본 계층화된 배포 매니페스트입니다.

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

참고 항목

이 계층화된 배포 매니페스트의 형식은 표준 배포 매니페스트와 약간 다릅니다. 런타임 모듈의 desired 속성이 축소되고 점 표기법을 사용합니다. 이 서식은 Azure Portal에서 계층화된 배포를 인식하는 데 필요합니다. 예시:

properties.desired.modules.<module_name>
properties.desired.routes.<route_name>

이전 예제에서는 모듈에 대한 계층화된 배포 설정을 properties.desired 보여줍니다. 이 계층화된 배포가 동일한 모듈이 이미 적용된 디바이스를 대상으로 하는 경우 기존 원하는 속성을 덮어씁니다. 원하는 속성을 덮어쓰는 대신 업데이트하려면 새 하위 섹션을 정의합니다. 예시:

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

다음 구문을 사용하여 동일하게 표현할 수도 있습니다.

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

참고 항목

현재 모든 계층화된 배포에는 유효한 개체가 edgeAgent 포함되어야 합니다. 계층화된 배포가 모듈 속성만 업데이트하더라도 빈 개체를 포함합니다. 예: "$edgeAgent":{} 빈 edgeAgent 개체가 있는 계층화된 배포는 적용되지 않고 모듈 쌍에서 edgeAgent대상으로 표시됩니다.

계층화된 배포를 만들려면 다음을 수행합니다.

Azure CLI 만들기 명령에 --layered 플래그를 추가합니다.
시스템 모듈을 포함하지 마세요.
$edgeAgent 및 $edgeHub에서 전체 점 표기법을 사용합니다.

계층화된 배포에서 모듈 쌍을 구성하는 방법에 대한 자세한 내용은 계층화된 배포를 참조하세요.

태그를 사용하여 디바이스 식별

배포를 만들기 전에 영향을 줄 디바이스를 지정해야 합니다. Azure IoT Edge는 디바이스 쌍의 태그를 사용하여 디바이스를 식별합니다.

각 디바이스는 솔루션에 적합한 방식으로 정의하는 여러 개의 태그를 포함할 수 있습니다. 예를 들어 스마트 건물의 캠퍼스를 관리하는 경우 디바이스에 다음 태그를 추가할 수 있습니다.

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

디바이스 쌍 및 태그에 대한 자세한 내용은 IoT Hub의 디바이스 쌍 이해 및 사용을 참조하세요.

배포 만들기

배포 매니페스트 및 기타 매개 변수가 있는 배포를 만들어 대상 디바이스에 모듈을 배포합니다.

az iot edge deployment create 명령을 실행하여 배포를 만듭니다.

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

플래그를 --layered 추가하여 계층화된 배포를 만듭니다.

이 az iot edge deployment create 명령은 다음 매개 변수를 사용합니다.

--layered: 배포를 계층화된 배포로 식별하는 선택적 플래그입니다.
--deployment-id: IoT Hub에서 만든 배포의 이름입니다. 최대 128개 소문자로 고유한 이름을 사용합니다. 공백 및 잘못된 문자는 & ^ [ ] { } \ | " < > /사용하지 마세요. 이 매개 변수는 필수입니다.
--content: 배포 매니페스트 JSON에 대한 파일 경로입니다. 이 매개 변수는 필수입니다.
--hub-name: 배포가 만들어지는 IoT Hub의 이름입니다. 허브가 현재 구독에 있어야 합니다. 를 실행 az account set -s <subscription-name>하여 현재 구독을 변경합니다.
--labels: 배포를 설명하고 추적하는 데 도움이 되는 이름/값 쌍입니다. 레이블은 이름 및 값에 JSON 서식을 사용합니다. 예: {"HostPlatform":"Linux", "Version":"3.0.1"}
--target-condition: 이 배포를 대상으로 하는 디바이스를 결정하는 조건입니다. 조건은 디바이스 쌍 태그 또는 디바이스 쌍 reported 속성을 기반으로 하며, 표현 형식이 일치해야 합니다. 예: tags.environment='test' and properties.reported.devicemodel='4000x' 대상 조건을 지정하지 않으면 배포가 디바이스에 적용되지 않습니다.
--priority: 양의 정수입니다. 둘 이상의 배포가 동일한 디바이스를 대상으로 하는 경우 우선 순위가 가장 높은 배포가 적용됩니다.
--metrics: 보고된 속성을 쿼리 edgeHub 하여 배포 상태를 추적하는 메트릭입니다. 메트릭은 JSON 입력 또는 파일 경로를 사용합니다. 예: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'

Azure CLI를 사용하여 배포를 모니터링하려면 IoT Edge 배포 모니터링을 참조하세요.

참고 항목

새 IoT Edge 배포를 만들 때 IoT Hub가 새 구성을 처리하고 원하는 새 속성을 대상 디바이스로 보내는 데 최대 5분이 걸릴 수 있습니다.

배포 수정

배포를 변경하면 변경 내용이 모든 대상 디바이스에 즉시 복제됩니다.

대상 조건을 업데이트하면 다음과 같은 변경 내용이 발생합니다.

디바이스가 이전 대상 조건을 충족하지 않았지만 새 대상 조건을 충족하고 이 배포가 해당 디바이스의 가장 높은 우선 순위인 경우 이 배포가 디바이스에 적용됩니다.
현재 이 배포를 실행하는 디바이스가 더 이상 대상 조건을 충족하지 않는 경우 이 배포를 제거하고 다음으로 높은 우선 순위 배포를 수행합니다.
현재 이 배포를 실행하는 디바이스가 더 이상 대상 조건을 충족하지 않고 다른 배포의 대상 조건을 충족하지 않는 경우 디바이스에서 변경이 발생하지 않습니다. 디바이스는 현재 상태에서 현재 모듈을 계속 실행하지만 더 이상 이 배포의 일부로 관리되지 않습니다. 디바이스가 다른 배포의 대상 조건을 충족하면 이 배포를 제거하고 새 배포를 수행합니다.

배포 매니페스트에 정의된 모듈과 경로를 포함하는 배포의 콘텐츠는 업데이트할 수 없습니다. 배포 콘텐츠를 업데이트하려면 우선 순위가 더 높은 동일한 디바이스를 대상으로 하는 새 배포를 만듭니다. 대상 조건, 레이블, 메트릭 및 우선 순위를 포함하여 기존 모듈의 특정 속성을 수정할 수 있습니다.

az iot edge deployment update 명령을 사용하여 배포를 업데이트합니다.

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

배포 업데이트 명령은 다음 매개 변수를 사용합니다.

--deployment-id: IoT Hub의 배포 이름입니다.
--hub-name: 배포가 있는 IoT Hub의 이름입니다. 허브가 현재 구독에 있어야 합니다. 다른 구독으로 전환하려면 az account set -s <subscription-name>을 실행합니다.
--set: 배포의 속성을 변경합니다. 다음 속성을 변경할 수 있습니다.
- targetCondition(예: targetCondition=tags.___location.state='Oregon')
- labels
- priority
--add: 대상 조건 또는 레이블을 포함하여 배포에 새 속성을 추가합니다.
--remove: 대상 조건 또는 레이블을 포함하여 기존 속성을 제거합니다.

배포 삭제

배포를 삭제하면 디바이스는 우선 순위가 가장 높은 다음 배포를 사용합니다. 디바이스가 다른 배포의 대상 조건을 충족하지 않으면 배포를 삭제할 때 모듈이 제거되지 않습니다.

az iot edge deployment delete 명령을 실행하여 배포를 삭제합니다.

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

이 deployment delete 명령은 다음 매개 변수를 사용합니다.

--deployment-id. IoT Hub에 있는 배포의 이름입니다.
--hub-name. 배포가 있는 IoT Hub의 이름입니다. 허브가 현재 구독에 있어야 합니다. az account set -s [subscription name] 명령을 사용하여 원하는 구독으로 전환합니다.

다음 단계

IoT Edge 디바이스에 모듈 배포에 대해 자세히 알아봅니다.

다음을 통해 공유

Azure CLI를 사용하여 대규모로 IoT Edge 모듈 배포 및 모니터링

필수 조건

배포 매니페스트 구성

계층화된 배포

태그를 사용하여 디바이스 식별

배포 만들기

배포 수정

배포 삭제

다음 단계

피드백

추가 리소스