IoT Edge 디바이스 문제 해결
적용 대상: 
IoT Edge 1.5 IoT Edge 1.4
Important
IoT Edge 1.5 LTS 및 IoT Edge 1.4 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일에 수명이 종료됩니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.
작업 환경에서 Azure IoT Edge를 실행하는 동안 문제가 발생할 경우 이 문서를 문제 해결 및 진단에 대한 가이드로 사용합니다.
'check' 명령 실행
IoT Edge 문제를 해결하는 첫 번째 단계는 일반적인 문제에 대한 구성 및 연결 테스트 컬렉션을 실행하는 check 명령을 사용하는 것입니다. check 명령은 release 1.0.7 이상에서 사용할 수 있습니다.
참고 항목
문제 해결 도구는 IoT Edge 디바이스가 프록시 서버 뒤에 있는 경우 연결 확인을 실행할 수 없습니다.
다음과 같이 check 명령을 실행하거나 --help 플래그를 포함하여 전체 옵션 목록을 볼 수 있습니다.
sudo iotedge check
문제 해결 도구는 다음과 같은 세 가지 범주로 정렬된 많은 검사를 실행합니다.
- 구성 검사는 구성 파일 및 컨테이너 엔진과 관련된 문제를 포함하여 IoT Edge 디바이스가 클라우드에 연결되지 못하게 하는 세부 정보를 검사합니다.
- 연결 확인은 IoT Edge 런타임이 호스트 디바이스의 포트에 액세스할 수 있고 모든 IoT Edge 구성 요소가 IoT Hub에 연결할 수 있는지 확인합니다. IoT Edge 디바이스가 프록시 뒤에 있는 경우 이 검사 집합은 오류를 반환합니다.
- 프로덕션 준비 검사는 디바이스 CA(인증 기관) 인증서 및 모듈 로그 파일 구성의 상태와 같은 권장 프로덕션 모범 사례를 확인합니다.
IoT Edge 검사 도구는 컨테이너를 사용하여 진단을 실행합니다. 컨테이너 이미지 mcr.microsoft.com/azureiotedge-diagnostics:latest는 Microsoft Container Registry를 통해 사용할 수 있습니다. 인터넷에 직접 액세스하지 않고 디바이스에서 검사를 실행해야 하는 경우 디바이스에서 컨테이너 이미지에 액세스해야 합니다.
중첩된 IoT Edge 디바이스를 사용하는 시나리오에서는 부모 디바이스를 통해 이미지 풀을 라우팅하여 다운스트림 디바이스에 있는 진단 이미지에 액세스할 수 있습니다.
sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2
오류 또는 경고가 발생하는 경우 수행할 작업을 포함하여 이 도구를 실행하는 각 진단 검사에 대한 자세한 내용은 IoT Edge 문제 해결 확인을 참조하세요.
'support-bundle' 명령을 사용하여 디버그 정보 수집
IoT Edge 디바이스에서 로그를 수집해야 하는 경우 가장 편리한 방법은 support-bundle 명령을 사용하는 것입니다. 기본적으로 이 명령은 모듈, IoT Edge 보안 관리자 및 컨테이너 엔진 로그, iotedge check JSON 출력 및 기타 유용한 디버그 정보를 수집합니다. 쉽게 공유할 수 있도록 단일 파일로 압축합니다. support-bundle 명령은 release 1.0.9 이상에서 사용할 수 있습니다.
--since 플래그를 사용하여 support-bundle 명령을 실행하여 과거부터 로그를 가져올 기간을 지정합니다. 예를 들어 6h 마지막 6분 이후의 마지막 6일 6d 6m 이후의 로그를 가져옵니다. --help 플래그를 포함하여 전체 옵션 목록을 표시합니다.
sudo iotedge support-bundle --since 6h
기본적으로 support-bundle 명령은 명령이 호출되는 디렉터리에 support_bundle.zip이라는 zip 파일을 만듭니다. --output 플래그를 사용하여 출력에 대해 다른 경로 또는 파일 이름을 지정합니다.
명령에 대한 자세한 내용은 해당 도움말 정보를 확인하세요.
iotedge support-bundle --help
기본 제공되는 직접 메서드 호출 UploadSupportBundle을 사용하여 Azure Blob Storage에 대한 support-bundle 명령의 출력을 업로드할 수도 있습니다.
Warning
support-bundle 명령의 출력에는 호스트, 디바이스 및 모듈 이름, 모듈에 의해 기록된 정보 등이 포함될 수 있습니다. 공개 포럼의 출력을 공유하는 경우 이 점에 유의하세요.
런타임에서 수집된 메트릭 검토
IoT Edge 런타임 모듈은 IoT Edge 디바이스의 상태를 모니터링하고 이해하는 데 도움이 되는 메트릭을 생성합니다. 메트릭 수집기 모듈을 배포에 추가하여 이러한 메트릭 수집을 처리하고 더 쉽게 모니터링할 수 있도록 클라우드에 보냅니다.
자세한 내용은 메트릭 수집 및 전송을 참조하세요.
IoT Edge 버전 확인
이전 버전의 IoT Edge를 실행하는 경우 업그레이드하면 문제가 해결될 수 있습니다. iotedge check 도구는 IoT Edge 보안 디먼이 최신 버전인지 확인하지만, IoT Edge 허브 및 에이전트 모듈의 버전을 확인하지는 않습니다. 디바이스에서 런타임 모듈의 버전을 확인하려면 iotedge logs edgeAgent 및 iotedge logs edgeHub 명령을 사용합니다. 버전 번호는 모듈이 시작될 때 로그에서 선언됩니다.
디바이스를 업데이트하는 방법에 대한 지침은 IoT Edge 보안 디먼 및 런타임 업데이트를 참조하세요.
디바이스에 IoT Edge 설치 확인
edgeAgent 모듈 쌍을 모니터링하여 디바이스에 IoT Edge 설치를 확인할 수 있습니다.
최신 edgeAgent 모듈 쌍을 가져오려면 Azure Cloud Shell에서 다음 명령을 실행합니다.
az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>
이 명령은 모든 edgeAgent reported 속성을 출력합니다. 다음은 디바이스 상태를 모니터링하는 데 도움이 되는 몇 가지 유용한 항목입니다.
- 런타임 상태
- 런타임 시작 시간
- 런타임 마지막 종료 시간
- 런타임 다시 시작 횟수
IoT Edge 보안 관리자의 상태 및 해당 로그 확인
IoT Edge 보안 관리자는 시작 및 프로비저닝 디바이스에서 IoT Edge 시스템을 초기화하는 등의 작업을 담당합니다. IoT Edge를 시작하지 않는 경우 보안 관리자 로그에서 유용한 정보를 제공할 수 있습니다.
IoT Edge 시스템 서비스의 상태를 확인합니다.
sudo iotedge system statusIoT Edge 시스템 서비스의 로그를 확인합니다.
sudo iotedge system logs -- -f디버그 수준 로그를 사용하여 IoT Edge 시스템 서비스에 대한 자세한 로그를 확인합니다.
디버그 수준 로그를 사용하도록 설정합니다.
sudo iotedge system set-log-level debug sudo iotedge system restart디버깅 후 기본 정보 수준 로그로 다시 전환합니다.
sudo iotedge system set-log-level info sudo iotedge system restart
문제에 대한 컨테이너 로그 확인
IoT Edge 보안 디먼이 실행되면 컨테이너의 로그를 확인하여 문제를 검색합니다. 배포된 컨테이너부터 살펴본 후, IoT Edge 런타임을 구성하는 컨테이너(edgeAgent 및 edgeHub)를 살펴봅니다. IoT Edge 에이전트 로그는 일반적으로 각 컨테이너의 수명 주기에 대한 정보를 제공합니다. IoT Edge 허브 로그는 메시징 및 라우팅에 대한 정보를 제공합니다.
컨테이너 로그는 여러 위치에서 검색할 수 있습니다.
IoT Edge 디바이스에서 다음 명령을 실행하여 로그를 확인합니다.
iotedge logs <container name>Azure Portal에서 기본 제공 문제 해결 도구를 사용합니다. Azure Portal에서 IoT Edge 디바이스 모니터링 및 문제 해결
UploadModuleLogs 직접 메서드를 사용하여 모듈의 로그를 Azure Blob Storage에 업로드합니다.
컨테이너 로그 정리
기본적으로 Moby 컨테이너 엔진은 컨테이너 로그 크기 제한을 설정하지 않습니다. 시간이 지남에 따라 광범위한 로그로 인해 디바이스가 로그로 가득 차고 디스크 공간이 부족해질 수 있습니다. 컨테이너 로그가 커서 IoT Edge 디바이스 성능에 영향이 있는 경우 다음 명령을 사용하여 컨테이너와 관련 로그를 강제 제거합니다.
그래도 문제가 있으면 컨테이너 로그를 검사한 뒤 잠시 기다렸다가 이 단계를 수행합니다.
Warning
배달되지 않은 메시지 백로그가 있고 호스트 스토리지가 설정되지 않은 상태에서 edgeHub 컨테이너를 강제로 제거하면 배달되지 않은 메시지가 손실됩니다.
docker rm --force <container name>
진행 중인 로그 유지 관리 및 프로덕션 시나리오의 경우 기본 로깅 드라이버 설정을 참조하세요.
IoT Edge 허브를 따라 메시지 확인
IoT Edge 허브에 표시되는 메시지를 확인하고, 런타임 컨테이너의 자세한 로그에서 인사이트를 수집할 수 있습니다. 이러한 컨테이너에서 자세한 로그를 켜려면 배포 매니페스트에서 RuntimeLogLevel 환경 변수를 설정합니다.
IoT Edge 허브에 표시되는 메시지를 보려면 edgeHub 모듈에 대해 debug로 RuntimeLogLevel 환경 변수를 설정합니다.
edgeHub 및 edgeAgent 모듈에는 모두 이 런타임 로그 환경 변수가 있으며 기본값은 info로 설정됩니다. 이 환경 변수는 다음 값을 사용할 수 있습니다.
- fatal
- error
- 경고
- info
- 디버그
- verbose
IoT Hub 및 IoT 디바이스 간에 전송되는 메시지를 확인할 수도 있습니다. Visual Studio Code용 Azure IoT Hub 확장을 사용하여 이러한 메시지를 확인합니다. 자세한 내용은 Azure IoT로 개발할 때 사용할 수 있는 편리한 도구를 참조하세요.
컨테이너 다시 시작
로그 및 메시지에서 정보를 검토한 후에는 컨테이너를 다시 시작할 수 있습니다.
IoT Edge 디바이스에서 다음 명령을 사용하여 모듈을 다시 시작합니다.
iotedge restart <container name>
IoT Edge 런타임 컨테이너를 다시 시작합니다.
iotedge restart edgeAgent && iotedge restart edgeHub
Azure Portal에서 원격으로 모듈을 다시 시작할 수도 있습니다. 자세한 내용은 Azure Portal에서 IoT Edge 디바이스 모니터링 및 문제 해결을 참조하세요.
방화벽 및 포트 구성 규칙 확인
Azure IoT Edge를 사용하면 지원되는 IoT Hub 프로토콜을 사용하여 온-프레미스 서버에서 Azure 클라우드로 통신할 수 있습니다. 자세한 내용은 통신 프로토콜 선택을 참조하세요. 보안 향상된을 위해 Azure IoT Edge 및 Azure IoT Hub 간의 통신 채널은 항상 아웃바운드되도록 구성됩니다. 이 구성은 서비스 보조 통신 패턴을 기반으로 합니다. 그러면 탐색할 악의적인 엔터티에 대한 공격 노출 영역을 최소화합니다. 인바운드 통신은 Azure IoT Hub에서 메시지를 Azure IoT Edge 디바이스에 푸시해야 하는 특정 시나리오에만 필요합니다. 클라우드-디바이스 메시지는 보안 TLS 채널을 사용하여 보호되고 X.509 인증서 및 TPM 디바이스 모듈을 사용하여 추가로 보호될 수 있습니다. Azure IoT Edge 보안 관리자는 이 통신을 설정하는 방법을 관리합니다. IoT Edge 보안 관리자를 참조하세요.
IoT Edge는 Azure IoT Edge 런타임 및 배포된 모듈을 보호하기 위해 향상된 구성을 제공하지만, 기본 컴퓨터 및 네트워크 구성에 여전히 종속됩니다. 따라서 보안 에지-클라우드 통신을 위해 적절한 네트워크 및 방화벽 규칙을 설정해야 합니다. Azure IoT Edge 런타임이 호스트되는 기본 서버의 방화벽 규칙을 구성할 때 다음 표를 참조할 수 있습니다.
| 프로토콜 | Port | 수신 | 나가는 포트 | 지침 |
|---|---|---|---|---|
| MQTT | 8883 | BLOCKED(기본값) | BLOCKED(기본값) |
|
| AMQP | 5671 | BLOCKED(기본값) | OPEN(기본값) |
|
| HTTPS | 443 | BLOCKED(기본값) | OPEN(기본값) |
|
최후의 수단: 모든 컨테이너를 중지하고 다시 만듭니다.
경우에 따라 시스템은 기존 네트워킹 또는 운영 체제 제약 조건과 함께 작동하기 위해 상당한 특수 수정이 필요할 수 있습니다. 예를 들어, 시스템에 다른 데이터 디스크 탑재 및 프록시 설정이 필요할 수 있습니다. 이전 단계를 모두 시도했지만 여전히 컨테이너 오류가 발생하는 경우 Docker 시스템 캐시 또는 영구 네트워크 설정이 최신 다시 구성으로 최신 상태가 아닐 수 있습니다. 이 경우 마지막 수단 옵션은 docker prune을 사용하여 처음부터 깔끔하게 시작하는 것입니다.
다음 명령은 IoT Edge 시스템(따라서 모든 컨테이너)을 중지하고 docker prune에 대해 "all" 및 "volume" 옵션을 사용하여 모든 컨테이너와 볼륨을 제거합니다. 명령이 발급하는 경고를 검토하고 준비가 되면 y로 확인합니다.
sudo iotedge system stop
docker system prune --all --volumes
WARNING! This will remove:
- all stopped containers
- all networks not used by at least one container
- all volumes not used by at least one container
- all images without at least one container associated to them
- all build cache
Are you sure you want to continue? [y/N]
시스템을 다시 시작합니다. 안전을 위해 잠재적으로 남아 있는 구성을 적용하고 하나의 명령으로 시스템을 시작합니다.
sudo iotedge config apply
몇 분 정도 기다렸다가 다시 확인합니다.
sudo iotedge list
다음 단계
IoT Edge 플랫폼에서 버그를 찾았나요? 지속적인 제품 개선을 위해 문제를 제출하세요.
추가 질문이 있으면 지원 요청을 만들어 도움을 받으세요.