Suggerimenti e strumenti per la risoluzione dei problemi relativi all'istanza di Operazioni di Azure IoT

Questo articolo descrive come usare alcuni strumenti comuni durante l'apprendimento, l'esplorazione o la risoluzione dei problemi delle istanze di Operazioni di Azure IoT. Questi strumenti integrano le funzionalità fornite dal portale di Azure, interfaccia della riga di comando di Azure, dall'interfaccia utente Web dell'esperienza operativa e dalle risorse di osservabilità.

Strumenti di Kubernetes

I componenti di Operazioni di Azure IoT vengono eseguiti in un cluster Kubernetes standard. È possibile usare gli strumenti kubectl e k9s dell'interfaccia CLI per interagire e gestire il cluster.

Gestire i componenti usando i manifesti di distribuzione kubernetes

Importante

L'uso dei manifesti di distribuzione Kubernetes non è supportato negli ambienti di produzione e deve essere usato solo per il debug e il test.

In generale, Operazioni di Azure IoT usa la piattaforma Azure Arc per offrire un'esperienza cloud ibrida in cui è possibile gestire la configurazione tramite Azure Resource Manager (ARM) e strumenti front-end come il portale Azure, Bicep e interfaccia della riga di comando di Azure.

Tuttavia, in un ambiente di debug o test è possibile gestire i componenti di Operazioni di Azure IoT usando manifesti di distribuzione Kubernetes YAML. Ciò significa che è possibile usare strumenti come kubectl per gestire alcuni componenti di Operazioni di Azure IoT. Questa funzionalità presenta alcune limitazioni:

  • A meno che non si abiliti la sincronizzazione delle risorse in Operazioni di Azure IoT usando il comando az iot ops enable-rsync, le modifiche apportate alle risorse usando manifesti di distribuzione Kubernetes non vengono sincronizzate con Azure. Per altre informazioni sulla sincronizzazione delle risorse, vedere Sincronizzazione risorse.
  • Anche se la sincronizzazione delle risorse è abilitata, le nuove risorse create usando manifesti di distribuzione Kubernetes non vengono sincronizzate con Azure. Vengono sincronizzate solo le modifiche apportate alle risorse esistenti.

Importante

Nell'ambiente di produzione, il cloud è sempre la fonte di verità. Creare e modificare sempre le risorse tramite Azure, usando l'esperienza operativa, il portale di Azure, i modelli di interfaccia della riga di comando di Azure o ARM/Bicep. La creazione di risorse direttamente nel cluster o la modifica di risorse personalizzate Kubernetes esistenti possono causare la disconnessazione del cloud e dell'edge e non sono supportati negli ambienti di produzione.

kubectl

kubectl è lo strumento da riga di comando Kubernetes per la gestione del tuo cluster. Offre molte funzionalità che è possibile ottenere nella documentazione ufficiale di kubernetes. Questo articolo descrive gli usi comuni per kubectl quando si lavora con Operazioni di Azure IoT, ad esempio elencare i pod in esecuzione e visualizzare i log.

Configurare kubectl per connettersi alla tua istanza

L'articolo Prepare il cluster Kubernetes abilitato per Azure Arc descrive come configurare kubectl per connettersi al cluster Kubernetes k3s quando si eseguono comandi kubectl nello stesso computer in cui è stato distribuito il cluster Kubernetes.

Suggerimento

Aggiungere il export KUBECONFIG=~/.kube/config comando al file con estensione bashrc o .bash_profile in modo che non sia necessario impostare la KUBECONFIG variabile di ambiente ogni volta che si apre una nuova finestra del terminale.

Se l'istanza di Operazioni di Azure IoT è stata distribuita in AKS-EE abilitato per Arc, la configurazione kubectl viene impostata automaticamente. È possibile eseguire kubectl comandi direttamente dalla riga di comando nel computer in cui è stato distribuito il cluster.

È anche possibile eseguire kubectl comandi dal computer client locale anziché dal computer in cui è stato distribuito il cluster abilitato per Arc:

Come passaggio una tantum, usare SSH per connettersi al computer in cui è stato distribuito il cluster ed eseguire i comandi seguenti. Assicurarsi di sostituire <your-name> con il nome:

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

Prendere nota del token. Questo token viene usato per eseguire l'autenticazione quando si eseguono kubectl comandi nel computer client. È ora possibile disconnettersi dal computer che esegue il cluster Kubernetes.

Per usare kubectl nel computer client per connettersi al cluster, aprire due terminali:

  1. Nel primo terminale eseguire il comando seguente per configurare un proxy per connettersi al cluster. Assicurarsi di sostituire i valori per i tre segnaposto:

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

    Lasciare aperto questo terminale mentre si eseguono kubectl i comandi nel secondo terminale.

  2. Nel secondo terminale è possibile eseguire i kubectl comandi contro il cluster remoto. Ad esempio, per elencare i pod nello spazio dei nomi azure-iot-operations:

    kubectl get pods -n azure-iot-operations

    Suggerimento

    È anche possibile eseguire comandi, ad esempio k9s, che usano la kubectl configurazione in questo terminale.

    Il kubectl contesto rimane impostato sul cluster remoto fino a quando non si chiude il primo terminale.

Per ulteriori informazioni, vedere Usa il collegamento del cluster per connettersi in modo sicuro ai cluster Kubernetes abilitati per Azure Arc.

Namespaces

Per impostazione predefinita, Arc e Operazioni di Azure IoT usano gli spazi dei nomi seguenti nel cluster Kubernetes:

  • azure-iot-operations per i componenti di Operazioni di Azure IoT.
  • azure-arc per i componenti Kubernetes abilitati per Azure Arc.

Suggerimento

Per visualizzare tutti i namespace nel cluster, eseguire il seguente comando: kubectl get namespaces.

Comandi comuni kubectl

Per visualizzare tutti i pod in esecuzione nel namespace azure-iot-operations, eseguire il comando seguente:

kubectl get pods -n azure-iot-operations

L'output ha un aspetto simile all'esempio seguente:

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

Per visualizzare i log per un pod specifico, ad esempio aio-opc-opc.tcp-1-858b9ff67-dxwvb pod, eseguire il comando seguente:

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

Per visualizzare una descrizione leggibile di un pod specifico, ad esempio aio-opc-opc.tcp-1-858b9ff67-dxwvb, eseguire il comando seguente:

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

In alcuni casi, la documentazione Operazioni di Azure IoT usa il comando applykubectl apply per applicare un file manifesto Kubernetes per apportare una modifica alla configurazione nel cluster.

k9s

L'utilità k9s offre un'interfaccia utente basata su terminale per la gestione del cluster Kubernetes. Usa la configurazione kubectl per connetterti al tuo cluster e fornisce un modo visuale per interagire con esso. La visualizzazione predefinita elenca tutti i pod attualmente in esecuzione nel cluster:

Screenshot che mostra la visualizzazione k9s predefinita.

Quando si lavora con Operazioni di Azure IoT, si può filtrare la visualizzazione per mostrare solo i pod nel namespace azure-iot-operations.

  1. Digitare : per aprire il pannello dei comandi, quindi digitare ns e premere INVIO.

  2. Nell'elenco degli spazi dei nomi selezionare azure-iot-operations e premere INVIO.

  3. L'elenco dei pod mostra ora solo i pod nel namespace azure-iot-operations :

    Screenshot che mostra l'elenco dei pod di k9s filtrato per lo spazio dei nomi di Operazioni di Azure IoT.

Suggerimento

È ora possibile usare le chiavi numerice per applicare i filtri. Lo screenshot precedente mostra che 0 visualizza tutti i pod, mentre 1 mostra solo i pod nel namespace azure-iot-operations.

È possibile usare i tasti di scelta rapida per visualizzare informazioni sui pod. Ad esempio:

  • Per descrivere un pod, selezionarlo nell'elenco e premere d.

    Screenshot che mostra una descrizione in k9s di un pod in esecuzione.

  • Per visualizzare i log per un pod, selezionarlo nell'elenco e premere l.

    Screenshot che mostra il log di un pod in esecuzione in k9s.

    Suggerimento

    È possibile usare le chiavi numerice per spostarsi nel file di log.

Per visualizzare tipi di risorse personalizzati diversi dai pod nel cluster:

  1. Premere CTRL+A per visualizzare l'elenco dei tipi di risorse personalizzati.

  2. Selezionare il tipo di risorsa personalizzato, ad esempio i dispositivi e premere INVIO.

    Suggerimento

    Per cercare un tipo di risorsa personalizzato in base al nome, digitare / e quindi iniziare a digitare il nome del tipo che si sta cercando.

  3. Selezionare una risorsa personalizzata e scegliere una delle operazioni disponibili. Ad esempio, è possibile visualizzare la definizione YAML di un profilo endpoint dispositivo selezionandolo e premendo y. Per alcune risorse, è possibile modificare la configurazione.

La tabella seguente descrive alcuni dei tipi di risorse personalizzati che è possibile usare in Operazioni di Azure IoT:

Tipo di risorsa personalizzato Descrizione
devices Rappresenta la configurazione per un dispositivo.
assets Rappresenta la configurazione di un asset.
brokers, brokerlisters, brokerauthenticationsbrokerauthorizations Rappresenta la configurazione per un broker MQTT.
dataflows, dataflowendpoints, dataflowprofiles Rappresentare la configurazione per un flusso di dati.
secrets, secretsyncs, secretproviderclasses Rappresenta la configurazione per i segreti e la gestione dei segreti.

Strumenti MQTT

Quando si apprende e si testa il broker MQTT nell'istanza di Operazioni di Azure IoT, è possibile usare gli strumenti client MQTT per interagire con il broker. Tuttavia, per motivi di sicurezza Operazioni di Azure IoT non espone il broker MQTT all'esterno del cluster. Come soluzione alternativa, sono disponibili le opzioni seguenti:

Attenzione

Questi tre approcci sono adatti solo per ambienti di sviluppo e test. In nessun caso è consigliabile usarli in un ambiente di produzione.

  • Connettersi al listener predefinito all'interno del cluster. Questa opzione usa la configurazione predefinita e non richiede aggiornamenti aggiuntivi. Si è limitati a un piccolo set di strumenti client MQTT.

  • Usare un NodePort servizio per esporre il broker MQTT all'esterno del cluster. Questa opzione richiede di aggiornare la configurazione del broker MQTT. È possibile usare qualsiasi strumento client MQTT che supporti la connessione a una porta specifica.

  • Usare un LoadBalancer servizio per esporre il broker MQTT all'esterno del cluster. Questa opzione richiede di aggiornare la configurazione del broker MQTT. È possibile usare qualsiasi strumento client MQTT che supporti la connessione a una porta specifica.

Connettersi al listener predefinito all'interno del cluster

Per connettersi al listener predefinito all'interno del cluster, è possibile distribuire un pod che esegue strumenti client MQTT basati sull'interfaccia della riga di comando, mosquitto_sub ad esempio e mosquitto_pub. Il comando seguente distribuisce un pod di questo tipo nel cluster:

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

Una volta che il pod è in esecuzione, è possibile connettersi a una shell nel pod.

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

Usare questa shell per eseguire comandi come mosquitto_sub e mosquitto_pub per interagire con il broker MQTT. Ad esempio, per sottoscrivere tutti gli argomenti nell'argomento azure-iot-operations/data :

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)

Si noti che il comando carica un file di certificato e un token dal file system del pod. Il file manifest mqtt-client.yaml monta questi file nel pod.

Per ricevere un singolo messaggio dall'argomento azure-iot-operations/data/thermostat , aggiungere l'opzione -C 1 :

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)

Per visualizzare le proprietà utente MQTT v5 nei messaggi, usare l'opzione -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)

Per pubblicare un messaggio nell'argomento azure-iot-operations/data/valve :

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)

Al termine dell'uso del pod degli strumenti client MQTT, è possibile eliminarlo dal cluster:

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

Per altre informazioni su questa configurazione, vedere Connettersi al listener predefinito all'interno del cluster.

Usare un servizio NodePort o LoadBalancer

Se si seguono i passaggi per configurare una porta Node o un servizio di bilanciamento del carico per esporre il broker MQTT all'esterno del cluster, è possibile usare qualsiasi strumento client MQTT che supporti la connessione a una porta specifica. Negli esempi seguenti si presuppone che il servizio sia stato configurato senza autenticazione, autorizzazione o TLS. È ora possibile usare gli strumenti client MQTT preferiti per connettersi al broker MQTT sulla porta 1883 se si usa un servizio di bilanciamento del carico o la porta configurata se si usa una porta del nodo.

Ad esempio, per eseguire lo strumento mqttui open source nel computer in cui è in esecuzione il cluster Kubernetes, usare il comando seguente:

mqttui --broker mqtt://localhost:1883

Suggerimento

Se è stato configurato un servizio di bilanciamento del carico e la porta 1883 è aperta nell'indirizzo IP pubblico del computer host, è possibile usare il comando seguente per connettersi al broker MQTT da un computer diverso: mqttui --broker mqtt://<cluster-machine-public-ip>:1883

È possibile usare lo mqttui strumento per sottoscrivere argomenti, pubblicare messaggi e visualizzare i messaggi trasmessi attraverso il broker:

Screenshot che visualizza lo strumento MQTTUI con tutti gli argomenti.

Per visualizzare i messaggi su un argomento specifico come azure-iot-operations/data/thermostat, usare il comando seguente:

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

Per pubblicare un messaggio nell'argomento azure-iot-operations/data/valve , usare il comando seguente:

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

Per eseguire lo strumento MQTT Explorer open source nel computer in cui è in esecuzione il cluster Kubernetes, usare la configurazione seguente:

Screenshot che mostra la configurazione localhost di MQTT Explorer.

Per eseguire lo strumento MQTT Explorer open source nel computer locale per connettersi al computer in cui è in esecuzione il cluster Kubernetes, usare la configurazione seguente:

Screenshot che mostra la configurazione dell'host remoto di MQTT Explorer.

Assicurarsi che MQTT Explorer abbia almeno l'argomento # configurato:

Screenshot che mostra la configurazione dell'argomento predefinito di MQTT Explorer.

Dopo la connessione, è possibile visualizzare i messaggi negli argomenti sottoscritti e pubblicare messaggi:

Screenshot che mostra gli argomenti di Operazioni di Azure IoT sottoscritti da MQTT Explorer.

Suggerimenti

Ecco alcuni suggerimenti aggiuntivi che consentono di usare l'istanza di Operazioni di Azure IoT:

Trovare la posizione personalizzata dell'istanza di Operazioni di Azure IoT

Per trovare il percorso personalizzato associato all'istanza di Operazioni di Azure IoT, usare il comando seguente:

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

È anche possibile trovare il percorso personalizzato nel portale di Azure nella pagina panoramica dell'istanza nel campo Posizione estesa.

  • Last updated on