Schnellstart: Bereitstellen einer verbundenen Registrierung auf einem IoT Edge-Gerät

Artikel
10/31/2023

In dieser Schnellstartanleitung verwenden Sie die Azure CLI, um eine verbundene Registrierung als Modul auf einem Azure IoT Edge-Gerät bereitzustellen. Das IoT Edge-Gerät kann auf die übergeordnete Azure Container Registry in der Cloud zugreifen.

Eine Übersicht über die Verwendung einer verbundenen Registrierung mit IoT Edge finden Sie unter Verwenden einer verbundenen Registrierung mit Azure IoT Edge. Dieses Szenario entspricht einem Gerät auf der obersten Ebene einer IoT Edge-Hierarchie.

Voraussetzungen

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Azure IoT Hub- und IoT Edge-Gerät Die Bereitstellungsschritte finden Sie unter Schnellstart: Bereitstellen Ihres ersten IoT Edge-Moduls auf einem virtuellen Linux-Gerät.

Wichtig

Stellen Sie sicher, dass Sie die Ports 8000, 5671 und 8883 auf dem Gerät öffnen, um später auf die Module zugreifen zu können, die auf dem IoT Edge-Gerät bereitgestellt werden. Die Konfigurationsschritte finden Sie unter Öffnen von Ports zu einem virtuellen Computer mit dem Azure-Portal.
Verbundene Registrierungsressource in Azure. Informationen zu den Bereitstellungsschritten finden Sie unter Schnellstarts mit der Azure CLI oder dem Azure Portal.
- In diesem Szenario kann eine verbundene Registrierung im Modus ReadWrite oder ReadOnly verwendet werden.
- In den Befehlen in diesem Artikel ist der Name der verbundenen Registrierung in der Umgebungsvariablen CONNECTED_REGISTRY_RW gespeichert.

Importieren von Images in die Cloudregistrierung

Importieren Sie mit dem Befehl az acr import die folgenden Containerimages in Ihre Cloudregistrierung. Überspringen Sie diesen Schritt, wenn Sie diese Images bereits importiert haben.

Image der verbundenen Registrierung

Um geschachtelte IoT Edge-Szenarien zu unterstützen, muss das Containerimage der Runtime der verbundenen Registrierung in Ihrer privaten Azure-Containerregistrierung verfügbar sein. Mit dem Befehl az acr import können Sie das Image der verbundenen Registrierung in Ihre private Registrierung importieren.

# 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

Images von IoT Edge- und API-Proxy

Um die verbundene Registrierung für geschachteltes IoT Edge zu unterstützen, müssen Sie Module für den IoT Edge- und API-Proxy bereitstellen. Importieren Sie diese Images in Ihre private Registrierung.

Das IoT Edge- und API-Proxymodul ermöglicht einem IoT Edge Gerät, mehrere Dienste über das HTTPS-Protokoll am selben Port verfügbar zu machen, z. B. 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

Image „hello-world“

Importieren Sie das Image, um die verbundene Registrierung hello-world zu testen. Dieses Repository wird mit der verbundenen Registrierung synchronisiert und von den verbundenen Registrierungsclients gepullt.

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

Abrufen der verbundenen Registrierungskonfiguration

Bevor Sie die verbundene Registrierung auf dem IoT Edge-Gerät bereitstellen, müssen Sie die Konfigurationseinstellungen aus der verbundenen Registrierungsressource in Azure abrufen.

Verwenden Sie den Befehl az acr connected-registry get-settings, um die Einstellungsinformationen abzurufen, die zum Installieren einer verbundenen Registrierung erforderlich sind. Im folgenden Beispiel wird HTTPS als übergeordnetes Protokoll angegeben. Dieses Protokoll ist erforderlich, wenn die übergeordnete Registrierung eine Cloudregistrierung ist.

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

Standardmäßig enthalten die Einstellungsinformationen nicht das Sync-Token-Kennwort, das ebenfalls für die Bereitstellung der verbundenen Registrierung benötigt wird. Optional können Sie eines der Passwörter generieren, indem Sie den Parameter --generate-password 1 oder generate-password 2 übergeben. Speichern Sie das generierte Passwort an einem sicheren Ort. Sie kann nicht wieder abgerufen werden.

Warnung

Durch die Neuerstellung eines Kennworts werden die Sync-Token-Anmeldeinformationen ausgetauscht. Wenn Sie ein Gerät mit dem vorherigen Passwort konfiguriert haben, müssen Sie die Konfiguration aktualisieren.

Die Befehlsausgabe umfasst die Registrierungsverbindungszeichenfolge und die zugehörigen Einstellungen. Die folgende Beispielausgabe zeigt die Verbindungszeichenfolge für die verbundene Registrierung namens myconnectedregistry mit der übergeordneten Registrierung contosoregistry:

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

Konfigurieren eines Bereitstellungsmanifests für IoT Edge

Ein Bereitstellungsmanifest ist ein JSON-Dokument, das beschreibt, welche Module auf dem IoT Edge-Gerät bereitgestellt werden sollen. Weitere Informationen finden Sie unter Verstehen, wie IoT Edge-Module verwendet, konfiguriert und wiederverwendet werden können.

Um die verbundenen Registrierungs- und API-Proxymodule mithilfe der Azure CLI bereitzustellen, speichern Sie das folgende Bereitstellungsmanifest lokal als manifest.json-Datei. Sie verwenden den Dateipfad im nächsten Abschnitt, wenn Sie den Befehl zum Anwenden der Konfiguration auf Ihr Gerät ausführen.

Einstellungen für verbundene Registrierungsmodule

Verwenden Sie die Token-Anmeldeinformationen und die Verbindungszeichenfolge aus den vorherigen Abschnitten, um die relevanten JSON-Werte im env Knoten zu aktualisieren.

Die folgenden Umgebungsvariablen sind optional im env Knoten:

Variable	BESCHREIBUNG
`ACR_REGISTRY_LOGIN_SERVER`	Gibt einen eindeutigen Hostnamen oder FQDN an. Bei Verwendung akzeptiert die verbundene Registrierung nur Anforderungen, die an diesen Anmeldeserverwert gesendet werden. Wenn kein Wert angegeben wird, kann auf die verbundene Registrierung mit einem beliebigen Anmeldeserverwert zugegriffen werden.
`ACR_REGISTRY_CERTIFICATE_VOLUME`	Wenn auf Ihre verbundene Registrierung über HTTPS zugegriffen werden kann, verweist sie auf das Verzeichnis, auf dem die HTTPS-Zertifikate gespeichert sind. Wenn nicht festgelegt, ist der Standardspeicherort `/var/acr/certs`.
`ACR_REGISTRY_DATA_VOLUME`	Überschreibt den Standardspeicherort `/var/acr/data`, an dem die Images von der verbundenen Registrierung gespeichert werden. Dieser Speicherort muss mit der Verzeichnisbindung für den Container übereinstimmen.

Wichtig

Wenn die verbundene Registrierung auf einen anderen Port als 80 und 443 lauscht, muss der Wert ACR_REGISTRY_LOGIN_SERVER (sofern angegeben) den Port enthalten. Beispiel: 192.168.0.100:8080.

Wenn das API-Proxymodul nicht verwendet wird, sollte eine HostPort Bindung für die verbundene Registrierung festgelegt werden. Beispiel:

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

API-Proxymodul Einstellungen

Der API-Proxy lauscht auf Port 8000, der als NGINX_DEFAULT_PORT konfiguriert ist. Weitere Informationen zu den API-Proxyeinstellungen finden Sie im IoT Edge GitHub Repository.

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

Bereitstellen der verbundenen Registrierungs- und API-Proxymodule auf IoT Edge

Verwenden Sie den folgenden Befehl, um die verbundenen Registrierungs- und API-Proxymodule auf dem IoT Edge-Gerät bereitzustellen, indem Sie das im vorherigen Abschnitt erstellte Bereitstellungsmanifest verwenden. Stellen Sie die ID des IoT Edge-Geräts der obersten Ebene und den IoT Hub-Namen bereit, sofern angegeben.

# 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

Einzelheiten finden Sie unter Bereitstellen von Azure IoT Edge-Modulen mit der Azure CLI.

Um den Status der verbundenen Registrierung zu überprüfen, verwenden Sie den folgenden az acr connected-registry show-Befehl: Der Name der verbundenen Registrierung ist der Wert von $CONNECTED_REGISTRY_RW.

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

Nach erfolgreicher Bereitstellung weist die verbundene Registrierung den Status Online auf.

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie eine verbundene Registrierung für ein IoT Edge-Gerät bereitstellen. Fahren Sie mit den nächsten Leitfäden fort, um zu erfahren, wie Sie Images aus der neu bereitgestellten verbundenen Registrierung pullen oder die verbundene Registrierung auf geschachtelten IoT Edge-Geräten bereitstellen.

Pullen von Images aus einer verbundenen Registrierung

Tutorial: Bereitstellen einer verbundenen Registrierung auf geschachtelten IoT Edge-Geräten