Mengonfigurasi modul proksi API untuk skenario hierarki gateway Anda

  • Artikel

Berlaku untuk:IoT Edge 1.4 checkmark IoT Edge 1.4

Penting

IoT Edge 1.4 adalah rilis yang didukung Jika Anda menggunakan rilis sebelumnya, lihat Memperbarui IoT Edge.

Artikel ini menelusuri opsi konfigurasi untuk modul proksi API, sehingga Anda dapat menyesuaikan modul tersebut agar dapat mendukung persyaratan hierarki gateway Anda.

Modul proksi API menyederhanakan komunikasi untuk perangkat IoT Edge ketika beberapa layanan disebarkan yang semuanya mendukung protokol HTTPS dan mengikat ke port 443. Ini sangat relevan dalam penyebaran hierarkis perangkat IoT Edge dalam arsitektur terisolasi jaringan berbasis ISA-95 seperti yang dijelaskan dalam Jaringan mengisolasi perangkat hilir karena klien pada perangkat hilir tidak dapat terhubung langsung ke cloud.

Misalnya, untuk memungkinkan perangkat IoT Edge hilir menarik gambar Docker memerlukan penyebaran modul registri Docker. Untuk memungkinkan pengunggahan blob, diperlukan penyebaran modul Azure Blob Storage pada perangkat IoT Edge yang sama. Kedua layanan ini menggunakan HTTPS untuk komunikasi. Proksi API mengaktifkan penyebaran tersebut pada perangkat IoT Edge. Alih-alih setiap layanan, modul proksi API mengikat port 443 pada perangkat host dan merutekan permintaan ke modul layanan yang tepat yang berjalan pada perangkat tersebut pada setiap aturan yang dapat dikonfigurasi oleh pengguna. Layanan individu masih bertanggung jawab untuk menangani permintaan, termasuk mengautentikasi dan memberi otorisasi kepada klien.

Tanpa proksi API, setiap modul layanan harus mengikat ke port terpisah pada perangkat host, yang membutuhkan perubahan konfigurasi yang rumit dan rawan terjadi kesalahan pada setiap perangkat anak yang tersambung ke perangkat IoT Edge induk.

Catatan

Perangkat hilir memancarkan data langsung ke Internet atau ke perangkat gateway (diaktifkan IoT Edge atau tidak). Perangkat anak dapat menjadi perangkat hilir atau perangkat gateway dalam topologi berlapis.

Menyebarkan modul proksi

Modul proksi API tersedia dari Microsoft Container Registry (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Anda juga dapat menyebarkan modul proksi API langsung dari Marketplace Azure: Azure IoT Edge API Proksi.

Memahami modul proksi

Modul proksi API memanfaatkan proksi terbalik nginx untuk merutekan data melalui lapisan jaringan. Proksi tertanam dalam modul, yang berarti bahwa gambar modul perlu mendukung konfigurasi proksi. Sebagai contoh, jika proksi mendengarkan port tertentu, maka modul harus membuka port tersebut.

Proksi dimulai dengan file konfigurasi default yang disematkan dalam modul. Anda dapat meneruskan konfigurasi baru ke modul dari cloud menggunakan modul kembar. Selain itu, Anda dapat menggunakan variabel lingkungan untuk mengaktifkan atau menonaktifkan pengaturan konfigurasi pada waktu penyebaran.

Artikel ini berfokus terlebih dahulu pada file konfigurasi default, dan cara menggunakan variabel lingkungan untuk mengaktifkan pengaturannya. Kemudian, kami membahas tentang mengkustomisasi file konfigurasi di akhir.

Konfigurasi default

Modul proksi API dilengkapi dengan konfigurasi default yang mendukung skenario umum dan memungkinkan penyesuaian. Anda dapat mengontrol konfigurasi default melalui variabel lingkungan modul.

Saat ini, variabel lingkungan default meliputi:

Variabel lingkungan Deskripsi
PROXY_CONFIG_ENV_VAR_LIST Mencantumkan semua variabel yang ingin Anda perbarui dalam daftar yang dipisahkan dengan koma. Langkah ini mencegah perubahan pengaturan konfigurasi yang salah secara tidak disengaja.
NGINX_DEFAULT_TLS Menentukan daftar protokol TLS yang akan diaktifkan. Lihat ssl_protocols NGINX.

Defaultnya adalah 'TLSv1.2'.
NGINX_DEFAULT_PORT Mengubah port yang didengarkan oleh proksi nginx. Jika Anda memperbarui variabel lingkungan ini, Anda harus mengekspos port di dockerfile modul dan mendeklarasikan pengikatan port dalam manifes penyebaran. Untuk informasi selengkapnya, lihat Mengekspos port proksi.

Default-nya adalah 443.

Saat disebarkan dari Marketplace Azure, port default diperbarui ke 8000 untuk mencegah konflik dengan modul edgeHub. Untuk informasi selengkapnya, lihat Mengecilkan port terbuka.
DOCKER_REQUEST_ROUTE_ADDRESS Alamat untuk merutekan permintaan penambat. Ubah variabel ini pada perangkat lapisan atas untuk menunjuk ke modul registri.

Default-nya adalah nama host induk.
BLOB_UPLOAD_ROUTE_ADDRESS Alamat untuk merutekan permintaan registri blob. Ubah variabel ini pada perangkat lapisan atas untuk menunjuk ke modul penyimpanan blob.

Default-nya adalah nama host induk.

Mengecilkan port terbuka

Untuk mengecilkan jumlah port terbuka, modul proksi API harus me-relay semua lalu lintas HTTPS (port 443), termasuk lalu lintas yang menargetkan modul edgeHub. Modul proksi API dikonfigurasikan secara default untuk merutekan ulang semua lalu lintas edgeHub pada port 443.

Menggunakan langkah-langkah berikut untuk mengonfigurasikan penyebaran Anda untuk mengecilkan port yang terbuka:

  1. Perbarui pengaturan modul edgeHub untuk tidak mengikat pada port 443, jika tidak, akan ada konflik pengikatan port. Secara default, modul edgeHub mengikat port 443, 5671, dan 8883. Menghapus pengikatan port 443 dan biarkan dua lainnya di tempat:

    {
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}

  2. Konfigurasikan modul proksi API untuk mengikat port 443.

    1. Set nilai NGINX_DEFAULT_PORT variabel lingkungan menjadi 443.

    2. Perbarui opsi pembuatan kontainer untuk mengikat pada port 443.

      {
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}

Jika Anda tidak perlu mengecilkan port terbuka, maka Anda dapat membiarkan modul edgeHub menggunakan port 443 dan mengonfigurasikan modul proksi API untuk mendengarkan port lain. Misalnya, modul proksi API dapat mendengarkan port 8000 dengan mengatur nilai NGINX_DEFAULT_PORT variabel lingkungan ke 8000 dan membuat pengikatan untuk port 8000.

Mengaktifkan pengunduhan gambar kontainer

Kasus penggunaan umum untuk modul proksi API adalah mengaktifkan perangkat Azure IoT Edge di lapisan bawah untuk menarik gambar kontainer. Skenario ini menggunakan modul Penambat registri modul untuk mengambil gambar kontainer kembali dari cloud dan menyimpannya di lapisan atas. Proksi API menyampaikan semua permintaan HTTPS untuk mengunduh gambar kontainer dari lapisan bawah yang akan dilayani oleh modul registri di lapisan atas.

Skenario ini mengharuskan perangkat Azure IoT Edge downstream menunjuk ke nama domain $upstream yang diikuti oleh nomor port modul Proxksi API alih-alih registri kontainer gambar. Sebagai contoh: $upstream:8000/azureiotedge-api-proxy:1.1.

Kasus penggunaan ini ditunjukkan dalam tutorial Membuat hierarki perangkat Azure IoT Edge menggunakan gateway.

Mengonfigurasikan modul berikut di lapisan atas:

  • Modul registri Docker
    • Konfigurasikan modul dengan nama yang mudah diingat seperti registri dan mengekspos port dalam modul untuk menerima permintaan.
    • Konfigurasikan modul untuk memetakan ke registri kontainer Anda.
  • Modul proksi API

    • Mengonfigurasikan variabel lingkungan berikut:

      Nama Nilai
      DOCKER_REQUEST_ROUTE_ADDRESS Nama modul registri dan port terbuka. Contohnya, registry:5000.
      NGINX_DEFAULT_PORT Port yang didengarkan proksi nginx untuk permintaan dari perangkat downstream. Contohnya, 8000.

    • Mengonfigurasikan createOptions berikut:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Mengonfigurasikan modul berikut pada lapisan bawah untuk skenario ini:

  • Modul proksi API. Modul proksi API diperlukan pada semua perangkat lapisan bawah kecuali perangkat lapisan bawah.

    • Mengonfigurasikan variabel lingkungan berikut:

      Nama Nilai
      NGINX_DEFAULT_PORT Port yang didengarkan proksi nginx untuk permintaan dari perangkat downstream. Contohnya, 8000.

    • Mengonfigurasikan createOptions berikut:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Mengekspos port proksi

Port 8000 diekspos secara default dari gambar docker. Jika port proksi nginx yang berbeda digunakan, tambahkan bagian ExposedPorts yang mendeklarasikan port dalam manifes penyebaran. Misalnya, jika Anda mengubah port proksi nginx menjadi 8001, tambahkan yang berikut ini ke manifes penyebaran:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

Mengaktifkan unggahan blob

Kasus penggunaan lain untuk modul proksi API adalah mengaktifkan perangkat Azure IoT Edge pada lapisan bawah untuk mengunggah blob. Kasus penggunaan ini memungkinkan fungsionalitas pemecahan masalah pada perangkat lapisan bawah seperti mengunggah log modul atau mengunggah bundel dukungan.

Skenario ini menggunakan Azure Blob Storage pada Azure IoT Edge modul pada lapisan atas untuk menangani pembuatan dan pengunggahan blob. Dalam skenario berlapis, hingga lima lapisan didukung. Modul Azure Blob Storage di IoT Edge diperlukan pada perangkat lapisan atas dan opsional untuk perangkat lapisan bawah. Untuk contoh penyebaran multi-lapisan, lihat sampel Azure IoT Edge for Industrial IoT .

Mengonfigurasikan modul berikut di lapisan atas:

  • Azure Blob Storage pada modul Azure IoT Edge.
  • Modul proksi API

    • Mengonfigurasikan variabel lingkungan berikut:

      Nama Nilai
      BLOB_UPLOAD_ROUTE_ADDRESS Nama modul penyimpanan blob dan port terbuka. Contohnya, azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Port yang didengarkan proksi nginx untuk permintaan dari perangkat downstream. Contohnya, 8000.

    • Mengonfigurasikan createOptions berikut:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Mengonfigurasikan modul berikut pada lapisan bawah untuk skenario ini:

  • Modul proksi API

    • Mengonfigurasikan variabel lingkungan berikut:

      Nama Nilai
      NGINX_DEFAULT_PORT Port yang didengarkan proksi nginx untuk permintaan dari perangkat downstream. Contohnya, 8000.

    • Mengonfigurasikan createOptions berikut:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Menggunakan langkah-langkah berikut untuk mengunggah bundel dukungan atau file log ke modul penyimpanan blob yang terletak di lapisan atas:

  1. Buat kontainer blob menggunakan Azure Storage Explorer atau API REST. Untuk informasi selengkapnya, lihat Menyimpan data di Azure Stack Edge dengan Azure Blob Storage pada Azure IoT Edge.

  2. Minta pengunggahan bundel log atau dukungan sesuai dengan langkah-langkah dalam Mengambil kembali log dari penyebaran Azure IoT Edge, tetapi gunakan nama domain $upstream dan port proksi terbuka sebagai ganti dari alamat modul penyimpanan blob. Contohnya:

    {
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}

Mengedit konfigurasi proksi

File konfigurasi default disematkan pada modul proksi API, tetapi Anda dapat meneruskan konfigurasi baru ke modul melalui cloud menggunakan modul kembar.

Saat menulis konfigurasi, Anda masih dapat menggunakan lingkungan untuk menyesuaikan pengaturan per penyebaran. Gunakan sintaks berikut:

  • Gunakan ${MY_ENVIRONMENT_VARIABLE} untuk mengambil nilai variabel lingkungan.

  • Gunakan pernyataan bersyarat untuk mengaktifkan atau menonaktifkan pengaturan berdasarkan nilai variabel lingkungan:

    #if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

Ketika modul proksi API mengurai konfigurasi proksi, modul ini terlebih dahulu menggantikan semua variabel lingkungan yang tercantum dalam PROXY_CONFIG_ENV_VAR_LISTdengan nilai yang disediakan menggunakan substitusi. Kemudian, semuanya di antara #if_tag dan #endif_tag pasangan diganti. Kemudian, modul menyediakan konfigurasi terurai ke proksi terbalik nginx.

Untuk memperbarui konfigurasi proksi secara dinamis, gunakan langkah-langkah berikut:

  1. Tulis file konfigurasi Anda. Anda dapat menggunakan templat default ini sebagai referensi: nginx_default_config.conf

  2. Salin teks file konfigurasi dan konversikan ke base64.

  3. Tempelkan file konfigurasi yang dikodekan sebagai nilai proxy_config properti yang diinginkan dalam modul kembar.

    Screenshot that shows how to paste encoded config file as value of proxy_config property.

Langkah berikutnya

Gunakan modul proksi API untuk Menyambungkan perangkat Azure IoT Edge downstream ke gateway Azure IoT Edge.