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

Importante

A utilização dos manifestos de implementação Kubernetes não é suportada em ambientes de produção e deve ser usada apenas para depuração e testes.

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.

Importante

Na produção, a nuvem é sempre a fonte da verdade. Crie e modifique sempre recursos através do Azure — utilizando a experiência operacional, o portal Azure, a CLI do Azure ou templates ARM/Bicep. Criar recursos diretamente no cluster ou editar recursos personalizados existentes do Kubernetes pode fazer com que a nuvem e a borda fiquem fora de sincronia e não são suportados em ambientes de produção.

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.

Gorjeta

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

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:

Como uma etapa única, use SSH para se conectar à máquina onde você implantou seu cluster e execute os seguintes comandos. Certifique-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. 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.

Gorjeta

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

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:

Captura de ecrã que mostra a visualização k9s predefinida.

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 :

    Captura de ecrã que mostra a lista de pods do k9s filtrada para o namespace azure-iot-operations.

Gorjeta

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 teclas de atalho para visualizar informações sobre os seus pods. Por exemplo:

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

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

  • Para visualizar 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.

    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:

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

Ferramentas MQTT

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

Atenção

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

  • 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 arquivo de manifesto mqtt-client.yaml insere estes ficheiros 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 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 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.

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

Gorjeta

Se você configurou um balanceador de carga e a porta 1883 está aberta no endereço IP público da máquina host, você pode usar o seguinte comando para se conectar ao broker MQTT de uma máquina diferente: mqttui --broker mqtt://<cluster-machine-public-ip>: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:

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

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

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:

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

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

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

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

Captura de ecrã que mostra o MQTT Explorer subscrito nos tópicos do Operações IoT do Azure.

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.

  • Last updated on