프록시 서버를 통해 통신하도록 IoT Edge 디바이스 구성

아티클
04/11/2024

적용 대상: IoT Edge 1.4

Important

IoT Edge 1.4는 지원되는 릴리스입니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.

IoT Edge 디바이스는 IoT Hub와 통신하기 위해 HTTPS 요청을 보냅니다. 프록시 서버를 사용하는 네트워크에 디바이스를 연결한 경우 서버를 통해 통신하도록 IoT Edge 런타임을 구성해야 합니다. 프록시 서버는 IoT Edge 허브를 통해 라우팅하지 않은 HTTP 또는 HTTPS 요청을 만드는 경우 개별 IoT Edge 모듈에도 영향을 줄 수 있습니다.

이 문서에서는 프록시 서버 뒤에서 IoT Edge 디바이스를 구성한 후 관리하는 다음 4개 단계를 안내합니다.

디바이스에 IoT Edge 런타임 설치

IoT Edge 설치 스크립트는 인터넷에서 패키지 및 파일을 끌어오므로 디바이스는 프록시 서버를 통해 통신하여 해당 요청을 수행해야 합니다. Windows 디바이스의 경우 설치 스크립트는 오프라인 설치 옵션도 제공합니다.

이 단계는 처음 설정할 때 IoT Edge 디바이스를 구성하는 일회성 프로세스입니다. 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은 다음 형식을 사용합니다. 프로토콜://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 런타임 설치의 지침을 따릅니다.

Windows에서 Linux용 IoT Edge를 사용하는 Windows 디바이스

IoT Edge for Linux on Windows를 사용하여 IoT Edge 런타임을 설치하는 경우 IoT Edge는 기본적으로 Linux 가상 머신에 설치됩니다. 다른 단계를 설치하거나 업데이트할 필요는 없습니다.

Windows 컨테이너를 사용하는 Windows 디바이스

Windows 디바이스에서 IoT Edge 런타임을 설치하는 경우 프록시 서버를 두 번 거쳐야 합니다. 첫 번째 연결은 설치 관리자 스크립트 파일을 다운로드하고, 두 번째 연결은 설치 중에 필요한 구성 요소를 다운로드하는 것입니다. Windows 설정에서 프록시 정보를 구성하거나 PowerShell 명령에 직접 프록시 정보를 포함할 수 있습니다.

다음 단계에서는 -proxy 인수를 사용하는 Windows 설치의 예제를 보여 줍니다.

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에 포함할 수 없는 프록시 서버에 대한 복잡한 자격 증명이 있는 경우 내의 매개 변수-InvokeWebRequestParameters를 -ProxyCredential 사용합니다. 예를 들면 다음과 같습니다.

$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에 요청을 보냅니다.

Linux

터미널에서 편집기를 열어 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

Windows에서 Linux용 IoT Edge를 사용하는 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 Hub에 연결하여 배포 매니페스트를 검색합니다. 매니페스트는 디바이스가 배포해야 하는 다른 모듈을 선언합니다.

이 단계는 초기 디바이스 설정 중에 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.4"

[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.4"

[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.4"

[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.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
변경 내용을 저장하고 편집기를 닫습니다. 최신 변경 내용을 적용합니다.
```
sudo iotedge config apply
```
Env 섹션에서 docker inspect edgeAgent를 사용하여 프록시 설정이 전파되는지 확인합니다. 그렇지 않은 경우 컨테이너를 다시 만들어야 합니다.
```
sudo docker rm -f edgeAgent
```
IoT 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 허브 모듈을 구성하려면 마법사의 첫 번째 단계에서 런타임 설정 선택합니다.

Screenshot of how to configure advanced Edge Runtime settings.

https_proxy 환경 변수를 IoT Edge 에이전트 및 IoT Edge 허브 모듈 정의 모두에 추가합니다. IoT Edge 디바이스의 구성 파일에 UpstreamProtocol 환경 변수를 포함한 경우에는 IoT Edge 에이전트 모듈 정의에도 해당 환경 변수를 추가합니다.

Screenshot of how to set the https_proxy environment variable.

배포 매니페스트에 추가하는 기타 모든 모듈은 같은 패턴을 따릅니다. 적용을 선택하여 변경 내용을 저장합니다.

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.4",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

IoT Edge 디바이스의 confige.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에 대한 일반적인 문제 및 해결을 사용하여 설치 및 구성 오류 문제 해결