Dicas e ferramentas para solucionar problemas de sua instância de Operações IoT do Azure

Este artigo descreve como usar algumas ferramentas comuns quando você está aprendendo, explorando ou solucionando problemas de suas instâncias de Operações do Azure IoT. Essas ferramentas são adicionais aos recursos fornecidos pelo portal do Azure, CLI do Azure, interface do usuário da Web de experiência de operações e recursos de observabilidade.

Ferramentas do Kubernetes

Os componentes do Azure IoT Operations são executados em um cluster Kubernetes padrão. Você pode usar as ferramentas e kubectl CLI k9s para interagir e gerenciar seu cluster.

kubectl

kubectl é a ferramenta de linha de comando do Kubernetes para gerenciar seu cluster. Ele tem muitos recursos que você pode aprender na documentação oficial do kubernetes. Este artigo descreve os usos comuns para kubectl quando você está trabalhando com as Operações do Azure IoT, como listar os pods em execução e exibir logs.

Configurar kubectl para se conectar à sua instância

O artigo Prepare your Azure Arc-enabled Kubernetes cluster descreve como configurar kubectl para se conectar ao cluster k3s quando você executa kubectl comandos na mesma máquina em que implantou o cluster Kubernetes.

Se você implantou sua instância de Operações IoT do Azure em um AKS-EE habilitado para Arc, a kubectl configuração será configurada automaticamente para você. 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 Usar conexão de cluster para se conectar com segurança a clusters Kubernetes habilitados para Azure Arc.

Espaços de nomes

Por padrão, o Arc e o Azure IoT Operations usam os seguintes namespaces no cluster do Kubernetes:

• azure-iot-operations para os componentes do Azure IoT Operations.
• azure-arc para os componentes do Kubernetes habilitados para 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 das Operações IoT do Azure usa o comando kubectl apply para aplicar um arquivo de manifesto do Kubernetes para fazer uma alteração de 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 vista para mostrar apenas os pods no azure-iot-operations espaço de nomes.

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 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 outros tipos de recursos personalizados 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 a seguir descreve alguns dos tipos de recursos personalizados com os quais você pode trabalhar nas Operações IoT do Azure:

Ferramentas MQTT

Quando você estiver aprendendo e testando o broker MQTT em sua instância do Azure IoT Operations, poderá usar as ferramentas de cliente MQTT para interagir com o broker. No entanto, por motivos de segurança, o Azure IoT Operations não expõe o agente MQTT fora do cluster. Como solução alternativa, você tem as seguintes opções:

• Conecte-se ao ouvinte padrão dentro do cluster. Esta opção usa a configuração padrão e não requer atualizações extras. Você está limitado a um pequeno conjunto de ferramentas de cliente MQTT.

• Use um NodePort serviço para expor o broker MQTT fora do cluster. Esta opção requer que você atualize a configuração do broker MQTT. Você pode usar qualquer ferramenta de cliente MQTT que suporte a conexão a uma porta específica.

• Use um LoadBalancer serviço para expor o broker MQTT fora do cluster. Esta opção requer que você atualize a configuração do broker MQTT. Você pode usar qualquer ferramenta de cliente MQTT que suporte a conexão a uma porta específica.

Conectar-se ao ouvinte padrão dentro do cluster

Para se conectar ao ouvinte padrão dentro do cluster, você pode implantar um pod que execute ferramentas de cliente MQTT baseadas em CLI como mosquitto_sub e mosquitto_pub. O comando a seguir implanta esse pod no cluster:

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

Depois que o pod estiver em execução, você poderá se conectar a um shell no pod:

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

Use este shell para executar comandos como mosquitto_sub e mosquitto_pub interagir com o broker MQTT. Por exemplo, para subscrever todos os tópicos sob o azure-iot-operations/data tópico:

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)

Observe como o comando carrega um arquivo de certificado e um token do sistema de arquivos do pod. O mqtt-client.yaml arquivo de manifesto monta esses arquivos no pod.

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 usuário MQTT v5 nas mensagens, use a -F %P opção:

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 terminar de usar o pod de ferramentas do cliente MQTT, você poderá excluí-lo do cluster:

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

Para saber mais sobre essa configuração, consulte Conectar-se ao ouvinte padrão dentro do cluster.

Usar um NodePort ou LoadBalancer serviço

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 Azure IoT Operations:

Encontre a localização personalizada da sua instância Azure IoT Operations

Para encontrar a localização personalizada associada à sua instância Azure IoT Operations, utilize 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 .