IoT Hub용 디바이스 업데이트에서 델타 업데이트를 이해하고 사용하는 방법(미리 보기)

아티클
10/16/2024

델타 업데이트를 사용하면 원본 이미지와 대상 이미지의 두 전체 업데이트 간의 변경 내용만 나타내는 작은 업데이트를 생성할 수 있습니다. 이 접근 방법은 특히 원본 업데이트와 대상 업데이트 간에 몇 가지 변경 내용만 있는 경우 디바이스에 업데이트를 다운로드하는 데 사용되는 대역폭을 줄이는 데 이상적입니다.

참고 항목

델타 업데이트 기능은 현재 퍼블릭 미리 보기로 제공됩니다.

IoT Hub용 디바이스 업데이트에서 델타 업데이트를 사용하기 위한 요구 사항

원본 및 대상 업데이트 파일은 SWU(SWUpdate) 형식이어야 합니다.
각 SWUpdate 파일 내에는 Ext2, Ext3 또는 Ext4 파일 시스템을 사용하는 원시 이미지가 있어야 합니다.
델타 생성 프로세스는 최적의 델타를 생성하기 위해 gzip 압축을 사용하여 대상 SWU 업데이트를 다시 압축합니다. 생성된 델타 업데이트 파일과 함께 이 재압축된 대상 SWU 업데이트를 디바이스 업데이트 서비스로 가져옵니다.

디바이스 업데이트 에이전트 및 델타 프로세서 구성 요소를 사용하여 디바이스 구성

디바이스가 디바이스 업데이트 서비스에서 델타 업데이트를 다운로드하고 설치하려면 여러 구성 요소가 존재하고 구성되어야 합니다.

Device Update 에이전트

디바이스 업데이트 에이전트는 다운로드, 설치 및 다시 시작 작업을 포함하여 디바이스에서 업데이트 프로세스를 ‘오케스트레이션’합니다. 디바이스 업데이트 에이전트를 디바이스에 추가하고 사용하도록 구성합니다. 에이전트 버전 1.0 이상을 사용합니다. 지침은 디바이스 업데이트 에이전트 프로비저닝을 참조하세요.

업데이트 처리기

업데이트 처리기는 디바이스 업데이트 에이전트와 통합하여 실제 업데이트 설치를 수행합니다. 델타 업데이트의 경우 수정하려는 고유한 SWUpdate 업데이트 처리기가 아직 없는 경우 microsoft/swupdate:2 업데이트 처리기로 시작합니다.

델타 프로세서

델타 프로세서는 델타 파일이 다운로드된 후 디바이스에 원래 SWU 이미지 파일을 다시 만들어 업데이트 처리기가 SWU 파일을 설치할 수 있도록 합니다. 델타 프로세서는 Azure/iot-hub-device-update-delta GitHub 리포지토리에서 사용할 수 있습니다.

델타 프로세서 구성 요소를 디바이스 이미지에 추가하고 사용하도록 구성하려면 Ubuntu 20.04 이상에서 지원되는 .deb 패키지를 다운로드할 수 있습니다. 다른 배포판을 사용하는 경우 README.md 지침에 따라 CMAKE를 사용하여 원본에서 델타 프로세서를 빌드합니다. 여기에서 공유 개체(libadudiffapi.so)를 /usr/lib 디렉터리에 복사하여 직접 설치합니다.

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

디바이스에 원본 SWU 이미지 파일 추가

델타 업데이트를 디바이스에 다운로드한 후에는 이전에 디바이스에 캐시된 유효한 원본 SWU 파일과 비교해야 합니다. 이 프로세스는 델타 업데이트가 전체 대상 이미지를 다시 만드는 데 필요합니다. 이 캐시된 이미지를 채우는 가장 간단한 방법은 디바이스 업데이트 서비스를 통해 디바이스에 전체 이미지 업데이트를 배포하는 것입니다(기존 가져오기 및 배포 프로세스 사용). 디바이스가 디바이스 업데이트 에이전트(버전 1.0 이상) 및 델타 프로세서로 구성된 경우 디바이스 업데이트 에이전트는 이후 델타 업데이트 사용을 위해 설치된 SWU 파일을 자동으로 캐시합니다.

대신 디바이스에서 원본 이미지를 직접 미리 채우려는 경우 이미지가 필요한 경로는 다음과 같습니다.

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

기본적으로 BASE_SOURCE_DOWNLOAD_CACHE_PATH는 경로 /var/lib/adu/sdc/[provider]입니다. [provider] 값은 원본 SWU 파일에 대한 updateId의 공급자 부분입니다.

ENCODED_HASH는 이진 파일 SHA256의 base64 16진수 문자열이지만 base64 16진수 문자열로 인코딩한 후 다음과 같이 문자를 인코딩합니다.

+는 octets _2B로 인코딩됩니다.
/는 octets _2F로 인코딩됩니다.
=는 octets _3D로 인코딩됩니다.

DiffGen 도구를 사용하여 델타 업데이트 생성

환경 전제 조건

DiffGen을 사용하여 델타를 만들기 전에 환경 머신에 몇 가지 항목을 다운로드 및/또는 설치해야 합니다. Linux 환경 및 특히 Ubuntu 20.04(또는 Windows에서 기본적으로 Linux용 Windows 하위 시스템)를 사용하는 것이 좋습니다.

다음 표에서는 필요한 콘텐츠 목록, 검색 위치 및 권장 설치(필요한 경우)를 제공합니다.

이진 이름	가져올 위치	설치 방법
DiffGen	Azure/iot-hub-device-update-delta GitHub 리포지토리	델타 업데이트를 생성하는 데 사용할 컴퓨터에서 OS/배포판과 일치하는 버전을 다운로드합니다.
. NETCore 런타임, 버전 8.0.0	터미널/패키지 관리자를 통해	Linux에 대한 지침. 런타임만 필요합니다.

DiffGen을 사용하여 델타 업데이트 만들기

DiffGen 도구는 여러 인수로 실행됩니다. 모든 인수가 필요하며 전체 구문은 다음과 같습니다.

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive]

스크립트 recompress_tool.py는 [recompressed_target_archive] 파일을 만들기 위해 실행되며, 이 파일은 diff를 만들기 위한 대상 파일로 [target_archive] 대신 사용됩니다.
[recompressed_target_archive] 내의 이미지 파일은 gzip으로 압축됩니다.

SWU 파일이 서명된 경우(가능성이 높음) 다른 인수도 필요합니다.

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive] "[signing_command]"

[recompressed_target_archive]을 대상 파일로 사용하는 것 외에도 서명 명령 문자열 매개 변수를 제공하면 recompress_and_sign_tool.py가 실행되어 파일 [recompressed_target_archive]가 생성되고, 서명된 보관 파일 내에 sw-description 파일이 포함됩니다(즉, sw-description.sig 파일이 있음). Azure/iot-hub-device-update-delta GitHub 리포지토리에서 샘플 sign_file.sh 스크립트를 사용할 수 있습니다. 스크립트를 열고 편집하여 프라이빗 키 파일의 경로를 추가한 다음 저장합니다. 샘플 사용은 예제 섹션을 참조하세요.

다음 표에서는 이러한 인수를 좀 더 자세히 설명합니다.

인수	설명
[source_archive]	델타를 만들 때 델타의 기준이 되는 이미지입니다. 중요: 이 이미지는 디바이스에 이미 있는 이미지(예: 이전 업데이트에서 캐시됨)와 동일해야 합니다.
[target_archive]	델타가 디바이스를 업데이트하는 이미지입니다.
[output_path]	생성된 후 델타 파일이 배치될 호스트 컴퓨터의 경로(생성되는 델타 파일의 원하는 이름 포함)입니다. 경로가 없으면 도구에서 경로를 만듭니다.
[log_folder]	로그가 생성되는 호스트 컴퓨터의 경로입니다. 이 위치를 출력 경로의 하위 폴더로 정의하는 것이 좋습니다. 경로가 없으면 도구에서 경로를 만듭니다.
[working_folder]	델타 생성 중에 참고 자료 및 기타 작업 파일이 배치되는 컴퓨터의 경로입니다. 이 위치를 출력 경로의 하위 폴더로 정의하는 것이 좋습니다. 경로가 없으면 도구에서 경로를 만듭니다.
[recompressed_target_archive]	다시 압축된 대상 파일이 만들어질 호스트 컴퓨터의 경로입니다. 이 파일은 diff 생성을 위한 대상 파일로 <target_archive> 대신 사용됩니다. DiffGenTool을 호출하기 전에 이 경로가 있으면 경로를 덮어씁니다. 이 경로를 출력 경로의 하위 폴더에 파일로 정의하는 것이 좋습니다.
"[signing_command]"(선택 사항)	다시 압축된 보관 파일 내에서 sw-description 파일에 서명하는 데 사용되는 사용자 지정 가능한 명령입니다. 압축된 보관 파일의 sw-description 파일은 서명 명령에 대한 입력 매개 변수로 사용됩니다. DiffGenTool에서는 `.sig`가 추가된 입력의 이름을 사용하여 서명 명령으로 새 서명 파일을 만들어야 합니다. 전체 명령이 단일 매개 변수로 전달되도록 매개 변수를 큰따옴표로 묶는 것이 필요합니다. 또한 서명에 사용되는 키 경로에 '~' 문자를 추가하지 말고 전체 홈 경로를 대신 사용합니다(예: ~/keys/priv.pem 대신 /home/USER/keys/priv.pem 사용).

DiffGen 예제

이러한 예제에서는 /mnt/o/temp 디렉터리(WSL)에서 작업합니다.

입력 원본 파일과 압축된 대상 파일 간에 diff 만들기:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]  
/mnt/o/temp/[target file.swu]  
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]

서명 매개 변수(SWU 파일이 서명된 경우 필요)도 사용하는 경우 이전에 참조한 샘플 sign_file.sh 스크립트를 사용할 수 있습니다. 먼저 스크립트를 열고 편집하여 프라이빗 키 파일에 대한 경로를 추가합니다. 스크립트를 저장한 다음, 다음과 같이 DiffGen을 실행합니다.

입력 원본 파일과 다시 압축/다시 서명된 대상 파일 간에 diff 만들기:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]
/mnt/o/temp/[target file.swu]   
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]  
/mnt/o/temp/[path to script]/sign_file.sh

생성된 델타 업데이트 가져오기

디바이스 업데이트 서비스에 업데이트를 가져오는 기본 프로세스는 델타 업데이트에 대해 변경되지 않으므로 아직 확인하지 않은 경우 IoT Hub용 Azure 디바이스 업데이트로 가져올 업데이트를 준비하는 방법 페이지를 검토해야 합니다

가져오기 매니페스트 생성

업데이트를 디바이스 업데이트 서비스로 가져오는 첫 번째 단계는 가져오기 매니페스트가 없는 경우 이 매니페스트를 만드는 것입니다. 가져오기 매니페스트에 대한 자세한 내용은 디바이스 업데이트로 업데이트 가져오기를 참조하세요. 델타 업데이트의 경우 가져오기 매니페스트는 다음 두 파일을 참조해야 합니다.

DiffGen 도구를 실행할 때 생성된 ‘다시 압축된’ 대상 SWU 이미지
DiffGen 도구를 실행할 때 생성된 델타 파일

델타 업데이트 기능은 관련 파일이라는 기능을 사용합니다. 이 파일에는 버전 5 이상인 가져오기 매니페스트가 필요합니다.

관련 파일 기능을 사용하여 델타 업데이트에 대한 가져오기 매니페스트를 만들려면 가져오기 매니페스트에 relatedFiles 및 downloadHandler 개체를 추가해야 합니다.

relatedFiles 개체를 사용하여 파일 이름, 파일 크기 및 sha256 해시를 포함하여 델타 업데이트 파일에 대한 정보를 지정합니다. 또한 델타 업데이트 기능에 고유한 다음 두 가지 속성을 지정해야 합니다.

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
}

이러한 두 속성은 델타 업데이트를 만들 때 DiffGen 도구에 대한 입력으로 사용한 원본 SWU 이미지 파일에만 적용됩니다. 원본 이미지를 실제로 가져오지 않더라도 원본 SWU 이미지에 대한 정보는 가져오기 매니페스트에 필요합니다. 델타가 다운로드되면 디바이스의 델타 구성 요소는 원본 이미지에 대한 이 메타데이터를 사용하여 디바이스에서 이미지를 찾습니다.

downloadHandler 개체를 사용하여 Device Update 에이전트가 관련 파일 기능을 사용하여 델타 업데이트를 조정하는 방법을 지정합니다. 델타 기능을 위해 고유한 버전의 디바이스 업데이트 에이전트를 사용자 지정하지 않는 한 이 downloadHandler만 사용해야 합니다.

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Azure CLI(명령줄 인터페이스)를 사용하여 델타 업데이트에 대한 가져오기 매니페스트를 생성할 수 있습니다. 이전에 Azure CLI를 사용하여 가져오기 매니페스트를 만든 적이 없다면 기본 가져오기 매니페스트 만들기를 참조하세요.

az iot du update init v5
--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

생성된 가져오기 매니페스트 JSON을 확장자를 지정하여 .importmanifest.json 파일에 저장합니다.

Azure Portal을 사용하여 가져오기

가져오기 매니페스트를 만들면 델타 업데이트를 가져올 준비가 된 것입니다. 가져오려면 IoT Hub용 디바이스 업데이트에 업데이트 추가의 지침을 따릅니다. 가져올 때 다음 항목을 포함해야 합니다.

이전 단계에서 만든 가져오기 매니페스트 .json 파일
DiffGen 도구를 실행할 때 생성된 ‘다시 압축된’ 대상 SWU 이미지
DiffGen 도구를 실행할 때 생성된 델타 파일

디바이스에 델타 업데이트 배포

델타 업데이트를 배포할 때 Azure Portal의 환경은 일반 이미지 업데이트를 배포하는 것과 동일해 보입니다. 업데이트 배포에 대한 자세한 내용은 Azure IoT Hub에 대한 디바이스 업데이트를 사용하여 업데이트 배포를 참조하세요.

델타 업데이트에 대한 배포를 만든 후 디바이스 업데이트 서비스와 클라이언트는 배포하려는 각 디바이스에 대해 유효한 델타 업데이트가 있는지 자동으로 식별합니다. 유효한 델타가 발견되면 델타 업데이트가 다운로드되어 해당 디바이스에 설치됩니다. 유효한 델타 업데이트가 없으면 전체 이미지 업데이트(재압축된 대상 SWU 이미지)가 대신 대체로 다운로드됩니다. 이 접근 방법을 사용하면 업데이트를 배포하는 모든 디바이스에서 적절한 버전을 사용하도록 할 수 있습니다.

델타 업데이트 배포에는 다음과 같은 세 가지 결과가 발생할 수 있습니다.

델타 업데이트가 설치되었습니다. 디바이스가 새 버전에 있습니다.
델타 업데이트를 사용할 수 없거나 설치하지 못했지만 전체 이미지의 대체 설치가 성공했습니다. 디바이스가 새 버전에 있습니다.
델타 및 전체 이미지로의 대체가 모두 실패했습니다. 디바이스가 여전히 이전 버전입니다.

위의 결과 중 어떤 것이 발생했는지 확인하려면 실패한 상태의 디바이스를 선택하여 오류 코드 및 확장 오류 코드가 있는 설치 결과를 볼 수 있습니다. 필요한 경우 실패한 여러 디바이스에서 로그를 수집할 수도 있습니다.

델타 업데이트가 성공하면 디바이스에 "성공" 상태가 표시됩니다.

델타 업데이트가 실패했지만 전체 이미지로 성공적으로 대체된 경우 다음과 같은 오류 상태가 표시됩니다.

resultCode: [0보다 큰 값]
extendedResultCode: [0이 아닌 값]

업데이트에 실패한 경우 다음 지침을 사용하여 해석할 수 있는 오류 상태가 표시됩니다.

result.h의 디바이스 업데이트 에이전트 오류로 시작합니다.

델타 업데이트에 사용되는 다운로드 처리기 기능과 관련된 디바이스 업데이트 에이전트의 오류는 0x9로 시작합니다.

구성 요소	소수	16진수	참고 항목
EXTENSION_MANAGER	0	0x00	확장 관리자 다운로드 처리기 논리의 오류를 나타냅니다. 예: 0x900XXXXX
PLUGIN	1	0x01	다운로드 처리기 플러그 인 공유 라이브러리 사용 오류를 나타냅니다. 예: 0x901XXXXX
예약됨	2 - 7	0x02 - 0x07	다운로드 처리기를 위해 예약되었습니다. 예: 0x902XXXXX
일반	8	0x08	델타 다운로드 처리기 확장 최상위 논리의 오류를 나타냅니다. 예: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	델타 다운로드 처리기 확장 원본 업데이트 캐시의 오류를 나타냅니다. 예: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	델타 프로세서 API의 오류에 대한 오류 코드입니다. 예: 0x90AXXXXX

result.h에 오류 코드가 없는 경우 델타 프로세서 구성 요소에서 오류가 발생할 수 있습니다(디바이스 업데이트 에이전트와는 별개). 그렇다면 extendedResultCode는 다음 16진수 형식인 0x90AXXXXX의 음수 10진수 값입니다.
- 9는 "델타 기능"입니다.
- 0A는 "델타 프로세서 구성 요소"(ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)입니다.
- XXXXX는 FIT 델타 프로세서의 20비트 오류 코드입니다.

오류 코드 정보에 따라 문제를 해결할 수 없는 경우 GitHub 문제를 제출하여 추가 지원을 받으세요.

다음 단계

일반 문제 해결

다음을 통해 공유