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

아티클
04/11/2024

적용 대상: IoT Edge 1.4

Important

IoT Edge 1.4는 지원되는 릴리스입니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.

Azure CLI에서 한 번에 여러 디바이스에 대한 지속적인 배포를 관리하는 Azure IoT Edge 자동 배포를 만듭니다. IoT Edge의 자동 배포는 Azure IoT Hub의 장치 관리 기능의 일부입니다. 배포는 여러 모듈을 여러 디바이스에 배포하고, 모듈의 상태를 추적하며, 필요한 경우 변경할 수 있게 하는 동적 프로세스입니다.

이 문서에서는 Azure CLI 및 IoT 확장을 설정합니다. 그런 다음, 사용 가능한 CLI 명령을 사용하여 IoT Edge 디바이스 세트에 모듈을 배포하고 프로세스를 모니터링하는 방법을 알아봅니다.

필수 조건

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 확장.

배포 매니페스트 구성

배포 매니페스트는 배포할 모듈, 모듈 간의 데이터 흐름 및 모듈 쌍의 desired 속성을 설명하는 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.1",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.1",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "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 디바이스의 필수 구성 요소를 제공하기 위해 디바이스에 표준 자동 배포가 필요합니다.

예를 들어 1개의 모듈이 있는 기본 계층화된 배포 매니페스트의 예제는 다음과 같습니다.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.0"
        }
      },
      "$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를 설정하는 계층화된 배포를 살펴보았습니다. 이 계층화된 배포가 동일한 모듈이 이미 적용된 디바이스를 대상으로 하는 경우 기존 desired 속성을 덮어씁니다. 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 [int]

--layered 플래그와 함께 동일한 명령을 사용하여 계층화된 배포를 만듭니다.

배포를 위한 create 명령은 다음 매개 변수를 사용합니다.

--layered. 배포를 계층화된 배포로 식별하는 선택적 플래그입니다.
--deployment-id. IoT 허브에 만들 배포 이름입니다. 배포에 최대 128자의 소문자로 된 고유한 이름을 지정합니다. 공백과 잘못된 문자(& ^ [ ] { } \ | " < > /)는 사용하지 않도록 합니다. 이 매개 변수는 필수입니다.
--content. 배포 매니페스트 JSON에 대한 파일 경로입니다. 이 매개 변수는 필수입니다.
--hub-name. 배포를 만들 IoT 허브의 이름입니다. 허브가 현재 구독에 있어야 합니다. 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 reported 속성을 쿼리하여 배포 상태를 추적하는 메트릭입니다. 메트릭은 JSON 입력 또는 파일 경로를 사용합니다. 예: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'

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

참고 항목

새 IoT Edge 배포가 생성되면 IoT Hub가 새 구성을 처리하고 원하는 새 desired 속성을 대상 디바이스에 전파하는 데 최대 5분이 걸릴 수 있습니다.

배포 수정

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

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

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

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

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

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

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

--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 모듈 배포 및 모니터링

필수 조건

배포 매니페스트 구성

계층화된 배포

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

배포 만들기

배포 수정

배포 삭제

다음 단계

추가 리소스