Dicas e ferramentas para resolução de problemas da sua instância Operações IoT do Azure

Este artigo descreve como usar algumas ferramentas comuns quando está a aprender, explorar ou a resolver problemas nas suas instâncias do Operações IoT do Azure. Estas ferramentas são adicionais às capacidades fornecidas pelo portal Azure, CLI do Azure, interface web de experiência operacional e recursos observabilidade.

Ferramentas do Kubernetes

Os componentes do Operações IoT do Azure correm num cluster Kubernetes padrão. Pode usar as ferramentas CLI kubectl e k9s para interagir e gerir o seu cluster.

Gerir componentes usando manifestos de implementação Kubernetes

De um modo geral, o Operações IoT do Azure utiliza a plataforma Azure Arc para proporcionar uma experiência híbrida na cloud, onde pode gerir a configuração através do Azure Resource Manager (ARM) e ferramentas front-end como o portal Azure, Bicep e o CLI do Azure.

No entanto, num ambiente de depuração ou teste pode gerir os componentes do Operações IoT do Azure usando manifestos de implementação YAML Kubernetes. Isto significa que pode usar ferramentas como kubectl para gerir alguns componentes da Operações IoT do Azure. Esta funcionalidade tem algumas limitações:

• A menos que atives a sincronização de recursos no Operações IoT do Azure usando o comando az iot ops enable-rsync, as alterações feitas aos recursos usando manifestos de implementação do Kubernetes não são sincronizadas com Azure. Para saber mais sobre a sincronização de recursos, consulte Sincronização de recursos.
• Mesmo que a sincronização de recursos esteja ativada, os recursos novos criados com manifestos de implementação do Kubernetes não são sincronizados com o Azure. Apenas as alterações aos recursos existentes são sincronizadas.

kubectl

kubectl é a ferramenta de linha de comando do Kubernetes para gerenciar seu cluster. O sistema tem muitos recursos que pode aprender na documentação oficial do Kubernetes. Este artigo descreve as utilizações comuns de kubectl quando se trabalha com Operações IoT do Azure, como listar os pods em execução e visualizar registos.

Configurar kubectl para se conectar à sua instância

O artigo Prepare o seu cluster Kubernetes compatível com Azure Arc descreve como configurar o kubectl para ligar-se ao seu cluster k3s ao executar comandos kubectl na mesma máquina onde implementou o seu cluster Kubernetes.

Se implementaste a tua instância Operações IoT do Azure num AKS-EE com Arc, a configuração kubectl é automaticamente configurada para ti. Você pode executar kubectl comandos diretamente da linha de comando na máquina em que implantou o cluster.

Também é possível executar kubectl comandos a partir da máquina cliente local em vez da máquina onde você implantou o cluster habilitado para Arc:

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

kubectl create serviceaccount "<your-name>" -n default
kubectl create clusterrolebinding "<your-name>-binding" --clusterrole cluster-admin --serviceaccount default:"<your-name>"


$yaml = @"
apiVersion: v1
kind: Secret
metadata:
  name: <your-name>-secret
  annotations:
    kubernetes.io/service-account.name: <your-name>
type: kubernetes.io/service-account-token
"@

$yaml | kubectl apply -f -

$TOKEN = ([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String((kubectl get secret <your-name>-secret -o jsonpath='{$.data.token}'))))
Write-Output $TOKEN

Anote o token. Você usa esse token para autenticar quando executa kubectl comandos na máquina cliente. Agora você pode se desconectar da máquina que executa o cluster do Kubernetes.

Para usar kubectl na máquina cliente para se conectar ao cluster, abra dois terminais:

1. No primeiro terminal, execute o seguinte comando para configurar um proxy para se conectar ao cluster. Certifique-se de substituir os valores para os três espaços reservados:

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

   Deixe este terminal aberto enquanto executa kubectl comandos no segundo terminal.

2. No segundo terminal, você pode executar seus kubectl comandos em seu cluster remoto. Por exemplo, para listar os pods no azure-iot-operations namespace:

   kubectl get pods -n azure-iot-operations
   

   Gorjeta

   Você também pode executar comandos, como k9s, que usam a kubectl configuração neste terminal.

   O kubectl contexto permanece definido para o cluster remoto até fechar o primeiro terminal.

Para saber mais, consulte Use cluster connect para se ligar de forma segura a clusters Kubernetes habilitados por Azure Arc.

Espaços de nomes

Por defeito, o Arc e o Operações IoT do Azure utilizam os seguintes namespaces no cluster Kubernetes:

• azure-iot-operations para os componentes do Operações IoT do Azure.
• azure-arc para os componentes Kubernetes habilitados por Azure Arc.

Comandos comuns kubectl

Para exibir todos os pods em execução no azure-iot-operations namespace, execute o seguinte comando:

kubectl get pods -n azure-iot-operations

A saída se parece com o exemplo a seguir:

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

Para exibir os logs de um pod específico, como o pod aio-opc-opc.tcp-1-858b9ff67-dxwvb, execute o seguinte comando:

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

Para exibir uma descrição legível por humanos de um pod específico, como o pod aio-opc-opc.tcp-1-858b9ff67-dxwvb, execute o seguinte comando:

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

Em alguns locais, a documentação da Operações IoT do Azure utiliza o comando kubectl apply para aplicar um ficheiro manifesto do Kubernetes e alterar a configuração no cluster.

k9s

O utilitário k9s oferece uma interface do usuário baseada em terminal para gerenciar seu cluster Kubernetes. Ele usa sua kubectl configuração para se conectar ao cluster e fornece uma maneira visual de interagir com o cluster. Sua visualização padrão lista todos os pods atualmente em execução no cluster:

Quando estiver a trabalhar com Operações IoT do Azure, pode filtrar a visualização para mostrar apenas os pods no espaço de nomes azure-iot-operations.

1. Digite : para abrir o painel de comando, digite ns e pressione Enter.

2. Na lista de namespaces, selecione azure-iot-operations e pressione Enter.

3. A lista de pods agora mostra apenas os pods no namespace azure-iot-operations :

   

Você pode usar teclas de atalho para visualizar informações sobre os seus pods. Por exemplo:

• Para descrever um pod, selecione-o na lista e pressione d.

  

• Para visualizar os logs de um pod, selecione-o na lista e pressione l.

  

  Gorjeta

  Você pode usar as teclas numéricas para navegar pelo arquivo de log.

Para exibir tipos de recursos personalizados além de pods no cluster:

1. Pressione Ctrl-a para exibir a lista de tipos de recursos personalizados.

2. Selecione o tipo de recurso personalizado, como dispositivos , e pressione Enter.

   Gorjeta

   Para procurar um tipo de recurso personalizado por nome, digite / e comece a digitar o nome do tipo que você está procurando.

3. Selecione um recurso personalizado e escolha uma das operações disponíveis. Por exemplo, você pode visualizar a definição YAML de um perfil de ponto de extremidade de dispositivo selecionando-o e pressionando y. Para alguns recursos, você pode editar a configuração.

A tabela seguinte descreve alguns dos tipos de recursos personalizados com que pode trabalhar no Operações IoT do Azure:

Ferramentas MQTT

Para interagir com o broker MQTT na sua instância de Operações IoT do Azure para aprendizagem, testes ou resolução de problemas, expõe primeiro o broker usando uma das abordagens não produtivas descritas em Testar conectividade ao broker MQTT com clientes MQTT: conectar-se a partir do interior do cluster, ou expor o broker fora do cluster com um NodePort serviço ORLoadBalancer. O resto desta secção mostra as ferramentas de resolução de problemas que pode executar contra esses ouvintes de teste.

Conectar-se ao ouvinte padrão dentro do cluster

Implemente o mqtt-client pod e abra uma shell nele, conforme descrito em Ligar ao listener predefinido dentro do cluster. Depois, na shell, utilize mosquitto_sub e mosquitto_pub para inspecionar e publicar mensagens nos tópicos de dados do Operações IoT do Azure.

Por exemplo, para subscrever todos os tópicos em 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)

Para receber uma única mensagem do azure-iot-operations/data/thermostat tópico, adicione a -C 1 opção:

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)

Para visualizar as propriedades do utilizador MQTT v5 nas mensagens, use a opção -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)

Para publicar uma mensagem sobre o azure-iot-operations/data/valve tópico:

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)

Quando terminares, elimina o pod do cliente:

kubectl delete pod mqtt-client -n azure-iot-operations

Utilize serviço NodePort ou LoadBalancer

Se você seguir as etapas para configurar uma porta de nó ou serviço de balanceador de carga para expor o agente MQTT fora do cluster, poderá usar qualquer ferramenta de cliente MQTT que ofereça suporte à conexão com uma porta específica. Os exemplos a seguir pressupõem que você configurou o serviço sem autenticação, autorização ou TLS. Agora você pode usar suas ferramentas de cliente MQTT favoritas para se conectar ao broker MQTT na porta 1883 se estiver usando um balanceador de carga ou a porta configurada se estiver usando uma porta de nó.

Por exemplo, para executar a ferramenta mqttui de código aberto na máquina em que o cluster do Kubernetes está sendo executado, use o seguinte comando:

mqttui --broker mqtt://localhost:1883

Você pode usar a mqttui ferramenta para se inscrever em tópicos, publicar mensagens e visualizar as mensagens que estão fluindo através do broker:

Para exibir as mensagens em um tópico específico, como azure-iot-operations/data/thermostat, use o seguinte comando:

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

Para publicar uma mensagem para o azure-iot-operations/data/valve tópico, use o seguinte comando:

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

Para executar a ferramenta de código aberto MQTT Explorer na máquina em que o cluster Kubernetes está sendo executado, use a seguinte configuração:

Para executar a ferramenta de código aberto MQTT Explorer em sua máquina local para se conectar à máquina onde o cluster Kubernetes está sendo executado, use a seguinte configuração:

Certifique-se de que o MQTT Explorer tenha pelo menos o # tópico configurado:

Depois de se conectar, você pode ver as mensagens nos tópicos que você se inscreveu e publicar mensagens:

Sugestões

Aqui ficam algumas dicas adicionais para o ajudar a trabalhar com a sua instância do Operações IoT do Azure:

Encontre a localização personalizada da sua instância do Operações IoT do Azure

Para encontrar a localização personalizada associada à sua instância do Operações IoT do Azure, use o seguinte comando:

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

Também pode encontrar a localização personalizada no portal Azure na página de visão geral da instância, no campo Localização Estendida.