Azure CLI를 사용하여 IoT 허브를 자동으로 마이그레이션하는 방법

아티클
02/23/2024

Azure CLI를 사용하여 IoT 허브를 새 지역, 새 계층 또는 새 구성으로 마이그레이션합니다.

이 문서의 단계는 다음을 수행하려는 경우에 유용합니다.

무료 계층에서 기본 또는 표준 계층 IoT 허브로 업그레이드합니다.
IoT 허브를 새 지역으로 이동합니다.
백업으로 사용할 IoT 허브 상태 정보를 내보냅니다.
IoT 허브의 파티션 수를 늘립니다.
프로덕션 환경이 아닌 개발을 위한 허브를 설정합니다.

자동 및 수동 마이그레이션 단계 비교

이 문서의 결과는 Azure Resource Manager 템플릿을 사용하여 Azure IoT 허브를 마이그레이션하는 방법과 유사 하지만 프로세스가 다릅니다. 시작하기 전에 시나리오에 적합한 프로세스를 결정합니다.

Azure CLI 프로세스(이 문서):
- 디바이스 레지스트리, 라우팅 및 엔드포인트 정보, IoT Edge 배포 또는 자동 디바이스 관리 구성과 같은 기타 구성 세부 정보를 마이그레이션합니다.
- 소수의 디바이스(예: 최대 10,000개)를 마이그레이션하는 경우 용이합니다.
- Azure Storage 계정이 필요하지 않습니다.
- 키 기반 인증을 사용하고 ARM 템플릿 출력에 포함하는 라우팅 및 파일 업로드 엔드포인트에 대한 연결 문자열 수집합니다.
수동 프로세스:
- 디바이스 레지스트리와 라우팅 및 엔드포인트 정보를 마이그레이션합니다. 새 IoT 허브에서 다른 구성 세부 정보를 수동으로 다시 만들어야 합니다.
- 다수의 디바이스(예: 100,000개 이상)를 마이그레이션하는 경우 더 빠릅니다.
- Azure Storage 계정을 사용하여 디바이스 레지스트리를 전송합니다.
- ARM 템플릿 출력에서 키 기반 인증을 사용하는 라우팅 및 파일 업로드 엔드포인트에 대한 연결 문자열 스크럽하고 수동으로 다시 추가해야 합니다.

필수 조건

Azure CLI

이 문서에 설명된 기능을 사용하려면 azure-iot 확장 버전 0.20.0 이상이 필요합니다. 확장 버전을 확인하려면 az --version을 실행합니다. 확장을 업데이트하려면 az extension update --name azure-iot를 실행합니다.

레거시 azure-cli-iot-ext 확장이 아직 설치되어 있는 경우 azure-iot 확장을 추가하기 전에 해당 확장을 제거합니다.

IoT 허브 상태

IoT 허브의 상태 마이그레이션에 대해 이야기할 때는 다음 세 가지 측면의 조합을 참조합니다.

ARM(Azure Resource Manager) 리소스. 이 측면은 리소스 템플릿에서 정의할 수 있는 모든 것이며, Azure Portal의 IoT 허브에서 리소스 템플릿을 내보낸 경우 얻을 수 있는 정보와 동일합니다. Azure Resource Manager 측면의 일부로 캡처된 정보는 다음과 같습니다.
- 기본 제공 이벤트 허브의 보존 시간
- 인증서
- 클라우드-디바이스 속성
- 디바이스 SAS 사용 안 함
- 로컬 인증 사용 안 함
- 파일 업로드 알림 사용
- 파일 업로드 스토리지 엔드포인트
- Identities
  - 사용자 할당 ID
  - 시스템 할당 ID(사용 또는 사용 안 함)
- 네트워크 규칙 집합
- 라우팅
  - 사용자 지정 엔드포인트
  - 대체(fallback) 경로
  - 경로
- 태그
구성. 이 측면은 ARM 템플릿에 표시되지 않는 IoT 허브의 측면을 위한 것입니다. 특히 이 측면은 자동 디바이스 관리 구성 및 IoT Edge 배포를 다룹니다.
디바이스. 이 측면은 다음을 포함하는 디바이스 레지스트리의 정보를 나타냅니다.
- 디바이스 ID 및 트윈
- 모듈 ID 및 트윈

여기에 나열되지 않은 IoT Hub 속성 또는 구성이 올바르게 내보내거나 가져오지 않을 수 있습니다.

IoT 허브의 상태 내보내기

az iot hub state export 명령을 사용하여 IoT 허브의 상태를 JSON 파일로 내보냅니다.

하나의 명령으로 내보내기 및 가져오기 단계를 모두 실행하려면 이 문서 뒷부분의 IoT Hub 마이그레이션 섹션을 참조하세요.

IoT 허브의 상태를 내보낼 때 내보낼 측면을 선택할 수 있습니다.

매개 변수	세부 정보
`--aspects`	내보낼 상태 측면입니다. arm, 구성 또는 디바이스와 같은 허용된 값 중 하나 이상을 지정합니다. 이 매개 변수를 제외하면 세 가지 측면이 모두 내보내집니다.
`--state-file -f`	상태 정보가 기록되는 파일의 경로입니다.
`--replace -r`	이 매개 변수를 포함하면 내보내기 명령이 상태 파일의 내용을 덮어씁니다.
`--hub-name -n` or `--login -l`	원본 IoT 허브의 이름(`-n`) 또는 원본 IoT 허브의 연결 문자열(`-l`)입니다. 둘 다 제공된 경우 연결 문자열이 우선합니다.
`--resource-group -g`	원본 IoT 허브에 대한 리소스 그룹의 이름입니다.

다음 예제에서는 IoT 허브 상태의 모든 측면을 myHub-state라는 파일로 내보냅니다.

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

다음 예제에서는 IoT 허브 상태의 디바이스 및 Azure Resource Manager 측면만 내보내고 기존 파일의 콘텐츠를 덮어씁니다.

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

엔드포인트 내보내기

IoT 허브의 Azure Resource Manager 측면을 내보내도록 선택하는 경우 내보내기 명령은 키 기반 인증이 있는 모든 엔드포인트에 대한 연결 문자열을 검색하여 출력 ARM 템플릿에 포함합니다.

또한 내보내기 명령은 모든 엔드포인트를 검사하여 연결된 리소스가 아직 존재하는지 확인합니다. 그렇지 않은 경우 해당 엔드포인트 및 해당 엔드포인트를 사용하는 모든 경로는 내보내지지 않습니다.

IoT 허브의 상태 가져오기

az iot hub state import 명령을 사용하여 내보낸 파일의 상태 정보를 새 IoT 허브 또는 기존 IoT 허브로 가져옵니다.

하나의 명령으로 내보내기 및 가져오기 단계를 모두 실행하려면 이 문서 뒷부분의 IoT Hub 마이그레이션 섹션을 참조하세요.

매개 변수	세부 정보
`--aspects`	가져올 상태 측면입니다. arm, 구성 또는 디바이스와 같은 허용된 값 중 하나 이상을 지정합니다. 이 매개 변수를 제외하면 세 가지 측면을 모두 가져옵니다.
`--state-file -f`	내보낸 상태 파일의 경로입니다.
`--replace -r`	이 매개 변수를 포함하면 가져오기 명령은 대상 허브의 현재 상태를 삭제합니다.
`--hub-name -n` or `--login -l`	대상 IoT 허브의 이름(`-n`) 또는 대상 IoT 허브의 연결 문자열(`-l`)입니다. 둘 다 제공된 경우 연결 문자열이 우선합니다.
`--resource-group -g`	대상 IoT 허브에 대한 리소스 그룹의 이름입니다.

다음 예제에서는 모든 측면을 새 IoT 허브로 가져오며, 아직 없는 경우 만들어집니다.

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

다음 예제에서는 이미 존재해야 하는 새 IoT 허브로 디바이스 및 구성 측면만 가져오고 기존 디바이스 및 구성을 덮어씁니다.

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

상태 가져오기를 사용하여 새 IoT 허브 만들기

az iot hub state import 명령을 사용하여 새 IoT 허브를 만들거나 기존 IoT 허브에 쓸 수 있습니다.

새 IoT Hub를 만들려면 가져오기 명령에 arm 측면을 포함해야 합니다. arm이 명령에 포함되지 않고 대상 허브가 없으면 가져오기 명령이 실패합니다.

대상 허브가 없으면 가져오기 명령에도 --resource-group 매개 변수가 필요합니다.

상태 가져오기를 사용하여 기존 IoT 허브 업데이트

대상 IoT 허브가 이미 있는 경우 az iot hub state import 명령에 arm 측면이 필요하지 않습니다. arm 측면을 포함하는 경우 허브를 만든 후에 변경할 수 없는 다음 속성을 제외한 모든 리소스 속성을 덮어씁니다.

위치
SKU
기본 제공 Event Hubs 파티션 수
데이터 보존
기능

--resource-group이 가져오기 명령에 지정되고 IoT 허브의 현재 리소스 그룹과 다른 경우 이미 존재하는 것과 동일한 이름의 새 허브를 만들려고 시도하므로 명령이 실패합니다.

가져오기 명령에 --replace 플래그를 포함하는 경우 허브 상태가 업로드되기 전에 대상 허브에서 다음 IoT 허브 측면이 제거됩니다.

ARM: 대상 허브에서 업로드된 모든 인증서가 삭제됩니다. 인증서가 있는 경우 etag를 업데이트해야 합니다.
디바이스: 모든 디바이스 및 모듈, 에지 및 비에지가 삭제됩니다.
구성: 모든 디바이스 관리 구성 및 IoT Edge 배포가 삭제됩니다.

IoT 허브 마이그레이션

az iot hub state migrate 명령을 사용하여 한 IoT 허브의 상태를 새 IoT 허브 또는 기존 IoT 허브로 마이그레이션합니다.

이 명령은 내보내기 및 가져오기 단계를 단일 명령으로 래핑하지만 출력 파일이 없습니다. IoT 허브 상태 내보내기 및 IoT 허브 상태 가져오기 섹션에 설명된 모든 지침 및 제한 사항은 state migrate 명령에도 적용됩니다.

많은 디바이스(예: 몇 백 또는 몇 천 개)를 사용하여 디바이스 레지스트리를 마이그레이션하는 경우 마이그레이션 명령을 실행하는 대신 내보내기 및 가져오기 명령을 개별적으로 실행하는 것이 더 쉽고 빠를 수 있습니다.

매개 변수	세부 정보
`--aspects`	마이그레이션할 상태 측면입니다. arm, 구성 또는 디바이스와 같은 허용된 값 중 하나 이상을 지정합니다. 이 매개 변수를 제외하면 세 가지 측면이 모두 마이그레이션됩니다.
`--replace -r`	이 매개 변수를 포함하면 마이그레이션 명령은 대상 허브의 현재 상태를 삭제합니다.
`--destination-hub --dh` or `--destination-hub-login --dl`	대상 IoT 허브의 이름(`--dh`) 또는 대상 IoT 허브의 연결 문자열(`--dl`)입니다. 둘 다 제공된 경우 연결 문자열이 우선합니다.
`--destination-resource-group --dg`	대상 IoT 허브에 대한 리소스 그룹의 이름입니다. 대상 허브가 없는 경우 대상 리소스 그룹이 필요합니다.
`--origin-hub --oh` or `--origin-hub-login --ol`	원본 IoT 허브의 이름(`--oh`) 또는 원본 IoT 허브의 연결 문자열(`--ol`)입니다. 둘 다 제공된 경우 연결 문자열이 우선합니다. 연결 문자열을 사용하여 Azure CLI 세션에 로그인할 필요가 없도록 합니다.
`--origin-resource-group --og`	원본 IoT 허브에 대한 리소스 그룹의 이름입니다.

다음 예제에서는 원본 허브의 모든 측면을 대상 허브로 마이그레이션합니다. 대상 허브가 없는 경우 만들어집니다.

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

마이그레이션 문제 해결

디바이스 또는 구성을 내보내거나 가져올 수 없는 경우 해당 속성에 대한 액세스 권한이 있는지 확인합니다. 액세스를 확인하는 한 가지 방법은 az iot hub device-identity list 또는 az iot hub configuration list 명령을 실행하는 것입니다.

az iot hub state migrate 명령이 실패하면 내보내기 및 가져오기 명령을 별도로 실행해 보세요. 두 명령은 마이그레이션 명령과 동일한 기능을 생성하지만 별도로 실행하면 내보내기 명령에서 만든 상태 파일을 검토할 수 있습니다.

다음 단계

IoT 허브에서 ID 레지스트리에 대한 대량 작업을 수행하는 방법에 대한 자세한 내용은 대량으로 IoT 허브 디바이스 ID 가져오기 및 내보내기를 참조하세요.

다음을 통해 공유