Tipps und Tools für die Problembehandlung ihrer Azure IoT Einsatz-Instanz

In diesem Artikel wird beschrieben, wie Sie einige gängige Tools verwenden, wenn Sie Ihre Azure IoT Einsatz Instanzen erlernen, untersuchen oder beheben. Diese Tools sind zusätzlich zu den Funktionen, die vom Azure-Portal, Azure CLI, der Webbenutzeroberfläche für Vorgänge und Observability Resources bereitgestellt werden.

Kubernetes-Tools

Azure IoT Einsatz Komponenten werden in einem Kubernetes-Standardcluster ausgeführt. Sie können die CLI-Tools kubectl und k9s verwenden, um mit Ihrem Cluster zu interagieren und ihn zu verwalten.

Verwalten von Komponenten mithilfe von Kubernetes-Bereitstellungsmanifesten

Von Bedeutung

Die Verwendung von Kubernetes-Bereitstellungsmanifesten wird in Produktionsumgebungen nicht unterstützt und sollte nur zum Debuggen und Testen verwendet werden.

Im Allgemeinen nutzt Azure IoT Einsatz die Azure Arc-Plattform, um eine hybride Cloudumgebung bereitzustellen, in der Sie die Konfiguration über den Azure Resource Manager (ARM) und Front-End-Tools wie das Azure-Portal, Bicep und die Azure CLI verwalten können.

In einer Debug- oder Testumgebung können Sie jedoch die Komponenten von Azure IoT Einsatz mithilfe von YAML Kubernetes-Bereitstellungsmanifesten verwalten. Dies bedeutet, dass Sie Tools wie kubectl verwenden können, um einige Komponenten von Azure IoT Einsatz zu verwalten. Dieses Feature hat einige Einschränkungen:

  • Sofern Sie die Ressourcensynchronisierung nicht in Azure IoT Einsatz mithilfe des Befehls az iot ops enable-rsync aktivieren, werden Änderungen, die an den Ressourcen mit Kubernetes-Bereitstellungsmanifesten vorgenommen wurden, nicht mit Azure synchronisiert. Weitere Informationen zur Ressourcensynchronisierung finden Sie unter "Ressourcensynchronisierung".
  • Auch wenn die Ressourcensynchronisierung aktiviert ist, werden brandneue Ressourcen, die mit Kubernetes-Bereitstellungsmanifesten erstellt wurden, nicht mit Azure synchronisiert. Es werden nur Änderungen an vorhandenen Ressourcen synchronisiert.

Von Bedeutung

In der Produktion ist die Cloud immer die Quelle der Wahrheit. Erstellen und ändern Sie Ressourcen immer über Azure – mithilfe der Betriebsoberfläche, des Azure Portals, der Azure CLI oder ARM/Bicep-Vorlagen. Das Direkte Erstellen von Ressourcen auf dem Cluster oder das Bearbeiten vorhandener benutzerdefinierter Kubernetes-Ressourcen kann dazu führen, dass die Cloud und der Edge nicht mehr synchronisiert werden und in Produktionsumgebungen nicht unterstützt werden.

kubectl

kubectl ist das Kubernetes-Befehlszeilentool zum Verwalten Ihres Clusters. Es verfügt über viele Funktionen, über die Sie in der offiziellen Kubernetes-Dokumentation mehr erfahren können. In diesem Artikel werden die allgemeinen Verwendungsmöglichkeiten für kubectl beschrieben, wenn Sie mit Azure IoT Einsatz arbeiten, z. B. das Auflisten der ausgeführten Pods und das Anzeigen von Protokollen.

Konfigurieren von kubectl zum Herstellen einer Verbindung mit Ihrer Instanz

Im Artikel Prepare your Azure Arc-enabled Kubernetes cluster wird beschrieben, wie Sie kubectl konfigurieren, um eine Verbindung mit Ihrem k3sCluster herzustellen, wenn Sie kubectl Befehle auf demselben Computer ausführen, auf dem Sie Ihren Kubernetes-Cluster bereitgestellt haben.

Tipp

Fügen Sie den Befehl export KUBECONFIG=~/.kube/config zu Ihrer .bashrc- oder .bash_profile-Datei hinzu, damit Sie die Umgebungsvariable KUBECONFIG nicht jedes Mal festlegen müssen, wenn Sie ein neues Terminalfenster öffnen.

Wenn Sie Ihre Azure IoT Einsatz Instanz in einem Arc-fähigen AKS-EE implementiert haben, wird die Konfiguration kubectl automatisch für Sie eingerichtet. Sie können kubectl-Befehle direkt über die Befehlszeile auf dem Computer ausführen, auf dem Sie Ihren Cluster bereitgestellt haben.

Es ist auch möglich, kubectl-Befehle von Ihrem lokalen Clientcomputer auszuführen anstelle des Computers, auf dem Sie Ihren Arc-fähigen Cluster bereitgestellt haben:

Verwenden Sie als einmaliger Schritt SSH, um eine Verbindung mit dem Computer herzustellen, auf dem Sie Ihren Cluster bereitgestellt haben, und führen Sie die folgenden Befehle aus. Achten Sie darauf, dass Sie <your-name> mit Ihrem Namen ersetzen:

kubectl create serviceaccount <your-name> -n default
kubectl create clusterrolebinding <your-name>-binding --clusterrole cluster-admin --serviceaccount default:<your-name>
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
    name: <your-name>-secret
    annotations:
        kubernetes.io/service-account.name: <your-name>
type: kubernetes.io/service-account-token
EOF
TOKEN=$(kubectl get secret <your-name>-secret -o jsonpath='{$.data.token}' | base64 -d | sed 's/$/\n/g')
echo $TOKEN

Notieren Sie sich das Token. Sie verwenden dieses Token, um sich bei der Ausführung von kubectl-Befehlen auf dem Clientcomputer zu authentifizieren. Sie können jetzt die Verbindung mit dem Computer trennen, auf dem Ihr Kubernetes-Cluster ausgeführt wird.

Um kubectl zum Herstellen einer Verbindung mit dem Cluster auf Ihrem Clientcomputer zu verwenden, öffnen Sie zwei Terminals:

  1. Führen Sie im ersten Terminal den folgenden Befehl aus, um einen Proxy für die Verbindung mit Ihrem Cluster zu konfigurieren. Achten Sie darauf, die Werte für die drei Platzhalter zu ersetzen:

    az connectedk8s proxy -n <your-arc-enabled-cluster-name> -g <your-arc-enabled-cluster-resource-group> --token <token-from-previous-step>

    Lassen Sie dieses Terminal geöffnet, während Sie kubectl-Befehle im zweiten Terminal ausführen.

  2. Im zweiten Terminal können Sie die kubectl-Befehle für Ihren Remotecluster ausführen. Listen Sie beispielsweise die Pods im azure-iot-operations-Namespace auf:

    kubectl get pods -n azure-iot-operations

    Tipp

    Sie können auch Befehle ausführen, z. B. k9s, die die Konfiguration kubectl in diesem Terminal verwenden.

    Der Kontext kubectl bleibt auf den Remote-Cluster festgelegt, bis Sie Ihren ersten Terminal schließen.

Weitere Informationen finden Sie unter Verwenden Sie Cluster Connect, um eine sichere Verbindung zu Azure Arc-fähigen Kubernetes-Clustern herzustellen.

Namensräume

Standardmäßig verwenden Arc und Azure IoT Einsatz die folgenden Namespaces im Kubernetes-Cluster:

  • azure-iot-operations für die Azure IoT Betriebskomponenten.
  • azure-arc für die Azure Arc-fähigen Kubernetes-Komponenten.

Tipp

Führen Sie den folgenden Befehl aus, um alle Namespaces in Ihrem Cluster anzuzeigen: kubectl get namespaces.

Häufige kubectl-Befehle

Führen Sie den folgenden Befehl aus, um alle im Namespace azure-iot-operations ausgeführten Pods anzuzeigen:

kubectl get pods -n azure-iot-operations

Die Ausgabe sieht wie folgt aus:

NAME                                              READY   STATUS      RESTARTS       AGE
adr-schema-registry-0                             2/2     Running     0              19m
adr-schema-registry-1                             2/2     Running     0              19m
aio-akri-agent-777477bc68-72lrg                   1/1     Running     7 (83m ago)    21d
aio-broker-authentication-0                       1/1     Running     7 (83m ago)    21d
aio-broker-backend-1-0                            1/1     Running     11 (82m ago)   21d
aio-broker-backend-1-1                            1/1     Running     7 (83m ago)    21d
aio-broker-diagnostics-probe-0                    1/1     Running     11 (83m ago)   21d
aio-broker-diagnostics-service-0                  1/1     Running     7 (83m ago)    21d
aio-broker-fluent-bit-6bkf2                       1/1     Running     0              16m
aio-broker-frontend-0                             1/1     Running     12 (83m ago)   21d
aio-broker-health-manager-0                       1/1     Running     14 (82m ago)   21d
aio-broker-operator-0                             1/1     Running     7 (83m ago)    21d
aio-broker-upgrade-status-job-1.0.4-bwlcc         0/1     Completed   0              77m
aio-broker-webhook-admission-65d67f8ddc-jct9j     1/1     Running     0              82m
aio-dataflow-admission-webhook-84dd44c8bd-6pw58   1/1     Running     7 (83m ago)    21d
aio-dataflow-operator-0                           1/1     Running     14 (83m ago)   21d
aio-dataflow-upgrade-status-job-1.0.5-msmf4       0/1     Completed   0              77m
aio-opc-asset-discovery-54649d46cf-kb6qs          1/1     Running     2 (83m ago)    17d
aio-opc-media-1-785748ff6c-qkhgl                  1/1     Running     1 (83m ago)    14d
aio-opc-opc.tcp-1-858b9ff67-dxwvb                 1/1     Running     4 (80m ago)    17d
aio-opc-supervisor-5d6b9bfc49-fgt7d               1/1     Running     2 (83m ago)    17d
aio-operator-7b9b585dc6-bvfpd                     2/2     Running     0              19m
aio-usage-28946280-f42k8                          0/1     Completed   0              14d
aio-usage-28946340-45grx                          0/1     Completed   0              14d
aio-usage-28946400-znn7v                          0/1     Completed   0              13d
aio-usage-28946460-nrw4z                          0/1     Completed   0              13d
aio-usage-28966500-mrcmf                          0/1     Completed   0              55m

Führen Sie den folgenden Befehl aus, um die Protokolle für einen bestimmten Pod anzuzeigen, z. B. den Pod aio-opc-opc.tcp-1-858b9ff67-dxwvb:

kubectl logs aio-opc-opc.tcp-1-858b9ff67-dxwvb -n azure-iot-operations

Führen Sie den folgenden Befehl aus, um eine menschenlesbare Beschreibung für einen bestimmten Pod anzuzeigen, z. B. den Pod aio-opc-opc.tcp-1-858b9ff67-dxwvb:

kubectl describe pod aio-opc-opc.tcp-1-858b9ff67-dxwvb -n azure-iot-operations

An einigen Stellen verwendet die Azure IoT Einsatz-Dokumentation den Befehl kubectl apply, um eine Kubernetes-Manifestdatei anzuwenden, um eine Konfigurationsänderung im Cluster vorzunehmen.

k9s

Das Hilfsprogramm k9s bietet eine terminalbasierte Benutzeroberfläche zum Verwalten Ihres Kubernetes-Clusters. Es verwendet Ihre kubectl-Konfiguration, um eine Verbindung mit Ihrem Cluster herzustellen und bietet eine visuelle Möglichkeit, mit Ihrem Cluster zu interagieren. Die Standardansicht listet alle derzeit in Ihrem Cluster ausgeführten Pods auf:

Screenshot: Standardansicht von k9s.

Wenn Sie mit Azure IoT Einsatz arbeiten, können Sie die Ansicht filtern, um nur die Pods im namespace azure-iot-operations anzuzeigen.

  1. Geben Sie : ein, um den Befehlsbereich zu öffnen, anschließend ns, und drücken Sie die Eingabetaste.

  2. Wählen Sie in der Liste der Namespaces azure-iot-operations aus, und drücken Sie die Eingabetaste.

  3. Die Liste der Pods zeigt jetzt nur die Pods im azure-iot-operations-Namespace an:

    Screenshot: Liste der k9s-Pods, die nach dem Namespace „azure-iot-operations“ gefiltert sind.

Tipp

Sie können jetzt die Zahlentasten verwenden, um Filter anzuwenden. Der vorherige Screenshot zeigt, dass 0 alle Pods und 1 nur die Pods im azure-iot-operations-Namespace anzeigt.

Sie können Tastenkombinationen verwenden, um Informationen zu Ihren Pods anzuzeigen. Zum Beispiel:

  • Um einen Pod zu beschreiben, wählen Sie ihn in der Liste aus, und drücken Sie d.

    Screenshot: Beschreibung eines ausgeführten Pods in k9s.

  • Um die Protokolle für einen Pod anzuzeigen, wählen Sie sie in der Liste aus, und drücken Sie l.

    Screenshot, der die Logdatei eines laufenden Pods in k9s zeigt.

    Tipp

    Sie können die Zahlentasten verwenden, um in der Protokolldatei zu navigieren.

Um benutzerdefinierte Ressourcentypen im Cluster anzuzeigen, die keine Pods sind:

  1. Drücken Sie Strg-a, um die Liste der benutzerdefinierten Ressourcentypen anzuzeigen.

  2. Wählen Sie den benutzerdefinierten Ressourcentyp aus, z. B. Geräte , und drücken Sie die EINGABETASTE.

    Tipp

    Um nach einem benutzerdefinierten Ressourcentyp nach Namen zu suchen, geben Sie / ein, und beginnen Sie dann mit der Eingabe des Namens des gesuchten Typs.

  3. Wählen Sie eine benutzerdefinierte Ressource und einen der verfügbaren Vorgänge aus. Sie können z. B. die YAML-Definition eines Geräteendpunktprofils anzeigen, indem Sie es auswählen und Y drücken. Für einigen Ressourcen können Sie die Konfiguration bearbeiten.

In der folgenden Tabelle werden einige der benutzerdefinierten Ressourcentypen beschrieben, mit denen Sie in Azure IoT Einsatz arbeiten können:

Benutzerdefinierter Ressourcentyp Beschreibung
devices Stellt die Konfiguration für ein Gerät dar.
assets Stellt die Konfiguration für eine Ressource dar.
brokers brokerlisters brokerauthentications brokerauthorizations Stellt die Konfiguration für einen MQTT-Broker dar.
dataflows, dataflowendpointsdataflowprofiles Stellt die Konfiguration für einen Datenfluss dar.
secrets, secretsyncssecretproviderclasses Stellt die Konfiguration für Geheimnisse und die Geheimnisverwaltung dar.

MQTT-Tools

Wenn Sie den MQTT-Broker in Ihrer Azure IoT Einsatz Instanz kennen und testen, können Sie MQTT-Clienttools verwenden, um mit dem Broker zu interagieren. Aus Sicherheitsgründen macht Azure IoT Einsatz jedoch nicht den MQTT-Broker außerhalb des Clusters verfügbar. Als Problemumgehung stehen Ihnen die folgenden Optionen zur Verfügung:

Achtung

Diese drei Ansätze eignen sich nur für Dev/Test-Umgebungen. Sie sollten sie unter keinen Umständen in einer Produktionsumgebung verwenden.

  • Stellen Sie eine Verbindung mit dem Standardlistener im Cluster her. Diese Option verwendet die Standardkonfiguration und erfordert keine zusätzlichen Updates. Sie sind auf eine kleine Gruppe von MQTT-Clienttools beschränkt.

  • Verwenden Sie einen NodePort-Dienst, um den MQTT-Broker außerhalb des Clusters verfügbar zu machen. Diese Option erfordert, dass Sie die Konfiguration des MQTT-Brokers aktualisieren. Sie können alle MQTT-Clienttools verwenden, die das Herstellen einer Verbindung mit einem bestimmten Port unterstützen.

  • Verwenden Sie einen LoadBalancer-Dienst, um den MQTT-Broker außerhalb des Clusters verfügbar zu machen. Diese Option erfordert, dass Sie die Konfiguration des MQTT-Brokers aktualisieren. Sie können alle MQTT-Clienttools verwenden, die das Herstellen einer Verbindung mit einem bestimmten Port unterstützen.

Herstellen einer Verbindung mit dem Standardlistener im Cluster

Um eine Verbindung mit dem Standardlistener innerhalb des Clusters herzustellen, können Sie einen Pod bereitstellen, auf dem CLI-basierte MQTT-Clienttools wie mosquitto_sub und mosquitto_pub ausgeführt werden. Der folgende Befehl stellt einen solchen Pod in Ihrem Cluster bereit:

kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/mqtt-client.yaml

Wenn der Pod ausgeführt wird, können Sie eine Verbindung mit einer Shell im Pod herstellen:

kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh

Verwenden Sie diese Shell, um Befehle zur Interaktion mit dem MQTT-Broker auszuführen wie mosquitto_sub und mosquitto_pub. Beispielsweise zum Abonnieren aller Themen unter dem azure-iot-operations/data-Thema:

mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" --verbose --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Beachten Sie, wie der Befehl eine Zertifikatdatei und ein Token aus dem Dateisystem des Pods lädt. Die Manifestdatei mqtt-client.yaml bindet diese Dateien in den Pod ein.

Um eine einzelne Nachricht aus dem azure-iot-operations/data/thermostat-Thema zu erhalten, fügen Sie die Option -C 1 hinzu:

mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/thermostat" -C 1 --verbose --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Um die MQTT-v5-Benutzereigenschaften in den Nachrichten anzuzeigen, verwenden Sie die Option -F %P:

mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/thermostat" -V mqttv5 -F %P --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Um eine Nachricht im azure-iot-operations/data/valve-Thema zu veröffentlichen:

mosquitto_pub --host aio-broker --port 18883 --topic "azure-iot-operations/data/valve" --message "open:15%" --id "controller" --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)

Wenn Sie mit der Verwendung des MQTT-Clienttools-Pod fertig sind, können Sie ihn aus dem Cluster löschen:

kubectl delete -f https://raw.githubusercontent.com/Azure-Samples/explore-iot-operations/main/samples/quickstarts/mqtt-client.yaml

Weitere Informationen zu dieser Konfiguration finden Sie unter Herstellen einer Verbindung mit dem Standardlistener im Cluster.

Verwenden eines NodePort- oder LoadBalancer-Diensts

Wenn Sie die Schritte zum Konfigurieren eines Knotenports oder Lastenausgleichsdiensts ausführen, um den MQTT-Broker außerhalb des Clusters verfügbar zu machen, können Sie alle MQTT-Clienttools verwenden, die die Verbindung mit einem bestimmten Port unterstützen. In den folgenden Beispielen wird davon ausgegangen, dass Sie den Dienst ohne Authentifizierung, Autorisierung oder TLS konfiguriert haben. Sie können jetzt Ihre bevorzugten MQTT-Clienttools verwenden, um eine Verbindung mit dem MQTT-Broker am Port 1883 herzustellen, wenn Sie einen Lastenausgleich verwenden, oder einen Verbindung mit dem konfigurierten Port herzustellen, wenn Sie einen Knotenport verwenden.

Wenn Sie beispielsweise das Open-Source-Tool mqttui auf dem Computer ausführen möchten, auf dem Ihr Kubernetes-Cluster ausgeführt wird, verwenden Sie den folgenden Befehl:

mqttui --broker mqtt://localhost:1883

Tipp

Wenn Sie einen Lastenausgleich konfiguriert haben und Port 1883 auf der öffentlichen IP-Adresse des Hostcomputers geöffnet ist, können Sie den folgenden Befehl verwenden, um eine Verbindung mit dem MQTT-Broker von einem anderen Computer herzustellen: mqttui --broker mqtt://<cluster-machine-public-ip>:1883

Sie können das mqttui-Tool verwenden, um Themen zu abonnieren, Nachrichten zu veröffentlichen und die Nachrichten anzuzeigen, die den Broker durchlaufen:

Screenshot, der das MQTTUI-Tool zeigt, das alle Topics anzeigt.

Verwenden Sie den folgenden Befehl, um die Nachrichten in einem bestimmten Thema anzuzeigen, z. B. azure-iot-operations/data/thermostat:

mqttui --broker mqtt://localhost:1883 azure-iot-operations/data/thermostat

Verwenden Sie den folgenden Befehl, um eine Nachricht im azure-iot-operations/data/valve-Thema zu veröffentlichen:

mqttui publish --broker mqtt://localhost:1883 azure-iot-operations/data/valve open:15%

Verwenden Sie die folgende Konfiguration, um das Open-Source-Tool MQTT Explorer auf dem Computer auszuführen, auf dem Ihr Kubernetes-Cluster ausgeführt wird:

Screenshot: Localhost-Konfiguration von MQTT Explorer.

Verwenden Sie die folgende Konfiguration, um das Open-Source-Tool MQTT Explorer auf Ihrem lokalen Computer auszuführen und eine Verbindung mit dem Computer herzustellen, auf dem Ihr Kubernetes-Cluster ausgeführt wird:

Screenshot, der die Konfiguration des entfernten Hosts in MQTT Explorer zeigt.

Stellen Sie sicher, dass für MQTT Explorer mindestens das #-Thema konfiguriert ist:

Screenshot: Zeigt die Standard-Topic-Konfiguration in MQTT Explorer.

Nachdem Sie eine Verbindung herstellen, können Sie Nachrichten in den Themen sehen, die Sie abonniert haben, und Nachrichten veröffentlichen:

Screenshot, das zeigt, dass der MQTT Explorer die Azure IoT Einsatz-Themen abonniert hat.

Tipps

Hier finden Sie einige zusätzliche Tipps, die Ihnen bei der Arbeit mit Ihrer Azure IoT Einsatz-Instanz helfen:

Finden Sie den benutzerdefinierten Standort Ihrer Azure IoT Einsatz-Instanz

Um den benutzerdefinierten Speicherort zu finden, der Ihrer Azure IoT Einsatz-Instanz zugeordnet ist, verwenden Sie den folgenden Befehl:

az iot ops show --name <YOUR_INSTANCE_NAME> --resource-group <YOUR_RESOURCE_GROUP> --query "extendedLocation.name" --output tsv

Sie können auch den benutzerdefinierten Speicherort im Azure-Portal auf der Seite "Instanzübersicht" im Feld Extended location finden.

  • Last updated on