적용 대상:
IoT Edge 1.5
중요합니다
IoT Edge 1.5 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일부터 수명이 종료됩니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.
IoT Edge 디바이스는 HTTPS 요청을 전송하여 IoT Hub와 통신합니다. 디바이스가 프록시 서버를 사용하는 네트워크에 연결하는 경우 서버를 통해 통신하도록 IoT Edge 런타임을 구성합니다. 프록시 서버는 IoT Edge 허브를 통해 라우팅되지 않는 HTTP 또는 HTTPS 요청을 만드는 경우 개별 IoT Edge 모듈에도 영향을 줄 수 있습니다.
이 문서에서는 프록시 서버 뒤에서 IoT Edge 디바이스를 구성하고 관리하는 네 가지 단계를 설명합니다.
-
IoT Edge 설치 스크립트는 인터넷에서 패키지 및 파일을 끌어오므로 디바이스는 프록시 서버를 통해 통신하여 해당 요청을 만듭니다. Windows 디바이스의 경우 설치 스크립트는 오프라인 설치 옵션도 제공합니다.
이 단계는 IoT Edge 디바이스를 처음 설정할 때 구성하는 일회성 프로세스입니다. IoT Edge 런타임을 업데이트할 때도 이와 동일한 연결이 필요합니다.
-
IoT Edge는 IoT Hub와의 통신을 처리합니다. 컨테이너 런타임은 컨테이너를 관리하고 컨테이너 레지스트리와 통신합니다. 이러한 구성 요소는 둘 다 프록시 서버를 통해 웹 요청을 수행해야 합니다.
이 단계는 IoT Edge 디바이스를 처음 설정할 때 구성하는 일회성 프로세스입니다.
디바이스에서 구성 파일의 IoT Edge 에이전트 속성 구성
IoT Edge 디먼은 처음에 edgeAgent 모듈을 시작합니다. 그런 다음, edgeAgent 모듈은 IoT Hub에서 배포 매니페스트를 검색하고 다른 모든 모듈을 시작합니다. IoT Edge 에이전트가 IoT Hub에 초기 연결을 만들도록 디바이스에서 edgeAgent 모듈 환경 변수를 수동으로 구성합니다. 초기 연결 후 edgeAgent 모듈을 원격으로 구성할 수 있습니다.
이 단계는 IoT Edge 디바이스를 처음 설정할 때 구성하는 일회성 프로세스입니다.
이후 모든 모듈 배포의 경우 프록시를 통해 통신하는 모든 모듈에 대해 환경 변수 설정
프록시 서버를 통해 IoT Edge 디바이스를 설정하고 IoT Hub에 연결한 후 이후의 모든 모듈 배포에서 연결을 유지합니다.
이 단계는 모든 새 모듈 또는 배포 업데이트가 프록시 서버를 통해 통신하는 디바이스 기능을 유지 관리하도록 원격으로 수행되는 지속적인 프로세스입니다.
프록시 URL 파악
이 문서의 단계를 시작하기 전에 프록시 URL을 알아두십시오.
프록시 URL은 protocol://proxy_host:proxy_port 형식을 사용합니다.
프로토콜은 HTTP 또는 HTTPS입니다. Docker 디먼은 컨테이너 레지스트리 설정에 따라 두 프로토콜 중 하나를 사용할 수 있지만 IoT Edge 디먼 및 런타임 컨테이너는 항상 HTTP를 사용하여 프록시에 연결합니다.
proxy_host 프록시 서버의 주소입니다. 프록시 서버에 인증이 필요한 경우 사용자:암호@proxy_host 형식으로 프록시 호스트의 일부로 자격 증명을 제공합니다.
proxy_port 프록시가 트래픽에 응답하는 네트워크 포트입니다.
프록시를 통해 IoT Edge 설치
IoT Edge 디바이스가 Windows 또는 Linux에서 실행되는지 여부에 관계없이 프록시 서버를 통해 설치 패키지에 액세스합니다. 운영 체제에 따라 프록시 서버를 통해 IoT Edge 런타임을 설치하는 단계를 수행합니다.
Linux 디바이스
Linux 디바이스에 IoT Edge 런타임을 설치하는 경우 프록시 서버를 사용하여 설치 패키지에 액세스하도록 패키지 관리자를 설정합니다. 예를 들어 http-proxy를 사용하도록 apt-get을 설정합니다. 패키지 관리자를 설정한 후 Azure IoT Edge 런타임 설치의 지침을 따릅니다.
IoT Edge for Linux on Windows를 사용하는 Windows 디바이스
Windows에서 Linux용 IoT Edge를 사용하여 IoT Edge 런타임을 설치하는 경우 IoT Edge 런타임은 기본적으로 Linux 가상 머신에 설치됩니다. 다른 단계를 설치하거나 업데이트할 필요는 없습니다.
Windows 컨테이너를 사용하는 Windows 디바이스
Windows 디바이스에서 IoT Edge 런타임을 설치하는 경우 프록시 서버를 두 번 거쳐야 합니다. 첫 번째 연결은 설치 관리자 스크립트 파일을 다운로드하고 두 번째 연결은 설치하는 동안 필요한 구성 요소를 다운로드합니다. Windows 설정에서 프록시 정보를 구성하거나 PowerShell 명령에 프록시 정보를 직접 포함할 수 있습니다.
다음 단계에서는 인수를 사용하여 Windows 설치의 예를 보여 줍니다 -proxy .
Invoke-WebRequest 명령에는 설치 프로그램 스크립트에 액세스하려면 프록시 정보가 필요합니다. 그런 다음, Deploy-IoTEdge 명령에는 설치 파일을 다운로드하려면 프록시 정보가 필요합니다.
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>Initialize-IoTEdge 명령은 프록시 서버를 거칠 필요가 없으므로 두 번째 단계에는 Invoke-WebRequest를 위한 프록시 정보만 필요합니다.
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
프록시 서버 자격 증명이 복잡하고 URL에 포함될 수 없는 경우 내-ProxyCredential의 매개 변수를 -InvokeWebRequestParameters 사용합니다. 예를 들면 다음과 같습니다.
$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }
프록시 매개 변수에 대한 자세한 내용은 Invoke-WebRequest를 참조하세요.
IoT Edge 및 Moby 구성
IoT Edge는 IoT Edge 디바이스에서 실행되는 두 개의 디먼을 사용합니다. Moby 디먼은 컨테이너 레지스트리에서 컨테이너 이미지를 가져옵니다. IoT Edge 디먼은 IoT Hub와 통신합니다.
진행 중인 디바이스 기능에 프록시 서버를 사용하도록 Moby 및 IoT Edge 디먼을 모두 구성합니다. 초기 설정 중에 IoT Edge 디바이스에서 이 단계를 수행합니다.
Moby 디먼
Moby는 Docker를 기반으로 하므로 Docker 설명서를 참조하여 환경 변수를 사용하여 Moby 디먼을 구성합니다. DockerHub 및 Azure Container Registries를 포함한 대부분의 컨테이너 레지스트리는 HTTPS 요청을 지원하므로 HTTPS_PROXY 매개 변수를 설정합니다. TLS(전송 계층 보안)를 지원하지 않는 레지스트리에서 이미지를 끌어오는 경우에는 HTTP_PROXY 매개 변수를 설정해야 합니다.
IoT Edge 디바이스 운영 체제에 적용되는 문서를 선택합니다.
- Linux에서 Docker 디먼 구성 Linux 디바이스에서는 Moby 디먼을 여전히 Docker라고 합니다.
- Windows에서 Docker 디먼 구성 Windows 디바이스의 Moby 디먼을 iotedge-moby라고 합니다. Windows 디바이스에서 Docker Desktop 및 Moby를 둘 다 병렬로 실행할 수 있으므로 이름은 서로 다릅니다.
IoT Edge 디먼
IoT Edge 디먼은 Moby 디먼과 유사합니다. 사용 중인 운영 체제에 따라 다음 단계를 수행하여 서비스에 대한 환경 변수를 설정합니다.
IoT Edge 디먼은 항상 HTTPS를 사용하여 IoT Hub에 요청을 보냅니다.
리눅스
터미널에서 편집기를 열어 IoT Edge 디먼을 구성합니다.
sudo systemctl edit aziot-edged
아래 텍스트를 입력합니다. <proxy URL>은 실제 프록시 서버 주소와 포트로 바꾸세요. 그런 다음 입력 내용을 저장하고 편집기를 종료합니다.
[Service]
Environment="https_proxy=<proxy URL>"
버전 1.2부터 IoT Edge는 IoT ID 서비스를 사용하여 IoT Hub 또는 IoT Hub Device Provisioning Service를 통해 디바이스 프로비저닝을 처리합니다. 터미널에서 편집기를 열어 IoT ID 서비스 디먼을 구성합니다.
sudo systemctl edit aziot-identityd
아래 텍스트를 입력합니다. <proxy URL>은 실제 프록시 서버 주소와 포트로 바꾸세요. 그런 다음 입력 내용을 저장하고 편집기를 종료합니다.
[Service]
Environment="https_proxy=<proxy URL>"
서비스 관리자를 새로 고쳐서 새 구성을 선택합니다.
sudo systemctl daemon-reload
IoT Edge 시스템 서비스를 다시 시작하여 두 디먼에 변경 내용을 적용합니다.
sudo iotedge system restart
환경 변수 및 새 구성이 있는지 확인합니다.
systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd
IoT Edge for Linux on Windows를 사용하는 Windows
Windows 가상 머신에서 Linux용 IoT Edge에 로그인합니다.
Connect-EflowVm
이 문서의 Linux 섹션과 동일한 단계를 수행하여 IoT Edge 디먼을 구성합니다.
Windows 컨테이너를 사용하는 Windows
관리자 권한으로 PowerShell 창을 연 후에 다음 명령을 실행해 새 환경 변수를 사용하여 레지스트리를 편집합니다. <proxy url>은 실제 프록시 서버 주소와 포트로 바꾸세요.
reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>
IoT Edge를 다시 시작하여 변경 내용을 적용합니다.
Restart-Service iotedge
IoT Edge 에이전트 구성
IoT Edge 에이전트는 모든 IoT Edge 디바이스에서 처음으로 시작되는 모듈로, 이 모듈에서는 IoT Edge 구성 파일의 정보에 따라 처음으로 시작됩니다. 그런 다음, IoT Edge 에이전트는 IoT 허브에 연결하여 배포 매니페스트를 검색합니다. 매니페스트는 디바이스가 배포해야 하는 다른 모듈을 선언합니다.
이 단계는 초기 디바이스 설정 중에 IoT Edge 디바이스에서 한 번 수행됩니다.
IoT Edge 디바이스에서 구성 파일
/etc/aziot/config.toml을 엽니다. 관리 권한이 있어야 구성 파일에 액세스할 수 있습니다. Linux 시스템에서는 원하는 텍스트 편집기에서 파일을 열기 전에sudo명령을 사용합니다.구성 파일에서 시작 시 사용할 edgeAgent 모듈의 모든 구성 정보가 포함된
[agent]섹션을 찾습니다. 섹션에[agent]메모가 없는지 확인합니다.[agent]섹션이 없으면config.toml에 추가합니다. IoT Edge 에이전트 정의에는 환경 변수를 추가할 수 있는[agent.env]하위 섹션이 포함됩니다.환경 변수 섹션에 https_proxy 매개 변수를 추가하고 프록시 URL을 해당 값으로 설정합니다.
[agent] name = "edgeAgent" type = "docker" [agent.config] image = "mcr.microsoft.com/azureiotedge-agent:1.5" [agent.env] # "RuntimeLogLevel" = "debug" # "UpstreamProtocol" = "AmqpWs" "https_proxy" = "<proxy URL>"IoT Edge 런타임은 기본적으로 AMQP를 사용하여 IoT Hub와 통신합니다. 그런데 일부 프록시 서버는 AMQP 포트를 차단합니다. 이 경우에는 WebSocket을 통해 AMQP를 사용하도록 edgeAgent도 구성해야 합니다. 매개 변수에서 주석을 제거합니다
UpstreamProtocol.[agent.config] image = "mcr.microsoft.com/azureiotedge-agent:1.5" [agent.env] # "RuntimeLogLevel" = "debug" "UpstreamProtocol" = "AmqpWs" "https_proxy" = "<proxy URL>"환경 변수 섹션에 https_proxy 매개 변수를 추가하고 프록시 URL을 해당 값으로 설정합니다.
[agent] name = "edgeAgent" type = "docker" [agent.config] image = "mcr.microsoft.com/azureiotedge-agent:1.5" [agent.env] # "RuntimeLogLevel" = "debug" # "UpstreamProtocol" = "AmqpWs" "https_proxy" = "<proxy URL>"IoT Edge 런타임은 기본적으로 AMQP를 사용하여 IoT Hub와 통신합니다. 그런데 일부 프록시 서버는 AMQP 포트를 차단합니다. 이 경우에는 WebSocket을 통해 AMQP를 사용하도록 edgeAgent도 구성해야 합니다.
UpstreamProtocol매개 변수의 주석 처리를 제거합니다.[agent.config] image = "mcr.microsoft.com/azureiotedge-agent:1.5" [agent.env] # "RuntimeLogLevel" = "debug" "UpstreamProtocol" = "AmqpWs" "https_proxy" = "<proxy URL>"변경 내용을 저장하고 편집기를 닫습니다. 변경 내용을 적용합니다.
sudo iotedge config applydocker inspect edgeAgent에서 프록시 설정이 적용되는지Env섹션에서 확인하십시오. 섹션이 없으면 컨테이너를 다시 만들어야 합니다.sudo docker rm -f edgeAgentIoT Edge 런타임은 1분 내에
edgeAgent을 다시 생성합니다.edgeAgent컨테이너가 다시 실행되면docker inspect edgeAgent명령을 사용하여 프록시 설정이 구성 파일과 일치하는지 확인합니다.
배포 매니페스트 구성
프록시 서버에서 작동하도록 IoT Edge 디바이스를 구성한 후 향후 배포 매니페스트에서 HTTPS_PROXY 환경 변수를 선언합니다. Azure Portal 마법사를 사용하거나 배포 매니페스트 JSON 파일을 편집하여 배포 매니페스트를 편집할 수 있습니다.
IoT Hub와의 연결을 유지하도록 프록시 서버를 통해 통신하도록 항상 두 런타임 모듈인 edgeAgent 및 edgeHub를 구성합니다. edgeAgent 모듈에서 프록시 정보를 제거하는 경우 연결을 다시 구성하는 유일한 방법은 이전 섹션에 설명된 대로 디바이스에서 구성 파일을 편집하는 것입니다.
edgeAgent 및 edgeHub 모듈 외에도 다른 모듈에 프록시 구성이 필요할 수 있습니다. Blob Storage와 같은 IoT Hub 외에 Azure 리소스에 액세스하는 모듈은 배포 매니페스트 파일에서 HTTPS_PROXY 변수를 지정해야 합니다.
이 절차는 IoT Edge 디바이스의 수명 내내 적용됩니다.
Azure Portal
모듈 설정 마법사를 사용하여 IoT Edge 디바이스의 배포를 만들 때 모든 모듈에는 프록시 서버 연결을 구성할 수 있는 환경 변수 섹션에 있습니다.
IoT Edge 에이전트 및 IoT Edge 허브 모듈을 구성하려면 마법사의 첫 단계에서 런타임 설정을 선택합니다.
https_proxy 환경 변수를 IoT Edge 에이전트 및 IoT Edge 허브 모듈 런타임 설정 정의 모두에 추가합니다. IoT Edge 디바이스의 구성 파일에 UpstreamProtocol 환경 변수를 포함하는 경우 IoT Edge 에이전트 모듈 정의에도 추가합니다.
배포 매니페스트에 추가하는 기타 모든 모듈은 같은 패턴을 따릅니다. 적용을 선택하여 변경 내용을 저장합니다.
JSON 배포 매니페스트 파일
Visual Studio Code에서 템플릿을 사용하거나 JSON 파일을 직접 만들어 IoT Edge 디바이스용 배포를 만든 경우에는 각 모듈 정의에 환경 변수를 직접 추가할 수 있습니다. Azure Portal에서 추가하지 않은 경우 여기에서 JSON 매니페스트 파일에 추가합니다. 값으로 대체 <proxy URL> 합니다.
다음 JSON 형식을 사용합니다.
"env": {
"https_proxy": {
"value": "<proxy URL>"
}
}
환경 변수가 포함된 모듈 정의는 다음 edgeHub 예제와 같습니다.
"edgeHub": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.5",
"createOptions": "{}"
},
"env": {
"https_proxy": {
"value": "http://proxy.example.com:3128"
}
},
"status": "running",
"restartPolicy": "always"
}
IoT Edge 디바이스의 config.yaml 파일에 UpstreamProtocol 환경 변수를 포함한 경우에는 IoT Edge 에이전트 모듈 정의에도 해당 환경 변수를 포함합니다.
"env": {
"https_proxy": {
"value": "<proxy URL>"
},
"UpstreamProtocol": {
"value": "AmqpWs"
}
}
트래픽을 검사하는 프록시 작업
Zscaler와 같은 일부 프록시는 TLS 암호화 트래픽을 검사할 수 있습니다. TLS 트래픽 검사 중에 프록시에서 반환된 인증서는 대상 서버의 인증서가 아니라 프록시의 루트 인증서로 서명된 인증서입니다. 기본적으로 IoT Edge 모듈(edgeAgent 및 edgeHub 포함)은 이 프록시의 인증서를 신뢰하지 않으며 TLS 핸드셰이크에 실패합니다.
실패한 핸드셰이크를 해결하려면 다음 단계를 수행하여 프록시의 루트 인증서를 신뢰하도록 운영 체제와 IoT Edge 모듈을 모두 설정합니다.
호스트 운영 체제의 신뢰할 수 있는 루트 인증서 저장소에서 프록시 인증서를 설정합니다. 루트 인증서를 설치하는 방법에 대한 자세한 내용은 OS 인증서 저장소에 루트 CA 설치를 참조하세요.
트러스트 번들에서 인증서를 참조하여 프록시 서버를 통해 통신하도록 IoT Edge 디바이스를 설정합니다. 트러스트 번들을 설정하는 방법에 대한 자세한 내용은 신뢰할 수 있는 루트 CA 관리(트러스트 번들)를 참조하세요.
IoT Edge에서 관리되지 않는 컨테이너에 대한 트래픽 검사 프록시 지원을 설정하려면 프록시 공급자에게 문의하세요.
IoT Edge가 통신하는 대상의 FQDN(정규화된 도메인 이름)
프록시의 방화벽에서 인터넷 연결을 위해 허용 목록에 모든 FQDN을 추가해야 하는 경우 IoT Edge 디바이스의 연결 허용 목록을 검토하여 추가할 FQDN을 결정합니다.
다음 단계
IoT Edge 런타임의 역할에 대해 알아봅니다.
Azure IoT Edge에 대한 일반적인 문제 및 해결 방법의 설치 및 구성 오류를 해결합니다.