Dicas e ferramentas para solucionar problemas de sua instância de 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 de Operações do Azure IoT. Essas ferramentas se somam aos recursos fornecidos pelo portal Azure, CLI do Azure, a interface da experiência de operações na Web e os recursos de observabilidade.

Ferramentas do Kubernetes

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

Gerenciar componentes usando manifestos de implantação do Kubernetes

Importante

O uso de manifestos de implantação do Kubernetes não tem suporte em ambientes de produção e só deve ser usado para depuração e teste.

Em geral, Operações do Azure IoT usa a plataforma Azure Arc para fornecer uma experiência de nuvem híbrida em que você pode gerenciar a configuração por meio de ferramentas de Azure Resource Manager (ARM) e front-end, como o portal Azure, Bicep e o CLI do Azure.

No entanto, em um ambiente de depuração ou teste, você pode gerenciar os componentes do Operações do Azure IoT usando manifestos de implantação em YAML do Kubernetes. Isso significa que você pode usar ferramentas como kubectl para gerenciar alguns componentes de Operações do Azure IoT. Esse recurso tem algumas limitações:

  • A menos que você habilite a sincronização de recursos em Operações do Azure IoT usando az iot ops enable-rsync comando, as alterações feitas nos recursos usando manifestos de implantaçã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 habilitada, novos recursos criados usando manifestos de implantação do Kubernetes não serão sincronizados com Azure. Somente as alterações nos recursos existentes são sincronizadas.

Importante

Em produção, a nuvem é sempre a fonte da verdade. Sempre crie e modifique recursos por meio de Azure usando a experiência de operações, o portal Azure, o CLI do Azure ou modelos arm/Bicep. Criar recursos diretamente no cluster ou editar recursos personalizados existentes do Kubernetes pode fazer com que a nuvem e a edge fiquem fora de sincronia e não é suportado em ambientes de produção.

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 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 Prepare seu cluster kubernetes habilitado para Azure Arc descreve como configurar kubectl para se conectar ao cluster k3s quando você executa comandos kubectl no mesmo computador em que você implantou seu cluster kubernetes.

Dica

Adicione o comando export KUBECONFIG=~/.kube/config ao .bashrc ou .bash_profile para que você não precise definir a variável de ambiente KUBECONFIG sempre que abrir uma nova janela do terminal.

Se você implantou sua instância de Operações do Azure IoT em um AKS-EE habilitado para Arc, a configuração kubectl será configurada 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:

Como uma etapa única, use o SSH para se conectar ao computador onde você implantou seu cluster e execute os comandos a seguir. Lembre-se de substituir <your-name> pelo seu 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

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 marcadores:

    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, consulte Use o Cluster Connect para se conectar com segurança a clusters Kubernetes habilitados para Azure Arc.

Namespaces

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

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

Dica

Para exibir todos os namespaces no cluster, execute o seguinte comando: kubectl get namespaces.

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 do 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:

Captura de tela que mostra a visualização padrão do k9s.

Ao trabalhar com 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:

    Captura de tela que mostra a lista de pods k9s filtrados para o namespace azure-iot-operations.

Dica

Agora você pode usar as teclas numéricas para aplicar filtros. A captura de tela anterior mostra que 0 mostra todos os pods e 1 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.

    Captura de tela que mostra uma descrição em k9s de um pod em execução.

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

    Captura de tela que mostra o log de um pod em execução no k9s.

    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 no Operações do Azure IoT:

Tipo de recurso personalizado Descrição
devices Representa a configuração de um dispositivo.
assets Representa a configuração de um ativo.
brokers, brokerlisters, , brokerauthenticationsbrokerauthorizations Represente a configuração para um broker MQTT.
dataflows dataflowendpoints dataflowprofiles Represente a configuração de um fluxo de dados.
secrets secretsyncs secretproviderclasses Represente a configuração de segredos e gerenciamento de segredos.

Ferramentas do MQTT

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

Cuidado

Essas três abordagens são adequadas apenas para ambientes de desenvolvimento e teste. Em nenhuma circunstância você deve usá-las em um ambiente de produção.

  • 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 broker 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 broker 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 um serviço NodePort ou Balanceador de carga para expor o broker MQTT fora do cluster, poderá usar qualquer ferramenta de cliente MQTT que suporte a 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

Dica

Se você configurou um balanceador de carga e a porta 1883 está aberta no endereço IP público do computador host, você poderá usar o seguinte comando para se conectar ao Agente MQTT de um computador diferente: mqttui --broker mqtt://<cluster-machine-public-ip>:1883

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

Captura de tela que mostra a ferramenta MQTTUI exibindo todos os tópicos.

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:

Captura de tela que mostra a configuração de localhost do MQTT Explorer.

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:

Captura de tela que mostra a configuração do host remoto do MQTT Explorer.

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

Captura de tela que mostra a configuração do tópico padrão do MQTT Explorer.

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

Captura de tela que mostra o MQTT Explorer inscrito nos tópicos das Operações do Azure IoT.

Dicas

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

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

Para localizar o local personalizado associado à sua instância de Operações do Azure IoT, 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 Localização Estendida.

  • Last updated on