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

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

Ferramentas do Kubernetes

Os componentes das Operações do Azure IoT são executados em um cluster do Kubernetes padrão. Você pode usar as ferramentas da CLI kubectl e 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 sobre os quais você pode aprender na documentação do kubernetes oficial. 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.

Configure kubectl para se conectar à sua instância

O artigo Preparar seu cluster do Kubernetes habilitado para Azure Arc descreve como configurar kubectl para se conectar ao cluster k3s ao executar os comandos kubectl no mesmo computador onde você implantou o cluster do Kubernetes.

Se você implantou sua instância das Operações do Azure IoT em um AKS-EE habilitado para Arc, a configuração kubectl será definida automaticamente para você. Você pode executar os comandos kubectl diretamente da linha de comando no computador onde implantou o cluster.

Também é possível executar os comandos kubectl do seu computador cliente local em vez do computador 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. Use esse token para autenticar quando executar os comandos kubectl no computador cliente. Agora você pode se desconectar do computador que executa o cluster do Kubernetes.

Para usar kubectl no seu computador 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 seu cluster. Certifique-se de substituir os valores dos 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 esse terminal aberto enquanto executa os comandos kubectl no segundo terminal.

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

   kubectl get pods -n azure-iot-operations
   

   Dica

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

   O contexto kubectl permanece definido para o cluster remoto até que você feche seu primeiro terminal.

Para saber mais, confira Usar a conexão de cluster para se conectar com segurança aos clusters do Kubernetes habilitados para Azure Arc.

Namespaces

Por padrão, o Arc e as Operações do Azure IoT usam os seguintes namespaces no cluster do Kubernetes:

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

Comandos kubectl comuns

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

kubectl get pods -n azure-iot-operations

A saída se parece com o seguinte exemplo:

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 para 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 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 do Azure IoT 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 do Kubernetes. Ele usa a configuração kubectl para se conectar ao seu cluster e fornece uma maneira visual de interagir com seu cluster. Sua exibição padrão lista todos os pods atualmente em execução no cluster:

Ao trabalhar com as Operações do Azure IoT, você pode filtrar a exibição para mostrar apenas os pods no namespace azure-iot-operations.

1. Digite : para abrir o painel de comando, depois 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 as teclas de atalho para exibir informações sobre seus pods. Por exemplo:

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

  

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

  

  Dica

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

Para exibir outros tipos de recursos personalizados que não sejam 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.

   Dica

   Para pesquisar 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 exibir a definição YAML de um perfil de ponto de extremidade do 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 do Azure IoT:

Ferramentas do MQTT

Ao aprender e testar o Agente MQTT em sua instância das Operações do Azure IoT, você pode usar ferramentas do cliente MQTT para interagir com o agente. No entanto, por motivos de segurança, as Operações do Azure IoT não expõem o Agente MQTT fora do cluster. Como solução alternativa, você tem as seguintes opções:

• Conectar-se ao ouvinte padrão dentro do cluster. Essa opção usa a configuração padrão e não requer nenhuma atualização adicional. Você está limitado a um pequeno conjunto de ferramentas do cliente MQTT.

• Use um serviço NodePort para expor o Agente MQTT fora do cluster. Essa opção exige que você atualize a configuração do agente MQTT. Você pode usar todas as ferramentas do cliente MQTT que dão suporte à conexão a uma porta específica.

• Use um serviço LoadBalancer para expor o Agente MQTT fora do cluster. Essa opção exige que você atualize a configuração do agente MQTT. Você pode usar todas as ferramentas do cliente MQTT que dão suporte à 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 executa ferramentas do cliente MQTT baseadas em CLI, como mosquitto_sub e mosquitto_pub. O comando a seguir implanta um pod desse tipo em seu 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 esse shell para executar comandos como mosquitto_sub e mosquitto_pub para interagir com o Agente MQTT. Por exemplo, para assinar todos os tópicos no tópico 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)

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

Para receber uma única mensagem do tópico azure-iot-operations/data/thermostat, adicione a opção -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)

Para exibir as propriedades do usuário do 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 no tópico 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)

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, confira Conectar-se ao ouvinte padrão dentro do cluster.

Usar um serviço NodePort ou LoadBalancer

Se você seguir as etapas para configurar uma Porta de nó ou o serviço do Balanceador de carga para expor o Agente MQTT fora do cluster, você poderá usar todas as ferramentas do cliente MQTT que dão suporte à conexão a 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 do cliente MQTT favoritas para se conectar ao Agente 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 no computador onde o cluster do Kubernetes está em execução, use o seguinte comando:

mqttui --broker mqtt://localhost:1883

Você pode usar a ferramenta mqttui para assinar tópicos, publicar mensagens e exibir as mensagens que estão fluindo pelo agente:

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 no tópico azure-iot-operations/data/valve, use o seguinte comando:

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

Para executar a ferramenta MQTT Explorer de código aberto no computador onde seu cluster do Kubernetes está sendo executado, use a seguinte configuração:

Para executar a ferramenta MQTT Explorer de código aberto em seu computador local para se conectar ao computador onde seu cluster do Kubernetes está sendo executado, use a seguinte configuração:

Verifique se o MQTT Explorer configurou pelo menos o tópico #:

Depois de se conectar, você poderá ver as mensagens nos tópicos aos quais assinou e publicar mensagens:

Dicas

Aqui estão algumas dicas adicionais para ajudá-lo a trabalhar com sua instância de Operações de IoT do Azure:

Localizar o local personalizado da instância de Operações de IoT do Azure

Para localizar o local personalizado associado à instância de Operações de 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

Você também pode encontrar o local personalizado no portal do Azure na página de visão geral da instância no campo Local Estendido .