Guia de início rápido: executar operações do Azure IoT no GitHub Codespaces com K3s

Neste início rápido, você implanta o Azure IoT Operations em um cluster Kubernetes habilitado para Azure Arc para que possa gerenciar remotamente seus dispositivos e cargas de trabalho. No final do início rápido, você tem um cluster que pode gerenciar a partir da nuvem. O restante dos inícios rápidos desta série de ponta a ponta se baseia nesta para definir ativos de exemplo, pipelines de processamento de dados e visualizações.

Antes de começar

Esta série de inícios rápidos destina-se a ajudá-lo a começar a usar as Operações IoT do Azure o mais rápido possível para que você possa avaliar um cenário de ponta a ponta. Em um verdadeiro ambiente de desenvolvimento ou produção, várias equipes trabalhando juntas executam essas tarefas e algumas tarefas podem exigir permissões elevadas.

Para obter a melhor experiência de novo usuário, recomendamos usar uma conta gratuita do Azure para que você tenha permissões de proprietário sobre os recursos nesses inícios rápidos.

Usamos o GitHub Codespaces como um ambiente virtual para este quickstart, para que possas testar o cenário sem instalar novas ferramentas nas tuas próprias máquinas. No entanto, se você quiser implantar o Azure IoT Operations em um cluster local no Ubuntu ou no Serviço Kubernetes do Azure (AKS), consulte Preparar seu cluster Kubernetes habilitado para Azure Arc.

Pré-requisitos

Antes de começar, prepare os seguintes pré-requisitos:

• Uma subscrição do Azure. Se você não tiver uma assinatura do Azure, crie uma gratuitamente antes de começar.

• Uma conta GitHub.

• Visual Studio Code instalado em sua máquina de desenvolvimento. Para obter mais informações, consulte Baixar o código do Visual Studio.

• Permissões Microsoft.Authorization/roleAssignments/write no nível do grupo de recursos.

Que problema vamos resolver?

O Azure IoT Operations é um conjunto de serviços de dados que é executado em clusters Kubernetes. Você deseja que esses clusters sejam gerenciados remotamente a partir da nuvem e capazes de se comunicar com segurança com recursos e pontos de extremidade da nuvem. Abordamos essas preocupações com as seguintes tarefas neste guia de início rápido:

1. Crie um cluster Kubernetes no GitHub Codespaces.
2. Conecte o cluster ao Azure Arc para gerenciamento remoto.
3. Crie um registro de esquema.
4. Implante as Operações IoT do Azure em seu cluster.

Criar cluster

Nesta seção, você cria um novo cluster. Se você quiser reutilizar um cluster no qual implantou as Operações do Azure IoT anteriormente, consulte as etapas em Limpar recursos para desinstalar as Operações do Azure IoT antes de continuar.

O espaço de código Azure-Samples/explore-iot-operations é pré-configurado com:

• K3s rodando em K3d para um cluster Kubernetes leve
• CLI do Azure
• Kubectl para gerenciar recursos do Kubernetes
• Outras ferramentas úteis como Helm e k9s

Para criar seu espaço de código e cluster, use as seguintes etapas:

1. Crie um espaço de código no GitHub Codespaces.

   

2. Forneça os seguintes segredos recomendados para seu espaço de código:

   Parâmetro	Valor
   ID_DE_ASSINATURA	O seu ID de subscrição do Azure.
   Grupo de Recursos	Um nome para um novo grupo de recursos do Azure onde seu cluster será criado.
   LOCALIZAÇÃO	Uma região do Azure perto de você. Para obter a lista de regiões atualmente suportadas, consulte Regiões suportadas.

   Gorjeta

   Os valores que você fornece como segredos nesta etapa são salvos em sua conta do GitHub para serem usados neste e em futuros Codespaces. Elas são adicionadas como variáveis de ambiente no terminal do codespace, e você pode usar essas variáveis de ambiente nos comandos da CLI na próxima seção.

   Além disso, esse espaço de código cria uma variável de CLUSTER_NAME ambiente que é definida com o nome de espaço de código.

3. Selecione Criar novo espaço de código.

4. Quando o espaço de código estiver pronto, selecione o botão de menu no canto superior esquerdo e, em seguida, selecione Abrir no VS Code Desktop.

   

5. Se solicitado, instale a extensão Codespaces do GitHub para Visual Studio Code e entre no GitHub.

6. No Visual Studio Code, selecione View>Terminal.

   Use este terminal para executar todos os comandos da CLI para gerenciar seu cluster.

Conectar cluster ao Azure Arc

Para conectar seu cluster ao Azure Arc:

1. No seu terminal de codespace, inicie sessão na CLI do Azure:

   az login
   

   Gorjeta

   Se você estiver usando o ambiente de espaço de código GitHub em um navegador em vez da área de trabalho do VS Code, a execução az login retornará um erro localhost. Para corrigir o erro:

   • Abra o espaço de código na área de trabalho do VS Code e, em seguida, retorne ao terminal do navegador e execute az loginnovamente o .
   • Caso você obtenha o erro localhost no navegador, copie o URL do navegador e execute curl "<URL>" em uma nova aba do terminal. Deve ver uma resposta JSON com a mensagem "Iniciou sessão no Microsoft Azure!"

2. Depois de iniciar sessão, a CLI do Azure apresenta todas as suas subscrições e indica a sua subscrição predefinida com um asterisco *. Para continuar com sua assinatura padrão, selecione Enter. Caso contrário, digite o número da assinatura do Azure que você deseja usar.

3. Registe os fornecedores de recursos necessários na sua subscrição:

   Gorjeta

   Esta etapa só precisa ser executada uma vez por assinatura. Para registrar provedores de recursos, você precisa de permissão para fazer a /register/action operação, que está incluída nas funções de Colaborador e Proprietário da assinatura. Para obter mais informações, consulte Tipos e provedores de recursos do Azure.

   az provider register -n "Microsoft.ExtendedLocation"
   az provider register -n "Microsoft.Kubernetes"
   az provider register -n "Microsoft.KubernetesConfiguration"
   az provider register -n "Microsoft.IoTOperations"
   az provider register -n "Microsoft.DeviceRegistry"
   az provider register -n "Microsoft.SecretSyncController"
   

4. Use o comando az group create para criar um grupo de recursos em sua assinatura do Azure para armazenar todos os recursos:

   az group create --location $LOCATION --resource-group $RESOURCE_GROUP
   

5. Use o comando az connectedk8s connect para habilitar seu cluster Kubernetes e gerenciá-lo como parte do seu grupo de recursos do Azure:

   az connectedk8s connect --name $CLUSTER_NAME --location $LOCATION --resource-group $RESOURCE_GROUP
   

   Gorjeta

   O valor de $CLUSTER_NAME é definido automaticamente como o nome do seu espaço de código. Substitua a variável de ambiente se quiser usar um nome diferente.

6. Obtenha o aplicativo Microsoft Entra ID que o serviço Azure Arc usa em seu locatário e salve-o objectId como uma variável de ambiente. Execute o seguinte comando exatamente como escrito, sem alterar o valor do GUID.

   export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
   

7. Use o comando az connectedk8s enable-features para habilitar o suporte de local personalizado em seu cluster. Este comando usa o objectId do aplicativo Microsoft Entra ID que o serviço Azure Arc usa. Execute este comando na máquina onde você implantou o cluster Kubernetes:

   az connectedk8s enable-features -n $CLUSTER_NAME -g $RESOURCE_GROUP --custom-locations-oid $OBJECT_ID --features cluster-connect custom-locations
   

Instale a versão mais recente do az iot ops

Este guia de início rápido usa a versão mais recente do Azure IoT Operations. Para instalar a versão mais recente, você precisa da versão mais recente da extensão Azure IoT Operations CLI:

az extension add --upgrade --name azure-iot-ops

Criar conta de armazenamento e registro de esquema

O registro de esquema é um repositório sincronizado que armazena definições de mensagens na nuvem e na borda. O Azure IoT Operations requer um registro de esquema em seu cluster. O registro de esquema requer uma conta de armazenamento do Azure para as informações de esquema armazenadas na nuvem.

O comando para criar um registro de esquema nesta seção requer a permissão Microsoft.Authorization/roleAssignments/write no nível do grupo de recursos. Essa permissão é usada para dar ao registro de esquema uma função de colaborador para que ele possa gravar na conta de armazenamento.

Execute os seguintes comandos da CLI no terminal do Codespaces.

1. Defina variáveis de ambiente para os recursos criados nesta seção.

   Marcador de Posição	Valor
   <STORAGE_ACCOUNT_NAME>	O nome da sua conta de armazenamento. Os nomes das contas de armazenamento devem ter entre 3 e 24 caracteres e conter apenas números e letras minúsculas.
   <SCHEMA_REGISTRY_NAME>	Um nome para o registro do esquema. Os nomes do Registro de esquema só podem conter números, letras minúsculas e hífenes.
   <SCHEMA_REGISTRY_NAMESPACE>	Um nome para seu namespace do Registro de esquema. O namespace identifica exclusivamente um registro de esquema dentro de um locatário. Os nomes de namespace do Registro de esquema só podem conter números, letras minúsculas e hífenes.

   STORAGE_ACCOUNT=<STORAGE_ACCOUNT_NAME>
   SCHEMA_REGISTRY=<SCHEMA_REGISTRY_NAME>
   SCHEMA_REGISTRY_NAMESPACE=<SCHEMA_REGISTRY_NAMESPACE>
   

2. Crie uma conta de armazenamento com namespace hierárquico habilitado.

   az storage account create --name $STORAGE_ACCOUNT --location $LOCATION --resource-group $RESOURCE_GROUP --enable-hierarchical-namespace
   

3. Crie um registro de esquema que se conecte à sua conta de armazenamento. Esse comando também cria um contêiner de blob chamado esquemas na conta de armazenamento.

   az iot ops schema registry create --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP --registry-namespace $SCHEMA_REGISTRY_NAMESPACE --sa-resource-id $(az storage account show --name $STORAGE_ACCOUNT -o tsv --query id)
   

Criar um namespace do Registro de Dispositivo do Azure

As Operações do Azure IoT e o Registro de Dispositivo do Azure usam namespaces para organizar ativos e dispositivos. Cada instância do Azure IoT Operations usa um único namespace para seus ativos e dispositivos.

Execute o seguinte comando da CLI para criar um namespace do Registro de Dispositivo do Azure.

az iot ops ns create -n myqsnamespace -g $RESOURCE_GROUP

Implantar operações do Azure IoT

Nesta seção, você configura seu cluster com as dependências para seus componentes de Operações do Azure IoT e, em seguida, implanta as Operações do Azure IoT.

Execute os seguintes comandos da CLI no terminal do Codespaces.

1. Inicialize seu cluster para Operações do Azure IoT.

   Gorjeta

   O init comando só precisa ser executado uma vez por cluster. Se você estiver reutilizando um cluster que já tinha a versão mais recente do Azure IoT Operations implantada nele, ignore esta etapa.

   az iot ops init --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP
   

   Esse comando pode levar vários minutos para ser concluído. Você pode observar o progresso na exibição do progresso da implantação no terminal.

2. Implante as Operações IoT do Azure.

   az iot ops create --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP --name ${CLUSTER_NAME}-instance --sr-resource-id $(az iot ops schema registry show --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP -o tsv --query id) --ns-resource-id $(az iot ops ns show --name myqsnamespace --resource-group $RESOURCE_GROUP -o tsv --query id) --broker-frontend-replicas 1 --broker-frontend-workers 1  --broker-backend-part 1  --broker-backend-workers 1 --broker-backend-rf 2 --broker-mem-profile Low
   

   Esse comando pode levar vários minutos para ser concluído. Você pode observar o progresso na exibição do progresso da implantação no terminal.

   Se você receber um erro dizendo que seu dispositivo precisa ser gerenciado para acessar seu recurso, execute az login novamente e certifique-se de entrar interativamente com um navegador.

Exibir recursos no cluster

Quando a implantação estiver concluída, você poderá usar comandos kubectl para observar alterações no cluster ou, como o cluster é habilitado para Arc, poderá usar o portal do Azure.

Para exibir os pods no cluster, execute o seguinte comando:

kubectl get pods -n azure-iot-operations

Para exibir seus recursos no portal do Azure, use as seguintes etapas:

1. No portal do Azure, vá para o grupo de recursos que contém sua instância de Operações do Azure IoT ou procure e selecione Operações do Azure IoT.

2. Selecione o nome da sua instância de Operações do Azure IoT.

3. Na página Visão geral da instância, selecione a guia Resumo dos recursos para exibir o estado de provisionamento dos recursos que foram implantados no cluster.

   

Como resolvemos o problema?

Neste início rápido, você configurou seu cluster Kubernetes habilitado para Arc para que ele pudesse se comunicar com segurança com seus componentes do Azure IoT Operations. Em seguida, você implantou esses componentes no cluster. Para esse cenário de teste, você tem um único cluster Kubernetes em execução no Codespaces. Em um cenário de produção, no entanto, você pode usar as mesmas etapas para implantar cargas de trabalho em muitos clusters em vários sites.

Clean up resources (Limpar recursos)

Se continuar para o próximo início rápido, mantenha todos os seus recursos.

Se você quiser remover a implantação do Azure IoT Operations mas manter seu cluster, use o comando az iot ops delete :

az iot ops delete --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP

Se você quiser excluir todos os recursos criados para este início rápido, exclua o cluster do Kubernetes onde você implantou as Operações do Azure IoT e, em seguida, remova o grupo de recursos do Azure que continha o cluster.

Se você usou Codespaces para esses inícios rápidos, exclua seu Codespace do GitHub.

Próximo passo