일반적인 Azure IoT Edge 문제에 대한 해결 방법

아티클
11/17/2022

적용 대상: IoT Edge 1.1

Important

IoT Edge 1.1 지원 종료일은 2022년 12월 13일이었습니다. 이 제품, 서비스, 기술 또는 API가 지원되는 방법에 대한 정보는 Microsoft 제품 수명 주기를 확인하세요. 최신 버전의 IoT Edge로 업데이트하는 방법에 대한 자세한 내용은 업데이트 IoT Edge를 참조하세요.

이 문서를 사용하여 IoT Edge 솔루션을 사용할 때 발생하는 일반적인 문제를 식별하고 확인합니다. IoT Edge 서비스에서 로그 및 오류를 발견하는 방법에 대한 자세한 내용은 IoT Edge 디바이스 문제 해결을 참조하세요.

프로비전 및 배포

IoT Edge 모듈이 성공적으로 배포된 후 디바이스에서 사라짐

증상

IoT Edge 서비스에 대해 모듈을 설정한 후 모듈이 성공적으로 배포되지만 몇 분 후 디바이스 및 Azure Portal의 디바이스 세부 정보에서 사라집니다. 정의된 것 이외의 다른 모듈이 디바이스에 표시될 수도 있습니다.

원인

자동 배포가 대상 디바이스를 선택하는 경우 단일 디바이스에 대해 모듈을 수동으로 설정하는 것보다 우선 적용됩니다. Azure Portal의 모듈 설정 기능 또는 Visual Studio Code의 단일 디바이스에 대한 배포 만들기 기능이 잠시 동안 적용됩니다. 정의한 모듈이 디바이스에서 시작되는 것을 확인할 수 있습니다. 그런 후 자동 배포가 우선 시작되면서 디바이스의 원하는 속성을 덮어씁니다.

솔루션

자동 배포 또는 개별 디바이스 배포 중에서 배포 메커니즘을 디바이스당 한 가지 유형만 사용해야 합니다. 한 디바이스를 대상으로 하는 자동 배포가 여럿인 경우 올바른 항목이 지정된 디바이스에 적용되도록 우선 순위 또는 대상 설명을 변경할 수 있습니다. 또한 자동 배포의 대상 설명과 더 이상 일치하지 않도록 디바이스 트윈을 업데이트할 수 있습니다.

자세한 내용은 단일 디바이스 또는 대규모 IoT Edge 자동 배포에 대한 이해를 참조하세요.

Windows에서 IoT Edge 런타임 로그를 가져올 수 없습니다.

증상

Windows에서 사용할 Get-WinEvent 때 EventLogException이 발생합니다.

원인

Get-WinEvent PowerShell 명령은 특정 ProviderName별로 로그를 찾기 위해 표시된 레지스트리 항목을 사용합니다.

솔루션

IoT Edge 디먼에 대한 레지스트리 항목을 설정합니다. 다음 콘텐츠를 사용하여 iotedge.reg 파일을 만들고, 파일을 두 번 클릭하거나 reg import iotedge.reg 명령을 사용하여 Windows 레지스트리로 가져옵니다.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\iotedged]
"CustomSource"=dword:00000001
"EventMessageFile"="C:\\ProgramData\\iotedge\\iotedged.exe"
"TypesSupported"=dword:00000007

DPS 클라이언트 오류

증상

IoT Edge가 failed to provision with IoT Hub, and no valid device backup was found dps client error. 오류 메시지와 함께 시작되지 않음

원인

그룹 등록은 IoT Edge 디바이스를 IoT Hub에 프로비전하는 데 사용됩니다. IoT Edge 디바이스가 다른 허브로 이동되었습니다. DPS에서 등록이 삭제됩니다. 새 허브에 대한 DPS에서 새 등록이 만들어집니다. 디바이스가 다시 프로비전되지 않습니다.

솔루션

DPS 자격 증명이 올바른지 확인합니다.
sudo iotedge apply config를 사용하여 구성을 적용합니다.
디바이스가 다시 프로비전되지 않은 경우 sudo iotedge system restart를 사용하여 디바이스를 다시 시작합니다.
디바이스가 다시 프로비전되지 않은 경우 sudo iotedge system reprovision을 사용하여 강제로 다시 프로비전합니다.

자동으로 다시 프로비전하려면 디바이스 구성 파일에서 dynamic_reprovisioning: true를 설정합니다. 이 플래그를 true로 설정하면 동적 다시 프로비전 기능이 옵트인됩니다. IoT Edge는 특정 오류에 대해 자체 IoT Hub 연결을 모니터링하여 디바이스가 클라우드에서 다시 프로비전된 것으로 보이는 상황을 검색합니다. IoT Edge는 모든 Edge 모듈 및 자체를 종료하여 응답합니다. 다음에 디먼이 시작되면 새 IoT Hub 프로비전 정보를 수신하기 위해 Azure로 이 디바이스를 다시 프로비전하려고 시도합니다.

외부 프로비저닝을 사용하는 경우 디먼은 종료하기 전에 외부 프로비전 엔드포인트에 다시 프로비전 이벤트에 대해 알립니다. 자세한 내용은 IoT Hub 디바이스 다시 프로비저닝 개념을 참조하세요.

IoT Edge 런타임

IoT Edge 에이전트가 1분 후에 중지됨

증상

edgeAgent 모듈이 시작되고 1분 정도 성공적으로 실행되고 나서 중지됩니다. 로그에는 IoT Edge 에이전트가 AMQP를 통해 IoT 허브에 연결하려고 시도한 후 WebSocket을 통해 AMQP를 사용하여 연결하려고 시도한다고 표시됩니다. 이것이 실패했을 때 IoT Edge 에이전트가 종료됩니다.

예제 edgeAgent 로그:

2017-11-28 18:46:19 [INF] - Starting module management agent.
2017-11-28 18:46:19 [INF] - Version - 1.0.7516610 (03c94f85d0833a861a43c669842f0817924911d5)
2017-11-28 18:46:19 [INF] - Edge agent attempting to connect to IoT Hub via AMQP...
2017-11-28 18:46:49 [INF] - Edge agent attempting to connect to IoT Hub via AMQP over WebSocket...

원인

호스트 네트워크의 네트워킹 구성 때문에 IoT Edge 에이전트가 네트워크에 연결하지 못합니다. 에이전트는 AMQP(포트 5671)를 통해 먼저 연결을 시도합니다. 이 연결이 실패하면 WebSockets(포트 443)을 시도합니다.

IoT Edge 런타임은 각 모듈이 통신할 네트워크를 설정합니다. Linux에서 이 네트워크는 브리지 네트워크입니다. Windows에서는 NAT를 사용합니다. 이 문제는 NAT 네트워크를 사용하는 Windows 컨테이너를 사용하는 Windows 디바이스에서 좀 더 자주 발생합니다.

솔루션

이 브리지/NAT 네트워크에 할당된 IP 주소가 인터넷에 연결되는 경로가 있는지 확인합니다. 경우에 따라 호스트의 VPN 구성은 IoT Edge 네트워크를 재정의합니다.

Edge 에이전트 모듈이 ‘빈 구성 파일’을 보고하고 모듈이 디바이스에서 시작되지 않음

증상

디바이스가 배포에 정의된 모듈을 시작하는 데 문제가 있습니다. edgeAgent만 실행 중이지만 지속적으로 '빈 구성 파일...'을 보고합니다.

원인

기본적으로 IoT Edge는 자신의 격리된 컨테이너 네트워크에서 모듈을 시작합니다. 디바이스가 이 비공개 네트워크 내에서 DNS 이름을 확인하는 데 문제가 발생할 수 있습니다.

솔루션

옵션 1: 컨테이너 엔진 설정에서 DNS 서버 설정

컨테이너 엔진 설정에서 해당 환경에 대해 DNS 서버를 지정합니다. 이것은 엔진에서 시작되는 모든 컨테이너 모듈에 적용됩니다. daemon.json이라는 파일을 만든 다음 사용할 DNS 서버를 지정합니다. 예시:

{
    "dns": ["1.1.1.1"]
}

이 DNS 서버는 공개적으로 액세스할 수 있는 DNS 서비스로 설정됩니다. 그러나 회사 네트워크와 같은 일부 네트워크에는 자체 DNS 서버가 설치되어 있으며 공용 DNS 서버에 대한 액세스를 허용하지 않습니다. 따라서 에지 디바이스가 공용 DNS 서버에 액세스할 수 없는 경우 액세스 가능한 DNS 서버 주소로 바꿉니다.

플랫폼에 적합한 위치에 배치 daemon.json 합니다.

플랫폼	위치
Linux	`/etc/docker`
Windows 컨테이너가 포함된 Windows 호스트	`C:\ProgramData\iotedge-moby\config`

위치에 이미 파일이 포함된 daemon.json 경우 dns 키를 추가하고 파일을 저장합니다.

업데이트를 적용하기 위해 컨테이너 엔진을 다시 시작합니다.

플랫폼	명령
Linux	`sudo systemctl restart docker`
Windows(관리자 PowerShell)	`Restart-Service iotedge-moby -Force`

옵션 2: 모듈별로 IoT Edge 배포에서 DNS 서버 설정

IoT Edge 배포에서 각 모듈의 createOptions에 대해 DNS 서버를 설정할 수 있습니다. 예시:

"createOptions": {
  "HostConfig": {
    "Dns": [
      "x.x.x.x"
    ]
  }
}

Warning

이 방법을 사용하고 잘못된 DNS 주소를 지정하면 edgeAgent에서 IoT Hub와의 연결이 끊어지고 문제를 해결하기 위해 새 배포를 받을 수 없습니다. 이 문제를 해결하기 위해 IoT Edge 런타임을 다시 설치할 수 있습니다. IoT Edge의 새 인스턴스를 설치하기 전에 이전 설치에서 모든 edgeAgent 컨테이너를 제거해야 합니다.

edgeAgent 및 edgeHub 모듈에 대해서도 이 구성을 설정해야 합니다.

IoT Edge 에이전트가 모듈의 이미지에 액세스할 수 없음(403)

증상

컨테이너가 실행되지 못하고 edgeAgent 로그에 403 오류가 보고됩니다.

원인

IoT Edge 에이전트가 모듈의 모듈 이미지에 액세스할 수 있는 권한이 없습니다.

솔루션

디바이스 배포 매니페스트에서 컨테이너 레지스트리 자격 증명이 올바른지 확인합니다.

IoT Edge 허브 시작 실패

증상

edgeHub 모듈이 시작되지 못합니다. 로그에 다음 오류 중 하나와 비슷한 메시지가 표시될 수 있습니다.

One or more errors occurred.
(Docker API responded with status code=InternalServerError, response=
{\"message\":\"driver failed programming external connectivity on endpoint edgeHub (6a82e5e994bab5187939049684fb64efe07606d2bb8a4cc5655b2a9bad5f8c80):
Error starting userland proxy: Bind for 0.0.0.0:443 failed: port is already allocated\"}\n)

또는

info: edgelet_docker::runtime -- Starting module edgeHub...
warn: edgelet_utils::logging -- Could not start module edgeHub
warn: edgelet_utils::logging --     caused by: failed to create endpoint edgeHub on network nat: hnsCall failed in Win32:  
        The process cannot access the file because it is being used by another process. (0x20)

원인

edgeHub 모듈이 바인딩하려고 시도 중인 포트를 호스트 컴퓨터에 있는 다른 일부 프로세스가 바인딩했습니다. IoT Edge 허브는 게이트웨이 시나리오에서 사용하기 위해 포트 443, 5671 및 8883을 매핑합니다. 다른 프로세스가 이러한 포트 중 하나를 이미 바인딩했으면 모듈이 시작되지 못합니다.

솔루션

이 문제는 두 가지 방법으로 해결할 수 있습니다.

IoT Edge 디바이스가 게이트웨이 디바이스로 작동하는 경우 포트 443, 5671 또는 8883을 사용 중인 프로세스를 찾아서 중지해야 합니다. 포트 443 오류는 일반적으로 다른 프로세스가 웹 서버임을 의미합니다.

IoT Edge 디바이스를 게이트웨이로 사용할 필요가 없으면 edgeHub의 모듈 만들기 옵션에서 포트 바인딩을 제거할 수 있습니다. Azure Portal에서 또는 deployment.json 파일에서 만들기 옵션을 변경할 수 있습니다.

Azure Portal에서 다음을 수행합니다.

IoT Hub로 이동하여 디바이스 관리 메뉴에서 디바이스를 선택합니다.
업데이트하려는 IoT Edge 디바이스를 선택합니다.
모듈 설정을 선택합니다.
런타임 설정을 선택합니다.
Edge Hub 모듈 설정의 [옵션 만들기] 텍스트 상자에서 모든 항목을 삭제합니다.
변경 내용을 저장하고 배포를 만듭니다.

deployment.json 파일에서 다음을 수행합니다.

IoT Edge 디바이스에 적용한 deployment.json 파일을 엽니다.

edgeAgent의 원하는 속성 섹션에서 edgeHub 설정을 찾습니다.

"edgeHub": {
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
        "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
    },
    "type": "docker",
    "status": "running",
    "restartPolicy": "always"
}

createOptions 줄을 제거하고 그 앞의 image 줄의 끝에 있는 후행 쉼표를 제거합니다.

"edgeHub": {
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1"
    },
    "type": "docker",
    "status": "running",
    "restartPolicy": "always"
}

파일을 저장하고 IoT Edge 디바이스에 다시 적용합니다.

404 오류로 IoT Edge 모듈이 edgeHub에 메시지를 보내지 못함

증상

사용자 지정 IoT Edge 모듈이 404 Module not found 오류로 인해 IoT Edge 허브에 메시지를 보내지 못합니다. IoT Edge 런타임은 로그에 다음 메시지를 출력합니다.

Error: Time:Thu Jun  4 19:44:58 2018 File:/usr/sdk/src/c/provisioning_client/adapters/hsm_client_http_edge.c Func:on_edge_hsm_http_recv Line:364 executing HTTP request fails, status=404, response_buffer={"message":"Module not found"}u, 04 )

원인

IoT Edge 런타임은 보안상의 이유로 edgeHub에 연결하는 모든 모듈에 대해 프로세스 확인을 적용합니다. 이 디먼은 모듈이 전송하는 모든 메시지가 해당 모듈의 기본 프로세스 ID에서 온 것인지 확인합니다. 메시지가 처음에 설정한 것과는 다른 프로세스 ID의 모듈에서 전송될 경우 404 오류 메시지가 표시되며 거부됩니다.

솔루션

1.0.7 버전부터는 모든 모듈 프로세스에 연결 권한이 부여됩니다. 자세한 내용은 1.0.7 릴리스 변경 로그를 참조하세요.

1.0.7로 업그레이드할 수 없으면 다음 단계를 완료합니다. 사용자 지정 IoT Edge 모듈이 edgeHub에 메시지를 보내는 데 항상 동일한 프로세스 ID를 사용하는지 확인합니다. 예를 들어 Docker 파일에서 CMD 명령 대신 ENTRYPOINT 명령을 사용합니다. CMD 명령은 모듈에 대한 프로세스 ID 하나와 기본 프로그램에서 실행되는 bash 명령에 대한 또 다른 프로세스 ID로 이어지지만 ENTRYPOINT 명령은 단일 프로세스 ID로 이어집니다.

작은 디바이스에서의 안정성 문제

증상

특히 게이트웨이로 사용될 때 Raspberry Pi와 같은 리소스가 제한된 디바이스에서 안정성 문제가 발생할 수 있습니다. 증상에는 IoT Edge 허브 모듈의 메모리 부족 예외, 다운스트림 디바이스의 연결 실패 또는 몇 시간 후 디바이스의 원격 분석 메시지 전송 실패가 포함됩니다.

원인

IoT Edge 런타임에 속하는 IoT Edge 허브는 기본적으로 성능에 최적화되어 있으며 많은 양의 메모리를 할당하려고 합니다. 이 최적화는 제한된 에지 디바이스에 대해 이상적이지 않으며 안정성 문제를 유발할 수 있습니다.

솔루션

IoT Edge 허브의 경우 OptimizeForPerformance 환경 변수를 false로 설정합니다. 환경 변수를 설정하는 방법은 두 가지입니다.

Azure Portal에서 다음을 수행합니다.

IoT 허브에서 IoT Edge 디바이스를 선택하고 디바이스 세부 정보 페이지에서 모듈 선택>런타임 설정을 선택합니다. False로 설정된 OptimizeForPerformance라는 IoT Edge 허브 모듈에 대한 환경 변수를 만듭니다.

OptimizeForPerformance를 false로 설정

배포 매니페스트의 경우:

"edgeHub": {
  "type": "docker",
  "settings": {
    "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
    "createOptions": <snipped>
  },
  "env": {
    "OptimizeForPerformance": {
      "value": "false"
    }
  },

보안 디먼을 성공적으로 시작할 수 없습니다.

증상

보안 디먼이 시작되지 않고 모듈 컨테이너가 만들어지지 않습니다. edgeAgent, edgeHub 및 기타 사용자 지정 모듈은 IoT Edge 서비스에서 시작되지 않습니다. aziot-edged 로그에 다음 오류가 표시됩니다.

디먼을 성공적으로 시작할 수 없습니다. 관리 서비스를 시작할 수 없습니다.

원인: /var/run/iotedge/mgmt.sock 경로에 오류가 발생했습니다.

원인: 권한 거부됨(os 오류 13)

원인

CentOS 7을 제외한 모든 Linux 배포판의 경우 IoT Edge의 기본 구성은 systemd 소켓 활성화를 사용하는 것입니다. 소켓 활성화를 사용하지 않도록 구성 파일을 변경하고 URL을 /var/run/iotedge/*.sock로 남겨두면 iotedge 사용자가 /var/run/iotedge에 쓸 수 없으므로 소켓 자체를 잠금 해제하고 탑재할 수 없기 때문에 권한 오류가 발생합니다.

솔루션

소켓 활성화가 지원되는 배포판에서는 소켓 활성화를 사용하지 않도록 설정할 필요가 없습니다. 그러나 소켓 활성화를 전혀 사용하지 않으려면 소켓을 /var/lib/iotedge/에 두세요.

systemctl disable iotedge.socket iotedge.mgmt.socket을 실행하여 소켓 장치를 사용하지 않도록 설정하여 systemd가 소켓 장치를 불필요하게 시작하지 않도록 합니다.
connect 및 listen 섹션 모두에서 /var/lib/iotedge/*.sock를 사용하도록 iotedge 구성을 변경합니다.
모듈이 이미 있는 경우 이전 /var/run/iotedge/*.sock 탑재가 있으므로 docker rm -f합니다.

OS 불일치로 인해 모듈을 시작할 수 없습니다.

증상

EdgeHub 모듈이 IoT Edge 버전 1.1에서 시작되지 않습니다.

원인

Windows 모듈이 호스트의 Windows 버전과 호환되지 않는 Windows 버전을 사용합니다. 모듈 이미지의 기본 계층으로 IoT Edge Windows 버전 1809 빌드 17763이 필요하지만 다른 버전이 사용 중입니다.

솔루션

호스트 및 컨테이너 이미지 불일치 문제 해결에서 다양한 Windows 운영 체제의 버전을 확인합니다. 운영 체제가 다른 경우 IoT Edge Windows 버전 1809 빌드 17763으로 업데이트하고 해당 모듈에 사용되는 Docker 이미지를 다시 빌드합니다.

네트워킹

IoT Edge 보안 디먼이 유효하지 않은 호스트 이름으로 실패합니다.

증상

IoT Edge 보안 관리자 로그를 확인하려는 시도가 실패하고 다음 메시지가 출력됩니다.

Error parsing user input data: invalid hostname. Hostname cannot be empty or greater than 64 characters

원인

IoT Edge 런타임은 64자 미만인 호스트 이름만을 지원할 수 있습니다. 물리적 머신은 일반적으로 긴 호스트 이름을 사용하지 않지만 문제는 가상 머신에서 자주 발생합니다. 특히 Azure에서 호스팅되는 Windows 가상 머신에 자동으로 생성된 호스트 이름이 너무 긴 경향이 있습니다.

솔루션

이 오류를 표시하는 경우 가상 머신의 DNS 이름을 구성한 다음, 설정 명령에서 DNS 이름을 호스트 이름으로 설정하여 해결할 수 있습니다.

Azure Portal에서 가상 머신의 개요 페이지로 이동합니다.
DNS 이름에서 구성을 선택합니다. 가상 머신에 DNS 이름이 이미 구성되어 있으면 새 이름을 구성할 필요가 없습니다.
DNS 이름 레이블에 대한 값을 입력하고 저장을 선택합니다.
새 DNS 이름을 복사합니다.이 형식은 <DNSnamelabel>.<vmlocation>.cloudapp.azure.com이어야 합니다.
가상 머신 내에서 다음 명령을 사용하여 DNS 이름으로 IoT Edge 런타임을 설정합니다.
- Linux:
```
sudo nano /etc/iotedge/config.yaml
```
- Windows:
```
notepad C:\ProgramData\iotedge\config.yaml
```

IoT Edge 모듈에서 연결 오류 보고

증상

런타임 모듈을 포함하여 클라우드 서비스에 직접 연결하는 IoT Edge 모듈은 예상대로 작동을 중지하고 연결 또는 네트워킹 실패에 대한 오류를 반환합니다.

원인

컨테이너는 클라우드 서비스와 통신할 수 있도록 인터넷에 연결하기 위해 IP 패킷 전달에 의존합니다. IP 패킷 전달은 Docker에서 기본적으로 사용하도록 설정되지만 사용하지 않도록 설정되면 클라우드 서비스에 연결하는 모든 모듈이 예상대로 작동하지 않습니다. 자세한 내용은 Docker 설명서의 컨테이너 통신 이해를 참조하세요.

솔루션

다음 단계에서 IP 패킷 전달을 사용하도록 설정합니다.

Windows:

실행 애플리케이션을 엽니다.
텍스트 상자에 regedit을 입력하고 확인을 선택합니다.
레지스트리 편집기 창에서 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters로 이동합니다.
IPEnableRouter 매개 변수를 찾습니다.
1. 매개 변수가 있으면 매개 변수 값을 1로 설정합니다.
2. 매개 변수가 존재하지 않는 경우 다음 설정을 사용하여 새 매개 변수로 추가합니다.
  
  설정 값
  
  속성 IPEnableRouter
  
  Type REG_DWORD
  
  값 1
레지스트리 편집기 창을 닫습니다.
변경 내용을 적용하려면 시스템을 다시 시작합니다.

설정	값
속성	IPEnableRouter
Type	REG_DWORD
값	1

Linux:

sysctl.conf 파일을 엽니다.
```
sudo nano /etc/sysctl.conf
```
파일에 다음 줄을 추가합니다.
```
net.ipv4.ip_forward=1
```
파일을 저장 후 닫습니다.
변경 내용을 적용하려면 네트워크 서비스와 Docker 서비스를 다시 시작합니다.

다음 단계

IoT Edge 플랫폼에서 버그를 찾았나요? 지속적인 제품 개선을 위해 문제를 제출하세요.

추가 질문이 있으면 지원 요청을 만들어 도움을 받으세요.

다음을 통해 공유