快速入門：將已連線的登錄部署至 IoT Edge 裝置

發行項
10/31/2023

在本快速入門中，您會使用 Azure CLI 將已連線登錄部署為 Azure IoT Edge 裝置上的模組。 IoT Edge 裝置可存取雲端中的父代 Azure 容器登錄。

如需搭配使用連線的登錄與 IoT Edge 的概觀，請參閱搭配使用連線的登錄與 Azure IoT Edge。此情節會對應至 IoT Edge 階層最上層的裝置。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

Azure IoT 中樞和 IoT Edge 裝置。若需了解部署步驟，請參閱快速入門：將您的第一個 IoT Edge 模組部署至虛擬 Linux 裝置。

重要

若後續要存取部署於 IoT Edge 裝置上的模組，請確實開啟裝置上的 8000、5671 和 8883 連接埠。如需設定步驟，請參閱如何使用 Azure 入口網站開啟對虛擬機器的連接埠。
Azure 中連線的登錄資源。如需部署步驟，請參閱使用 Azure CLI 或 Azure 入口網站的快速入門。
- 在此情節中，可使用 ReadWrite 或 ReadOnly 模式中的已連線登錄。
- 在本文的命令中，連線的登錄名稱儲存在環境變數 CONNECTED_REGISTRY_RW 中。

將映像匯入至雲端登錄

使用 az acr import 命令，將下列容器映像匯入至您的雲端登錄。如果您已匯入這些映像，請略過此步驟。

連線的登錄映像

若要支援巢狀 IoT Edge 案例，連線登錄執行階段的容器映像必須可在您的私人 Azure 容器登錄中使用。使用 az acr import 命令，將連線的登錄映像匯入您的私人登錄中。

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry
REGISTRY_NAME=<container-registry-name>

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/acr/connected-registry:0.8.0

IoT Edge 和 API Proxy 映像

若要在巢狀 IoT Edge 上支援連線的登錄，您必須為 IoT Edge 和 API Proxy 部署模組。將這些映像匯入您的私人登錄中。

IoT Edge API Proxy 模組可讓 IoT Edge 裝置使用 HTTPS 通訊協定在相同的連接埠 (例如 443) 上公開多個服務。

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-agent:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-hub:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-api-proxy:1.1.2

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-diagnostics:1.2.4

hello-world 映像

若要測試連線的登錄，請匯入 hello-world 映像。此存放庫將會同步處理至連線的登錄，並由連線的登錄用戶端提取。

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/hello-world:1.1.2

擷取連線的登錄設定

將已連線登錄部署至階層中的 IoT Edge 裝置之前，您必須從 Azure 中的連線登錄資源擷取組態設定。

使用 az acr connected-registry get-settings 命令來取得安裝已連線登錄所需的設定資訊。下列範例會將 HTTPS 指定為父代通訊協定。當父代登錄是雲端登錄時，需要此通訊協定。

az acr connected-registry get-settings \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --parent-protocol https

根據預設，設定資訊不包含同步權杖密碼，而在部署連線的登錄時也需要此密碼。選擇性地傳遞 --generate-password 1 或 generate-password 2 參數以產生其中一個密碼。將產生的密碼儲存到安全的位置。該密碼無法再次擷取。

警告

若重新產生密碼，將會輪換同步權杖認證。如果您使用先前的密碼來設定裝置，則需要更新設定。

命令輸出包含登錄連接字串和相關設定。下列範例輸出顯示名為 myconnectedregistry、且父登錄為 contosoregistry 之連線登錄的連接字串：

{
  "ACR_REGISTRY_CONNECTION_STRING": "ConnectedRegistryName=myconnectedregistry;SyncTokenName=myconnectedregistry-sync-token;SyncTokenPassword=xxxxxxxxxxxxxxxx;ParentGatewayEndpoint=contosoregistry.eastus.data.azurecr.io;ParentEndpointProtocol=https"
}

設定 IoT Edge 的部署資訊清單

部署資訊清單是一份 JSON 文件，說明要部署至 IoT Edge 裝置的模組。如需詳細資訊，請參閱了解如何使用、設定以及重複使用 IoT Edge 模組。

若要使用 Azure CLI 部署已連線登錄和 API Proxy 模組，請將下列部署資訊清單儲存在本機作為 manifest.json 檔案。若要執行命令以將設定套用至裝置，您會使用到下一節中的檔案路徑。

連線的登錄模組設定

使用先前幾節中的權杖認證和連接字串，更新 env 節點中的相關 JSON 值。

在節點 env 中，下列環境變數是選擇性的：

變數	描述
`ACR_REGISTRY_LOGIN_SERVER`	指定唯一的主機名稱或 FQDN。如果使用，連線的登錄只會接受對此登入伺服器值提出的要求。若未提供任何值，則可以使用任何登入伺服器值來存取連線的登錄。
`ACR_REGISTRY_CERTIFICATE_VOLUME`	如果連線的登錄可透過 HTTPS 來存取，請指向 HTTPS 憑證存放所在的磁碟區。若未設定，預設位置為 `/var/acr/certs`。
`ACR_REGISTRY_DATA_VOLUME`	覆寫連線的登錄將儲存映像的預設位置 `/var/acr/data`。此位置必須符合容器的磁碟區繫結。

重要

如果連線的登錄接聽 80 和 443 以外的連接埠，則 ACR_REGISTRY_LOGIN_SERVER 值 (如果指定) 必須包含該連接埠。範例：192.168.0.100:8080。

若未使用 API Proxy 模組，則應為連線的登錄設定 HostPort 繫結。範例：

 "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"],\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"8080\"}]}}}"

API Proxy 模組設定

API Proxy 會在設定為 NGINX_DEFAULT_PORT 的連接埠 8000 上接聽。如需 API Proxy 設定的詳細資訊，請參閱 IoT Edge GitHub 存放庫。

{
    "modulesContent": {
        "$edgeAgent": {
            "properties.desired": {
                "modules": {
                    "connected-registry": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/acr/connected-registry:0.8.0",
                            "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"]}}"
                        },
                        "type": "docker",
                        "env": {
                            "ACR_REGISTRY_CONNECTION_STRING": {
                                "value": "ConnectedRegistryName=<REPLACE_WITH_CONNECTED_REGISTRY_NAME>;SyncTokenName=<REPLACE_WITH_SYNC_TOKEN_NAME>;SyncTokenPassword=REPLACE_WITH_SYNC_TOKEN_PASSWORD;ParentGatewayEndpoint=<REPLACE_WITH_CLOUD_REGISTRY_NAME>.<REPLACE_WITH_CLOUD_REGISTRY_REGION>.data.azurecr.io;ParentEndpointProtocol=https"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    },
                    "IoTEdgeAPIProxy": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-api-proxy:1.1.2",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8000/tcp\":[{\"HostPort\":\"8000\"}]}}}"
                        },
                        "type": "docker",
                        "env": {
                            "NGINX_DEFAULT_PORT": {
                                "value": "8000"
                            },
                            "CONNECTED_ACR_ROUTE_ADDRESS": {
                                "value": "connected-registry:8080"
                            },
                            "BLOB_UPLOAD_ROUTE_ADDRESS": {
                                "value": "AzureBlobStorageonIoTEdge:11002"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    }
                },
                "runtime": {
                    "settings": {
                        "minDockerVersion": "v1.25",
                        "registryCredentials": {
                            "cloudregistry": {
                                "address": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io",
                                "password": "<REPLACE_WITH_SYNC_TOKEN_PASSWORD>",
                                "username": "<REPLACE_WITH_SYNC_TOKEN_NAME>"
                            }
                        }
                    },
                    "type": "docker"
                },
                "schemaVersion": "1.1",
                "systemModules": {
                    "edgeAgent": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-agent:1.2.4",
                            "createOptions": ""
                        },
                        "type": "docker",
                        "env": {
                            "SendRuntimeQualityTelemetry": {
                                "value": "false"
                            }
                        }
                    },
                    "edgeHub": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-hub:1.2.4",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
                        },
                        "type": "docker",
                        "status": "running",
                        "restartPolicy": "always"
                    }
                }
            }
        },
        "$edgeHub": {
            "properties.desired": {
                "routes": {
                    "route": "FROM /messages/* INTO $upstream"
                },
                "schemaVersion": "1.1",
                "storeAndForwardConfiguration": {
                    "timeToLiveSecs": 7200
                }
            }
        }
    }
}

在 IoT Edge 上部署已連線登錄和 API Proxy 模組

使用下列命令，使用上一節中建立的部署資訊清單，在 IoT Edge 裝置上部署已連線登錄和 API Proxy 模組。提供 IoT Edge 最上層裝置的識別碼，以及所指出IoT 中樞的名稱。

# Set the IOT_EDGE_TOP_LAYER_DEVICE_ID and IOT_HUB_NAME environment variables for use in the following Azure CLI command
IOT_EDGE_TOP_LAYER_DEVICE_ID=<device-id>
IOT_HUB_NAME=<hub-name>

az iot edge set-modules \
  --device-id $IOT_EDGE_TOP_LAYER_DEVICE_ID \
  --hub-name $IOT_HUB_NAME \
  --content manifest.json

如需詳細資訊，請參閱使用 Azure CLI 部署 Azure IoT Edge 模組。

若要檢查已連線登錄狀態，請使用以下 az acr connected-registry show 命令。已連線登錄的名稱是 $CONNECTED_REGISTRY_RW的值。

az acr connected-registry show \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --output table

成功部署之後，連線的登錄會顯示 Online 的狀態。

下一步

在本快速入門中，您已了解如何將連線的登錄部署至 IoT Edge 裝置。繼續進行下一個指南，了解如何從新部署的已連線登錄提取影像，或在巢狀 IoT Edge 裝置上部署已連線登錄。

從連線的登錄提取映像

教學課程：將已連線的登錄部署至巢狀 IoT Edge 裝置

Share via