Mengonfigurasi perangkat IoT Edge untuk berkomunikasi melalui server proksi

2025-05-10

Berlaku untuk: IoT Edge 1.5

Penting

IoT Edge 1.5 LTS adalah rilis yang didukung. IoT Edge 1.4 LTS adalah akhir masa pakai per 12 November 2024. Jika Anda menggunakan rilis sebelumnya, lihat Memperbarui IoT Edge.

Perangkat IoT Edge mengirim permintaan HTTPS untuk berkomunikasi dengan IoT Hub. Jika perangkat Anda tersambung ke jaringan yang menggunakan server proksi, konfigurasikan runtime IoT Edge untuk berkomunikasi melalui server. Server proksi juga dapat memengaruhi modul IoT Edge individual jika mereka membuat permintaan HTTP atau HTTPS yang tidak dirutekan melalui hub IoT Edge.

Artikel ini menjelaskan empat langkah untuk mengonfigurasi dan mengelola perangkat IoT Edge di belakang server proksi:

Menginstal runtime IoT Edge di perangkat Anda

Skrip penginstalan IoT Edge menarik paket dan file dari internet, sehingga perangkat berkomunikasi melalui server proksi untuk membuat permintaan tersebut. Untuk perangkat Windows, skrip instalasi juga menyediakan opsi instalasi offline.

Langkah ini adalah proses sekali untuk mengonfigurasi perangkat IoT Edge saat pertama kali mengaturnya. Anda juga memerlukan koneksi yang sama ini saat memperbarui runtime IoT Edge.
Mengonfigurasi IoT Edge dan runtime kontainer di perangkat Anda

IoT Edge menangani komunikasi dengan IoT Hub. Runtime kontainer mengelola kontainer dan berkomunikasi dengan registri kontainer. Kedua komponen ini perlu membuat permintaan web melalui server proksi.

Langkah ini adalah proses sekali untuk mengonfigurasi perangkat IoT Edge saat pertama kali mengaturnya.
Mengonfigurasi properti agen IoT Edge dalam file konfigurasi di perangkat Anda

Daemon IoT Edge pada awalnya memulai modul edgeAgent. Kemudian, modul edgeAgent mengambil manifes penyebaran dari IoT Hub dan memulai semua modul lainnya. Konfigurasikan variabel lingkungan modul edgeAgent secara manual pada perangkat sehingga agen IoT Edge membuat koneksi awal ke IoT Hub. Setelah koneksi awal, Anda dapat mengonfigurasi modul edgeAgent dari jarak jauh.

Langkah ini adalah proses sekali untuk mengonfigurasi perangkat IoT Edge saat pertama kali mengaturnya.
Untuk semua penyebaran modul di masa mendatang, tetapkan variabel lingkungan untuk modul apa pun yang berkomunikasi melalui proksi

Setelah menyiapkan dan menyambungkan perangkat IoT Edge ke IoT Hub melalui server proksi, pertahankan koneksi di semua penyebaran modul di masa mendatang.

Langkah ini adalah proses berjalan yang dilakukan dari jarak jauh sehingga setiap modul atau pembaruan penyebaran baru akan mempertahankan kemampuan perangkat untuk berkomunikasi melalui server proksi.

Mengetahui URL proksi Anda

Sebelum memulai langkah-langkah dalam artikel ini, ketahui URL proksi Anda.

URL Proksi menggunakan format berikut: protocol://proxy_host:proxy_port.

Protokol ini adalah HTTP atau HTTPS. Daemon Docker dapat menggunakan salah satu protokol tergantung pada pengaturan registri kontainer Anda, tetapi daemon IoT Edge dan kontainer runtime selalu menggunakan HTTP untuk terhubung ke proksi.
proxy_host adalah alamat server proksi. Jika server proksi memerlukan autentikasi, berikan kredensial Anda sebagai bagian dari host proksi dalam format berikut: user:password@proxy_host.
proxy_port adalah port jaringan tempat proksi merespons lalu lintas.

Menginstal IoT Edge melalui proksi

Apakah perangkat IoT Edge Anda berjalan di Windows atau Linux, akses paket penginstalan melalui server proksi. Bergantung pada sistem operasi Anda, ikuti langkah-langkah untuk menginstal runtime IoT Edge melalui server proksi.

Perangkat Linux

Jika Anda menginstal runtime IoT Edge di perangkat Linux, siapkan manajer paket untuk menggunakan server proksi Anda untuk mengakses paket penginstalan. Misalnya Siapkan apt-get untuk menggunakan http-proxy. Setelah menyiapkan manajer paket Anda, ikuti instruksi di Menginstal runtime Azure IoT Edge.

Perangkat Windows yang menggunakan IoT Edge untuk Linux di Windows

Jika Anda menginstal runtime IoT Edge menggunakan IoT Edge untuk Linux di Windows, runtime IoT Edge diinstal secara default di komputer virtual Linux Anda. Anda tidak diharuskan menginstal atau memperbarui langkah-langkah lain.

Perangkat Windows yang menggunakan kontainer Windows

Jika menginstal runtime IoT Edge pada perangkat Windows, Anda harus melalui server proksi dua kali. Koneksi pertama mengunduh file skrip penginstal, dan koneksi kedua mengunduh komponen yang diperlukan selama penginstalan. Anda dapat mengonfigurasi informasi proksi di pengaturan Windows, atau menyertakan informasi proksi Anda secara langsung di perintah PowerShell.

Langkah-langkah berikut menunjukkan contoh penginstalan Windows menggunakan -proxy argumen :

Perintah Cabut-WebRequest memerlukan informasi proksi untuk mengakses skrip penginstal. Kemudian, perintah Sebarkan-IoTEdge membutuhkan informasi proksi untuk mengunduh file instalasi.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
Perintah Inisialisasi-IoTEdge tidak perlu melalui server proksi, sehingga langkah kedua hanya memerlukan informasi proksi untuk Cabut-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Jika kredensial server proksi Anda kompleks dan tidak dapat disertakan dalam URL, gunakan -ProxyCredential parameter dalam -InvokeWebRequestParameters. Contohnya,

$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 }

Untuk informasi selengkapnya tentang parameter proksi, lihat Cabut-WebRequest.

Mengonfigurasi IoT Edge dan Moby

IoT Edge menggunakan dua daemon yang berjalan di perangkat IoT Edge. Daemon Moby menarik gambar kontainer dari registri kontainer. Daemon IoT Edge berkomunikasi dengan IoT Hub.

Konfigurasikan daemon Moby dan IoT Edge untuk menggunakan server proksi guna fungsi perangkat secara berkelanjutan. Lakukan langkah ini pada perangkat IoT Edge selama penyiapan awal.

Daemon Moby

Karena Moby dibangun di Docker, lihat dokumentasi Docker untuk mengonfigurasi daemon Moby dengan variabel lingkungan. Sebagian besar registri kontainer, termasuk DockerHub dan Azure Container Registries, mendukung permintaan HTTPS, jadi atur parameter HTTPS_PROXY . Jika Anda menarik gambar dari registri yang tidak mendukung keamanan lapisan transport (TLS), Anda harus mengatur parameter HTTP_PROXY.

Pilih artikel yang berlaku untuk sistem operasi perangkat IoT Edge Anda:

Mengonfigurasi daemon Docker di Linux Pada perangkat Linux, daemon Moby masih disebut Docker.
Mengonfigurasi daemon Docker di Windows Daemon Moby pada perangkat Windows disebut iotedge-moby. Nama-nama tersebut berbeda karena dimungkinkan untuk menjalankan Docker Desktop dan Moby secara paralel pada perangkat Windows.

Daemon IoT Edge

Daemon IoT Edge mirip dengan daemon Moby. Gunakan langkah-langkah berikut untuk mengatur variabel lingkungan untuk layanan, berdasarkan sistem operasi Anda.

Daemon IoT Edge selalu menggunakan HTTPS untuk mengirim permintaan ke IoT Hub.

Linux

Di terminal, buka editor untuk mengonfigurasi daemon IoT Edge.

sudo systemctl edit aziot-edged

Masukkan teks berikut, ganti <URL> proksi dengan alamat dan port server proksi Anda. Kemudian, simpan dan keluar.

[Service]
Environment="https_proxy=<proxy URL>"

Mulai versi 1.2, IoT Edge menggunakan layanan identitas IoT untuk menangani provisi perangkat dengan IoT Hub atau IoT Hub Device Provisioning Service. Buka editor di terminal untuk mengonfigurasi daemon layanan identitas IoT.

sudo systemctl edit aziot-identityd

Masukkan teks berikut, ganti <URL> proksi dengan alamat dan port server proksi Anda. Kemudian, simpan dan keluar.

[Service]
Environment="https_proxy=<proxy URL>"

Refresh pengelola layanan untuk mengambil konfigurasi baru.

sudo systemctl daemon-reload

Mulai ulang layanan sistem IoT Edge untuk menerapkan perubahan pada kedua daemon.

sudo iotedge system restart

Verifikasi bahwa variabel lingkungan Anda dan konfigurasi baru ada.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows menggunakan IoT Edge untuk Linux di Windows

Masuk ke IoT Edge untuk Linux di komputer virtual Windows:

Connect-EflowVm

Ikuti langkah yang sama dengan bagian Linux di artikel ini untuk mengonfigurasi daemon IoT Edge.

Windows yang menggunakan kontainer Windows

Buka jendela PowerShell sebagai administrator dan jalankan perintah berikut untuk mengedit registri dengan variabel lingkungan baru. Ganti <url> proksi dengan alamat server proksi dan port Anda.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Mulai ulang IoT Edge agar perubahan diterapkan.

Restart-Service iotedge

Mengonfigurasi agen IoT Edge

Agen IoT Edge adalah modul pertama yang dimulai pada perangkat IoT Edge mana pun. Modul ini dimulai untuk pertama kalinya berdasarkan informasi dalam file konfigurasi IoT Edge. Agen IoT Edge kemudian terhubung ke IoT Hub untuk mengambil manifes penyebaran. Manifes menyatakan modul lain mana yang harus disebarkan perangkat.

Langkah ini terjadi sekali pada perangkat IoT Edge selama pengaturan perangkat awal.

Buka file konfigurasi di perangkat IoT Edge Anda: /etc/aziot/config.toml. Anda memerlukan hak administratif untuk mengakses file konfigurasi. Pada sistem Linux, gunakan perintah sudo sebelum membuka file di editor teks pilihan Anda.
Dalam file konfigurasi, temukan bagian [agent], yang berisi semua informasi konfigurasi untuk modul edgeAgent untuk digunakan pada saat penyalaan. Periksa apakah bagian [agent] tidak memiliki komentar. Jika bagian [agent] hilang, tambahkan ke config.toml. Definisi agen IoT Edge mencakup subbagian [agent.env] tempat Anda dapat menambahkan variabel lingkungan.

Tambahkan parameter https_proxy ke bagian variabel lingkungan dan atur URL proksi Anda sebagai nilainya.

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

Runtime IoT Edge menggunakan AMQP secara default untuk berkomunikasi dengan IoT Hub. Beberapa server proksi memblokir port AMQP. Jika itu masalahnya, Anda juga perlu mengonfigurasi edgeAgent untuk menggunakan AMQP melalui WebSocket. Hapus komentar dari UpstreamProtocol parameter .
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

Tambahkan parameter https_proxy ke bagian variabel lingkungan dan tetapkan URL proksi Anda sebagai nilainya.

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

Runtime IoT Edge menggunakan AMQP secara default untuk berkomunikasi dengan IoT Hub. Beberapa server proksi memblokir port AMQP. Jika itu masalahnya, Anda juga perlu mengonfigurasi edgeAgent untuk menggunakan AMQP melalui WebSocket. Batalkan komentar pada parameter UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Simpan perubahan dan tutup editor. Terapkan perubahan.
```
sudo iotedge config apply
```
Verifikasi bahwa pengaturan proksi diterapkan menggunakan docker inspect edgeAgent di bagian Env . Jika tidak, Anda harus membuat ulang kontainer.
```
sudo docker rm -f edgeAgent
```
Runtime IoT Edge membangun ulang edgeAgent dalam satu menit. edgeAgent Setelah kontainer berjalan lagi, gunakan docker inspect edgeAgent perintah untuk memverifikasi bahwa pengaturan proksi cocok dengan file konfigurasi.

Mengonfigurasi manifes penyebaran

Setelah Mengonfigurasi perangkat IoT Edge untuk bekerja dengan server proksi Anda, deklarasikan variabel lingkungan HTTPS_PROXY dalam manifes penyebaran di masa mendatang. Anda dapat mengedit manifes penyebaran baik menggunakan panduan portal Azure maupun dengan mengedit file JSON manifes penyebaran.

Selalu konfigurasikan dua modul runtime, edgeAgent, dan edgeHub, untuk berkomunikasi melalui server proksi sehingga mereka mempertahankan koneksi dengan IoT Hub. Jika Anda menghapus informasi proksi dari modul edgeAgent, satu-satunya cara untuk membangun kembali koneksi adalah dengan mengedit file konfigurasi pada perangkat, seperti yang dijelaskan di bagian sebelumnya.

Selain modul edgeAgent dan edgeHub, modul lain mungkin memerlukan konfigurasi proksi. Modul yang mengakses sumber daya Azure selain IoT Hub, seperti penyimpanan blob, harus menentukan variabel HTTPS_PROXY dalam file manifes penyebaran.

Prosedur ini berlaku sepanjang masa pakai perangkat IoT Edge.

Portal Azure

Saat Anda menggunakan wizard Atur modul untuk membuat penyebaran untuk perangkat IoT Edge, setiap modul memiliki bagian Variabel Lingkungan tempat Anda dapat mengonfigurasi koneksi server proksi.

Untuk mengonfigurasi modul agen IoT Edge dan hub IoT Edge, pilih Pengaturan Runtime pada langkah pertama di wizard.

Cuplikan layar cara mengonfigurasi pengaturan Edge Runtime tingkat lanjut.

Tambahkan variabel lingkungan https_proxy ke agen IoT Edge dan definisi pengaturan runtime hub IoT Edge . Jika Anda menyertakan variabel lingkungan UpstreamProtocol dalam file konfigurasi pada perangkat IoT Edge Anda, tambahkan ke definisi modul agen IoT Edge juga.

Semua modul lain yang Anda tambahkan ke manifes penyebaran akan mengikuti pola yang sama. Pilih Terapkan untuk menyimpan perubahan.

File manifes penyebaran JSON

Jika Anda membuat penyebaran untuk perangkat IoT Edge menggunakan templat di Visual Studio Code atau dengan membuat file JSON secara manual, Anda dapat menambahkan variabel lingkungan secara langsung ke setiap definisi modul. Jika Anda tidak menambahkannya di portal Azure, tambahkan di sini ke file manifes JSON Anda. Ganti <proxy URL> dengan nilai Anda.

Gunakan format JSON berikut:

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

Dengan variabel lingkungan yang disertakan, definisi modul terlihat seperti contoh edgeHub berikut:

"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"
}

Jika Anda menyertakan variabel lingkungan UpstreamProtocol dalam file config.yaml pada perangkat IoT Edge Anda, tambahkan itu ke definisi modul agen IoT Edge juga.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Bekerja dengan proksi pemeriksaan lalu lintas

Beberapa proksi seperti Zscaler dapat memeriksa lalu lintas terenkripsi TLS. Selama inspeksi lalu lintas TLS, sertifikat yang dikembalikan oleh proksi bukan sertifikat dari server target tetapi sebaliknya sertifikat yang ditandatangani oleh sertifikat akar proksi sendiri. Secara default, modul IoT Edge (termasuk edgeAgent dan edgeHub) tidak mempercayai sertifikat proksi ini dan jabat tangan TLS gagal.

Untuk memperbaiki jabat tangan yang gagal, siapkan sistem operasi dan modul IoT Edge agar mempercayai sertifikat akar dari proksi dengan mengikuti langkah-langkah ini.

Siapkan sertifikat proksi di penyimpanan sertifikat akar tepercaya dari sistem operasi host Anda. Untuk informasi selengkapnya tentang cara menginstal sertifikat akar, lihat Menginstal OS akar ke penyimpanan sertifikat OS.
Siapkan perangkat IoT Edge Anda untuk berkomunikasi melalui server proksi dengan mereferensikan sertifikat dalam bundel kepercayaan. Untuk informasi selengkapnya tentang cara menyiapkan bundel kepercayaan, lihat Mengelola CA akar tepercaya (bundel kepercayaan).

Untuk menyiapkan dukungan proksi inspeksi lalu lintas untuk kontainer yang tidak dikelola oleh IoT Edge, hubungi penyedia proksi Anda.

Nama domain yang sepenuhnya memenuhi syarat (FQDN) dari tujuan yang dihubungi oleh IoT Edge.

Jika firewall proksi Anda memerlukan penambahan semua FQDN ke daftar yang diizinkan untuk konektivitas internet, tinjau daftar dari Izinkan koneksi dari perangkat IoT Edge untuk menentukan FQDN mana yang akan ditambahkan.

Langkah berikutnya

Pelajari peran IoT Edge runtime.

Memecahkan masalah kesalahan penginstalan dan konfigurasi dalam Masalah umum dan resolusi untuk Azure IoT Edge.