Skip to content

Commit 23b9c48

Browse files
19BMG0019BMG00
authored
Merge pull request #202861 from kgremban/jun24-duconcepts5
Device update concepts review - 5
2 parents 65cb3e5 + d257f7b commit 23b9c48

File tree

4 files changed

+93
-100
lines changed

4 files changed

+93
-100
lines changed

‎articles/iot-hub-device-update/connected-cache-configure.md

Lines changed: 44 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,58 +4,39 @@ titleSuffix: Device Update for Azure IoT Hub
44
description: Overview of Microsoft Connected Cache for Device Update for Azure IoT Hub
55
author: andyriv
66
ms.author: andyriv
7-
ms.date: 2/16/2021
7+
ms.date: 08/19/2022
88
ms.topic: conceptual
99
ms.service: iot-hub-device-update
1010
---
1111

12-
# Configure Microsoft Connected Cache for Device Update for Azure IoT Hub
12+
# Configure Microsoft Connected Cache for Device Update for IoT Hub
1313

14-
Microsoft Connected Cache is deployed to Azure IoT Edge gateways as an Azure IoT Edge Module. Like other Azure IoT Edge modules, MCC module deployment environment variables and container create options are used to configure Microsoft Connected Cache modules. This section defines the environment variables and container create options that are required for a customer to successfully deploy the Microsoft Connected Cache module for use by Device Update for Azure IoT Hub.
14+
Microsoft Connected Cache (MCC) is deployed to Azure IoT Edge gateways as an IoT Edge module. Like other IoT Edge modules, environment variables and container create options are used to configure MCC modules. This article defines the environment variables and container create options that are required for a customer to successfully deploy the Microsoft Connected Cache module for use by Device Update for IoT Hub.
1515

16-
## Microsoft Connected Cache Azure IoT Edge module deployment details
16+
## Module deployment details
1717

18-
Naming of the Microsoft Connected Cache module is at the discretion of the administrator. There are no other module or service interactions that rely on the name of the module for communication. Additionally, the parent child relationship of the Microsoft Connected Cache servers is not dependent on this module name, but rather the FQDN or Ip address of the Azure IoT Edge gateway that has been configured as discussed earlier.
18+
There's no naming requirement for the Microsoft Connected Cache module since no other module or service interactions rely on the name of the MCC module for communication. Additionally, the parent-child relationship of the Microsoft Connected Cache servers isn't dependent on this module name, but rather the FQDN or IP address of the IoT Edge gateway.
1919

20-
Microsoft Connected Cache Azure IoT Edge Module Environment Variables are used to pass basic module identity information and functional module settings to the container.
20+
Microsoft Connected Cache module environment variables are used to pass basic module identity information and functional module settings to the container.
2121

22-
| Variable Name | Value Format | Required/Optional | Functionality |
23-
| ----------------------------- | ---------------------------------------| ----------------- | ------------------------------------------------ |
24-
| CUSTOMER_ID | Azure Subscription ID GUID | Required | This is the customer's key, which provides secure<br>authentication of the cache node to Delivery Optimization<br>Services.<br>Required in order for module to function. |
25-
| CACHE_NODE_ID | Cache Node ID GUID | Required | Uniquely identifies the Microsoft Connected Cache<br>node to Delivery Optimization Services.<br>Required in order<br> for module to function. |
26-
| CUSTOMER_KEY | Customer Key GUID | Required | This is the customer's key, which provides secure<br>authentication of the cache node to Delivery Optimization Services.<br>Required in order for module to function.|
27-
| STORAGE_*N*_SIZE_GB | Where N is the cache drive | Required | Specify up to 9 drives to cache content and specify the maximum space in<br>Gigabytes to allocate for content on each cache drive. Examples:<br>STORAGE_1_SIZE_GB = 150<br>STORAGE_2_SIZE_GB = 50<br>The number of the drive must match the cache drive binding values specified<br>in the Container Create Option MicrosoftConnectedCache*N* value<br>Minimum size of the cache is 10GB.|
28-
| UPSTREAM_HOST | FQDN/IP | Optional | This value can specify an upstream Microsoft Connected<br>Cache node that acts as a proxy if the Connected Cache node<br> is disconnected from the internet. This setting is used to support<br> the Nested IoT scenario.<br>**Note:** Microsoft Connected Cache listens on http default port 80.|
29-
| UPSTREAM_PROXY | FQDN/IP:PORT | Optional | The outbound internet proxy.<br>This could also be the OT DMZ proxy if an ISA 95 network. |
30-
| CACHEABLE_CUSTOM_*N*_HOST | HOST/IP<br>FQDN | Optional | Required to support custom package repositories.<br>Repositories could be hosted locally or on the internet.<br>There is no limit to the number of custom hosts that can be configured.<br><br>Examples:<br>Name = CACHEABLE_CUSTOM_1_HOST Value = packages.foo.com<br> Name = CACHEABLE_CUSTOM_2_HOST Value = packages.bar.com |
31-
| CACHEABLE_CUSTOM_*N*_CANONICAL| Alias | Optional | Required to support custom package repositories.<br>This value can be used as an alias and will be used by the cache server to reference<br>different DNS names. For example, repository content hostname may be packages.foo.com,<br>but for different regions there could be an additional prefix that is added to the hostname<br>like westuscdn.packages.foo.com and eastuscdn.packages.foo.com.<br>By setting the canonical alias, you ensure that content is not duplicated<br>for content coming from the same host, but different CDN sources.<br>The format of the canonical value is not important, but it must be unique to the host.<br>It may be easiest to set the value to match the host value.<br><br>Examples based on Custom Host examples above:<br>Name = CACHEABLE_CUSTOM_1_CANONICAL Value = foopackages<br> Name = CACHEABLE_CUSTOM_2_CANONICAL Value = packages.bar.com |
32-
| IS_SUMMARY_PUBLIC | True or False | Optional | Enables viewing of the summary report on the local network or internet.<br>Use of an API key (discussed later) is required to view the summary report if set to true. |
33-
| IS_SUMMARY_ACCESS_UNRESTRICTED| True or False | Optional | Enables viewing of summary report on the local network or internet without<br>use of API key from any device in the network. Use if you don't want to lock down access<br>to viewing cache server summary data via the browser. |
34-
35-
## Microsoft Connected Cache Azure IoT Edge module container create options
22+
| Variable name | Value format | Description |
23+
|--|--|--|--|
24+
| CUSTOMER_ID | Azure subscription ID GUID | Required <br><br> This is the customer's key, which provides secure authentication of the cache node to Delivery Optimization services. |
25+
| CACHE_NODE_ID | Cache node ID GUID | Required <br><br> Uniquely identifies the MCC node to Delivery Optimization services. |
26+
| CUSTOMER_KEY | Customer Key GUID | Required <br><br> This is the customer's key, which provides secure authentication of the cache node to Delivery Optimization services. |
27+
| STORAGE_*N*_SIZE_GB (Where *N* is the cache drive) | Integer | Required <br><br> Specify up to nine drives to cache content and specify the maximum space in gigabytes to allocate for content on each cache drive. The number of the drive must match the cache drive binding values specified in the container create option MicrosoftConnectedCache*N* value.<br><br>Examples:<br>STORAGE_1_SIZE_GB = 150<br>STORAGE_2_SIZE_GB = 50<br><br>Minimum size of the cache is 10 GB. |
28+
| UPSTREAM_HOST | FQDN/IP | Optional <br><br> This value can specify an upstream MCC node that acts as a proxy if the Connected Cache node is disconnected from the internet. This setting is used to support the nested IoT scenario.<br><br>**Note:** MCC listens on http default port 80. |
29+
| UPSTREAM_PROXY | FQDN/IP:PORT | Optional <br><br> The outbound internet proxy. This could also be the OT DMZ proxy of an ISA 95 network. |
30+
| CACHEABLE_CUSTOM_*N*_HOST | HOST/IP<br>FQDN | Optional <br><br> Required to support custom package repositories. Repositories could be hosted locally or on the internet. There's no limit to the number of custom hosts that can be configured.<br><br>Examples:<br>Name = CACHEABLE_CUSTOM_1_HOST Value = packages.foo.com<br> Name = CACHEABLE_CUSTOM_2_HOST Value = packages.bar.com |
31+
| CACHEABLE_CUSTOM_*N*_CANONICAL | Alias | Optional <br><br> Required to support custom package repositories. This value can be used as an alias and will be used by the cache server to reference different DNS names. For example, repository content hostname may be packages.foo.com, but for different regions there could be an extra prefix that is added to the hostname like westuscdn.packages.foo.com and eastuscdn.packages.foo.com. By setting the canonical alias, you ensure that content isn't duplicated for content coming from the same host, but different CDN sources. The format of the canonical value isn't important, but it must be unique to the host. It may be easiest to set the value to match the host value.<br><br>Examples based on Custom Host examples above:<br>Name = CACHEABLE_CUSTOM_1_CANONICAL Value = foopackages<br> Name = CACHEABLE_CUSTOM_2_CANONICAL Value = packages.bar.com |
32+
| IS_SUMMARY_PUBLIC | True or False | Optional <br><br> Enables viewing of the summary report on the local network or internet. Use of an API key (discussed later) is required to view the summary report if set to true. |
33+
| IS_SUMMARY_ACCESS_UNRESTRICTED | True or False | Optional <br><br> Enables viewing of summary report on the local network or internet without use of API key from any device in the network. Use if you don't want to lock down access to viewing cache server summary data via the browser. |
3634

37-
Container create options for MCC module deployment provide control of the settings related to storage and ports used by the MCC module. This is the list of required container created variables used to deploy MCC.
35+
## Module container create options
3836

39-
### Container to host OS drive mappings
37+
Container create options provide control of the settings related to storage and ports used by the Microsoft Connected Cache module.
4038

41-
Required to map the container storage location to the storage location on the disk.< Up to nine locations can be specified.
42-
43-
>[!Note]
44-
>The number of the drive must match the cache drive binding values specified in the environment variable STORAGE_*N*_SIZE_GB value, ```/MicrosoftConnectedCache*N*/:/nginx/cache*N*/```
45-
46-
### Container to host TCP port mappings
47-
48-
This option specifies the external machine http port that MCC listens on for content requests. The default HostPort is port 80 and other ports are not supported at this time as the ADU client makes requests on port 80 today. TCP port 8081 is the internal container port that the MCC listens on and cannot be changed.
49-
50-
### Container service TCP port mappings
51-
52-
The Microsoft Connected Cache module has a .NET Core service, which is used by the caching engine for various functions.
53-
54-
>[!Note]
55-
>To support Azure IoT Nested Edge the HostPort must not be set to 5000 because the Registry proxy module is already listening on host port 5000.
56-
57-
58-
Sample Container Create Options
39+
Sample container create options:
5940

6041
```json
6142
{
@@ -79,14 +60,31 @@ Sample Container Create Options
7960
}
8061
```
8162

63+
The following sections list the required container create variables used to deploy the MCC module.
64+
65+
### HostConfig
66+
67+
The `HostConfig` parameters are required to map the container storage location to the storage location on the disk. Up to nine locations can be specified.
68+
69+
>[!Note]
70+
>The number of the drive must match the cache drive binding values specified in the environment variable STORAGE_*N*_SIZE_GB value, `/MicrosoftConnectedCache*N*/:/nginx/cache*N*/`.
71+
72+
### PortBindings
73+
74+
The `PortBindings` parameters map container ports to ports on the host device.
75+
76+
The first port binding specifies the external machine HTTP port that MCC listens on for content requests. The default HostPort is port 80 and other ports aren't supported at this time as the ADU client makes requests on port 80 today. TCP port 8081 is the internal container port that the MCC listens on and can't be changed.
77+
78+
The second port binding ensures that the container isn't listening on host port 5000. The Microsoft Connected Cache module has a .NET Core service, which is used by the caching engine for various functions. To support nested edge, the HostPort must not be set to 5000 because the registry proxy module is already listening on host port 5000.
79+
8280
## Microsoft Connected Cache summary report
8381

84-
The summary report is currently the only way for a customer to view caching data for the Microsoft Connected Cache instances deployed to Azure IoT Edge gateways. The report is generated at 15-second intervals and includes averaged stats for the period as well as aggregated stats for the lifetime of the module. The key stats that customers will be interested in are:
82+
The summary report is currently the only way for a customer to view caching data for the Microsoft Connected Cache instances deployed to IoT Edge gateways. The report is generated at 15-second intervals and includes averaged stats for the period and aggregated stats for the lifetime of the module. The key stats that customers will be interested in are:
8583

86-
* **hitBytes** - This is the sum of bytes delivered that came directly from cache.
87-
* **missBytes** - This is the sum of bytes delivered that Microsoft Connected Cache had to download from CDN to see the cache.
88-
* **eggressBytes** - This is the sum of hitBytes and missBytes and is the total bytes delivered to clients.
89-
* **hitRatioBytes** - This is the ratio of hitBytes to egressBytes. If 100% of eggressBytes delivered in a period were equal to the hitBytes this would be 1 for example.
84+
* **hitBytes** - The sum of bytes delivered that came directly from cache.
85+
* **missBytes** - The sum of bytes delivered that Microsoft Connected Cache had to download from CDN to see the cache.
86+
* **eggressBytes** - The sum of hitBytes and missBytes and is the total bytes delivered to clients.
87+
* **hitRatioBytes** - The ratio of hitBytes to egressBytes. For example, if 100% of eggressBytes delivered in a period were equal to the hitBytes, this value would be 1.
9088

9189

92-
The summary report is available at `http://<FQDN/IP of Azure IoT Edge Gateway hosting MCC>:5001/summary` Replace \<Azure IoT Edge Gateway IP\> with the IP address or hostname of your IoT Edge gateway. (see environment variable details for information on visibility of this report).
90+
The summary report is available at `http://<IoT Edge gateway>:5001/summary` Replace \<IoT Edge Gateway\> with the IP address or hostname of the IoT Edge gateway hosting the MCC module.

0 commit comments

Comments
 (0)