Ağ geçidi hiyerarşi senaryonuz için API proxy modülünü yapılandırma

Makale
06/12/2024

Şunlar için geçerlidir: IoT Edge 1.5 IoT Edge 1.4

Önemli

IoT Edge 1.5 LTS ve IoT Edge 1.4 LTS desteklenen sürümlerdir. IoT Edge 1.4 LTS, 12 Kasım 2024'te kullanım ömrü sona erer. Önceki bir sürümdeyseniz bkz. IoT Edge’i güncelleştirme.

Bu makalede API proxy modülü yapılandırma seçeneklerinde yol gösterilir, böylece modülü ağ geçidi hiyerarşi gereksinimlerinizi destekleyecek şekilde özelleştirebilirsiniz.

API proxy modülü, tümü HTTPS protokolünü destekleyen ve bağlantı noktası 443'e bağlanan birden çok hizmet dağıtıldığında IoT Edge cihazları için iletişimi basitleştirir. Bu, özellikle aşağı akış cihazlarındaki istemciler doğrudan buluta bağlanamadığından, Ağ yalıtma aşağı akış cihazları bölümünde açıklananlar gibi ISA-95 tabanlı ağdan yalıtılmış mimarilerde IoT Edge cihazlarının hiyerarşik dağıtımlarında geçerlidir.

Örneğin, aşağı akış IoT Edge cihazlarının Docker görüntülerini çekmesine izin vermek için bir Docker kayıt defteri modülünün dağıtılması gerekir. Blobların karşıya yüklenmesine izin vermek için aynı IoT Edge cihazına bir Azure Blob Depolama modülü dağıtılması gerekir. Bu hizmetlerin her ikisi de iletişim için HTTPS kullanır. API proxy'si bir IoT Edge cihazında bu tür dağıtımları etkinleştirir. API proxy modülü, her hizmet yerine konak cihazdaki 443 numaralı bağlantı noktasına bağlanır ve isteği kullanıcı tarafından yapılandırılabilir kurallar başına bu cihazda çalışan doğru hizmet modülüne yönlendirir. İstemcilerin kimliğini doğrulamak ve yetkilendirmek de dahil olmak üzere isteklerin işlenmesinden tek tek hizmetler sorumludur.

API ara sunucusu olmadan, her hizmet modülünün ana cihazdaki ayrı bir bağlantı noktasına bağlanması ve üst IoT Edge cihazına bağlanan her alt cihazda yorucu ve hataya açık bir yapılandırma değişikliği gerektirmesi gerekir.

Not

Aşağı akış cihazı verileri doğrudan İnternet'e veya ağ geçidi cihazlarına (IoT Edge etkin veya değil) yayar. Alt cihaz, iç içe topolojideki bir aşağı akış cihazı veya ağ geçidi cihazı olabilir.

Ara sunucu modülünü dağıtma

API proxy modülü Microsoft Container Registry'den (MCR) kullanılabilir ve görüntü URI'si şeklindedir mcr.microsoft.com/azureiotedge-api-proxy:latest. Modülü Azure portalını veya Azure CLI'yi kullanarak dağıtabilirsiniz.

Ara sunucu modülünü anlama

API proxy modülü, verileri ağ katmanları üzerinden yönlendirmek için nginx ters proxy'sini kullanır. Ara sunucu modüle eklendiğinden modül görüntüsünün ara sunucu yapılandırmasını desteklemesi gerekir. Örneğin, ara sunucu belirli bir bağlantı noktasında dinliyorsa modülün bu bağlantı noktasının açık olması gerekir.

Ara sunucu, modüle eklenmiş varsayılan bir yapılandırma dosyasıyla başlar. Modül ikizini kullanarak buluttan modüle yeni bir yapılandırma geçirebilirsiniz. Ayrıca, dağıtım zamanında yapılandırma ayarlarını açmak veya kapatmak için ortam değişkenlerini kullanabilirsiniz.

Bu makale öncelikle varsayılan yapılandırma dosyasına ve ayarlarını etkinleştirmek için ortam değişkenlerinin nasıl kullanılacağına odaklanır. Ardından, sonunda yapılandırma dosyasını özelleştirmeyi ele aacağız.

Varsayılan yapılandırma

API proxy modülü, yaygın senaryoları destekleyen ve özelleştirmeye izin veren varsayılan bir yapılandırmayla birlikte gelir. Modülün ortam değişkenleri aracılığıyla varsayılan yapılandırmayı denetleyebilirsiniz.

Şu anda varsayılan ortam değişkenleri şunlardır:

Ortam değişkeni	Açıklama
`PROXY_CONFIG_ENV_VAR_LIST`	Virgülle ayrılmış bir listede güncelleştirmek istediğiniz tüm değişkenleri listeleyin. Bu adım, yanlış yapılandırma ayarlarının yanlışlıkla değiştirilmesini engeller.
`NGINX_DEFAULT_TLS`	Etkinleştirilecek TLS protokollerinin listesini belirtir. Bkz. NGINX'in ssl_protocols. Varsayılan değer :'TLSv1.2'.
`NGINX_DEFAULT_PORT`	nginx proxy'sinin dinlediğini bağlantı noktasını değiştirir. Bu ortam değişkenini güncelleştirirseniz, bağlantı noktasını dockerfile modülünde kullanıma sunmanız ve dağıtım bildiriminde bağlantı noktası bağlamasını bildirmeniz gerekir. Daha fazla bilgi için bkz . Proxy bağlantı noktasını kullanıma sunma. Varsayılan değer 443'dür. Azure Market dağıtıldığında, edgeHub modülüyle çakışmaları önlemek için varsayılan bağlantı noktası 8000'e güncelleştirilir. Daha fazla bilgi için bkz . Açık bağlantı noktalarını en aza indirme.
`DOCKER_REQUEST_ROUTE_ADDRESS`	Docker isteklerini yönlendirmek için adres. Üst katman cihazında bu değişkeni kayıt defteri modülüne işaret eden şekilde değiştirin. Varsayılan, üst konak adıdır.
`BLOB_UPLOAD_ROUTE_ADDRESS`	Blob kayıt defteri isteklerini yönlendirmek için adres. Üst katman cihazındaki bu değişkeni blob depolama modülüne işaret eden şekilde değiştirin. Varsayılan, üst konak adıdır.

Açık bağlantı noktalarını simge durumuna küçültme

Açık bağlantı noktası sayısını en aza indirmek için, API proxy modülü edgeHub modülünü hedefleyen trafik de dahil olmak üzere tüm HTTPS trafiğini (bağlantı noktası 443) geçirmelidir. API proxy modülü varsayılan olarak tüm edgeHub trafiğini 443 numaralı bağlantı noktasında yeniden yönlendirecek şekilde yapılandırılır.

Dağıtımınızı açık bağlantı noktalarını en aza indirecek şekilde yapılandırmak için aşağıdaki adımları kullanın:

EdgeHub modülü ayarlarını bağlantı noktası 443'e bağlanmayacak şekilde güncelleştirin; aksi takdirde bağlantı noktası bağlama çakışmaları olur. EdgeHub modülü varsayılan olarak 443, 5671 ve 8883 bağlantı noktalarına bağlanır. Bağlantı noktası 443 bağlamasını silin ve diğer ikisini yerinde bırakın:
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
API proxy modülünü 443 numaralı bağlantı noktasına bağlanacak şekilde yapılandırın.
1. NGINX_DEFAULT_PORT ortam değişkeninin değerini olarak 443ayarlayın.
2. Kapsayıcı oluşturma seçeneklerini 443 numaralı bağlantı noktasına bağlanacak şekilde güncelleştirin.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

Açık bağlantı noktalarını en aza indirmeniz gerekmiyorsa edgeHub modülünün 443 numaralı bağlantı noktasını kullanmasına izin verebilir ve API proxy modülünü başka bir bağlantı noktasını dinleyecek şekilde yapılandırabilirsiniz. Örneğin API proxy modülü, NGINX_DEFAULT_PORT ortam değişkeninin 8000 değerini olarak ayarlayarak ve 8000 numaralı bağlantı noktası için bağlantı noktası bağlaması oluşturarak 8000 numaralı bağlantı noktasını dinleyebilir.

Kapsayıcı görüntüsü indirmeyi etkinleştirme

API ara sunucusu modülünün yaygın kullanım örneklerden biri, IoT Edge cihazlarının kapsayıcı görüntülerini çekmek için alt katmanlarda etkinleştirilmesidir. Bu senaryo, buluttan kapsayıcı görüntülerini almak ve üst katmanda önbelleğe almak için Docker kayıt defteri modülünü kullanır. API ara sunucusu, üst katmandaki kayıt defteri modülü tarafından sunulacak alt katmanlardan bir kapsayıcı görüntüsü indirmeye yönelik tüm HTTPS isteklerini aktarır.

Bu senaryo, aşağı akış IoT Edge cihazlarının etki alanı adını $upstream ve ardından bir görüntünün kapsayıcı kayıt defteri yerine API Proxy modülü bağlantı noktası numarasını işaret etmelerini gerektirir. Örneğin: $upstream:8000/azureiotedge-api-proxy:1.1.

Bu kullanım örneği, ağ geçitlerini kullanarak IoT Edge cihazları hiyerarşisi oluşturma öğreticisinde gösterilmiştir.

Üst katmanda aşağıdaki modülleri yapılandırın:

Docker kayıt defteri modülü
- Modülü kayıt defteri gibi akılda kalıcı bir adla yapılandırın ve istekleri almak için modüldeki bir bağlantı noktasını kullanıma sunun.
- Modülü kapsayıcı kayıt defterinize eş olacak şekilde yapılandırın.

API proxy modülü

Aşağıdaki ortam değişkenlerini yapılandırın:

Veri Akışı Adı	Değer
`DOCKER_REQUEST_ROUTE_ADDRESS`	Kayıt defteri modülü adı ve açık bağlantı noktası. Örneğin, `registry:5000`.
`NGINX_DEFAULT_PORT`	Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, `8000`.

Aşağıdaki createOptions'ı yapılandırın:

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

Bu senaryo için herhangi bir alt katmanda aşağıdaki modülü yapılandırın:

API proxy modülü. API proxy modülü, alt katman cihazı dışındaki tüm alt katman cihazlarda gereklidir.
- Aşağıdaki ortam değişkenlerini yapılandırın:
  
  Veri Akışı Adı Değer
  
  NGINX_DEFAULT_PORT Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, 8000.
- Aşağıdaki createOptions'ı yapılandırın:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Veri Akışı Adı	Değer
`NGINX_DEFAULT_PORT`	Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, `8000`.

Proxy bağlantı noktasını kullanıma sunma

8000 numaralı bağlantı noktası docker görüntüsünden varsayılan olarak kullanıma sunulur. Farklı bir nginx proxy bağlantı noktası kullanılıyorsa, dağıtım bildiriminde bağlantı noktasını belirten ExposedPorts bölümünü ekleyin. Örneğin, nginx proxy bağlantı noktasını 8001 olarak değiştirirseniz, dağıtım bildirimine aşağıdakileri ekleyin:

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

Blob karşıya yüklemeyi etkinleştirme

API ara sunucusu modülünün bir diğer kullanım örneği de blobları karşıya yüklemek için alt katmanlardaki IoT Edge cihazlarını etkinleştirmektir. Bu kullanım örneği, modül günlüklerini karşıya yükleme veya destek paketini karşıya yükleme gibi alt katman cihazlarda sorun giderme işlevselliği sağlar.

Bu senaryo, blob oluşturma ve karşıya yükleme işlemlerini işlemek için üst katmandaki IoT Edge'de Azure Blob Depolama modülünü kullanır. İç içe yerleştirilmiş bir senaryoda en fazla beş katman desteklenir. IoT Edge'de Azure Blob Depolama modülü üst katman cihazda gereklidir ve alt katman cihazlar için isteğe bağlıdır. Örnek çok katmanlı dağıtım için bkz . Endüstriyel IoT için Azure IoT Edge örneği.

Üst katmanda aşağıdaki modülleri yapılandırın:

IoT Edge'de bir Azure Blob Depolama modülü.

API proxy modülü

Aşağıdaki ortam değişkenlerini yapılandırın:

Veri Akışı Adı	Değer
`BLOB_UPLOAD_ROUTE_ADDRESS`	Blob depolama modülü adı ve açık bağlantı noktası. Örneğin, `azureblobstorageoniotedge:11002`.
`NGINX_DEFAULT_PORT`	Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, `8000`.

Aşağıdaki createOptions'ı yapılandırın:

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

Bu senaryo için herhangi bir alt katmanda aşağıdaki modülü yapılandırın:

API proxy modülü
- Aşağıdaki ortam değişkenlerini yapılandırın:
  
  Veri Akışı Adı Değer
  
  NGINX_DEFAULT_PORT Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, 8000.
- Aşağıdaki createOptions'ı yapılandırın:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Veri Akışı Adı	Değer
`NGINX_DEFAULT_PORT`	Nginx proxy'sinin aşağı akış cihazlarından gelen istekler için dinlediğini bağlantı noktası. Örneğin, `8000`.

Destek paketini veya günlük dosyasını üst katmanda bulunan blob depolama modülüne yüklemek için aşağıdaki adımları kullanın:

Azure Depolama Gezgini veya REST API'lerini kullanarak bir blob kapsayıcısı oluşturun. Daha fazla bilgi için bkz. IoT Edge'de Azure Blob Depolama ile verileri uçta depolama.
IoT Edge dağıtımlarından günlükleri alma başlığındaki adımlara göre günlük veya destek paketini karşıya yükleme isteğinde bulunun, ancak blob depolama modülü adresi yerine etki alanı adını $upstream ve açık ara sunucu bağlantı noktasını kullanın. Örneğin:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

Ara sunucu yapılandırmasını düzenleme

Varsayılan yapılandırma dosyası API proxy modülüne eklenir, ancak modül ikizini kullanarak bulut aracılığıyla modüle yeni bir yapılandırma geçirebilirsiniz.

Kendi yapılandırmanızı yazarken, dağıtım başına ayarları ayarlamak için ortamı kullanmaya devam edebilirsiniz. Aşağıdaki sözdizimini kullanın:

Ortam değişkeninin değerini almak için kullanın ${MY_ENVIRONMENT_VARIABLE} .

Ortam değişkeninin değerine göre ayarları açmak veya kapatmak için koşullu deyimleri kullanın:

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

API proxy modülü bir ara sunucu yapılandırmasını ayrıştırdığında, ilk olarak içinde listelenen PROXY_CONFIG_ENV_VAR_LIST tüm ortam değişkenlerini değiştirme kullanarak sağlanan değerleriyle değiştirir. Ardından ve çifti arasındaki #if_tag #endif_tag her şey değiştirilir. Modül daha sonra nginx ters ara sunucusuna ayrıştırılmış yapılandırmayı sağlar.

Proxy yapılandırmasını dinamik olarak güncelleştirmek için aşağıdaki adımları kullanın:

Yapılandırma dosyanızı yazın. Bu varsayılan şablonu başvuru olarak kullanabilirsiniz: nginx_default_config.conf
Yapılandırma dosyasının metnini kopyalayın ve base64'e dönüştürün.
Kodlanmış yapılandırma dosyasını modül ikizinde istenen özelliğin proxy_config değeri olarak yapıştırın.

Sonraki adımlar

Aşağı akış IoT Edge cihazını Azure IoT Edge ağ geçidine bağlamak için API proxy modülünü kullanın.

Aracılığıyla paylaş