Início Rápido: Executar as Operações do Azure IoT no GitHub Codespaces com o K3s

Neste início rápido, você implantará as Operações do Azure IoT em um cluster Kubernetes habilitado para Azure Arc para gerenciar remotamente seus dispositivos e suas cargas de trabalho. No final do início rápido, você terá um cluster que pode gerenciar na nuvem. Os outros guias de início rápido nesta série completa se baseiam neste guia para definir ativos de exemplo, pipelines de processamento de dados e visualizações.

Antes de começar

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

Para que a experiência de novo usuário seja a melhor possível, recomendamos usar uma conta gratuita do Azure para que você tenha permissões de proprietário sobre os recursos nestes guias de início rápido.

Usamos os Codespaces do GitHub como um ambiente virtual para este início rápido para que você possa testar o cenário sem instalar novas ferramentas em seus próprios computadores. No entanto, se você quiser implantar as Operações do Azure IoT em um cluster local no Ubuntu ou no AKS (Serviço de Kubernetes do Azure), veja Preparar seu cluster do Kubernetes habilitado para Azure Arc.

Pré-requisitos

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

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

• Uma conta do GitHub.

• É necessário ter o Visual Studio Code instalado no computador de desenvolvimento. Para obter mais informações, veja Baixar o Visual Studio Code.

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

Quais problemas vamos resolver?

As Operações do Azure IoT são um conjunto de serviços de dados executados em clusters do Kubernetes. Você deseja que esses clusters sejam gerenciados remotamente da nuvem e possam se comunicar com segurança com recursos e pontos de extremidade de nuvem. Abordamos essas questões com as seguintes tarefas neste início rápido:

1. Crie um cluster do 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 do Azure IoT no seu cluster.

Criar um cluster

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

O codespace Azure-Samples/explore-iot-operations já vem pré-configurado com:

• K3s em execução no K3d para um cluster leve do Kubernetes
• CLI do Azure
• Kubectl para gerenciar recursos do Kubernetes
• Outras ferramentas úteis, como o Helm e o k9s

Para criar seu codespace e cluster, use as seguintes etapas:

1. Crie um codespace no GitHub Codespaces.

   

2. Forneça os seguintes segredos recomendados para o seu codespace:

   Parâmetro	Valor
   ID_DE_ASSINATURA	Sua ID da assinatura do Azure.
   GRUPO_DE_RECURSOS	Um nome para um novo grupo de recursos do Azure em que o cluster será criado.
   LOCATION	Uma região do Azure próxima a você. Para ver todas as regiões com suporte no momento, veja Regiões com suporte.

   Dica

   Os valores que você fornece como segredos nesta etapa são salvos em sua conta do GitHub a serem usados neste e em futuros Codespaces. Eles são adicionados 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 codespace cria uma variável de ambiente CLUSTER_NAME que é definida com o nome do codespace.

3. Selecione Criar codespace.

4. Depois que o codespace estiver pronto, selecione o botão de menu no canto superior esquerdo e, em seguida, selecione Abrir na Área de Trabalho do VS Code.

   

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

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

   Use esse terminal para executar todos os comandos da CLI para gerenciar o cluster.

Conectar o cluster ao Azure Arc

Para conectar seu cluster ao Azure Arc:

1. No terminal do codespace, entre na CLI do Azure:

   az login
   

   Dica

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

   • Abra o codespace na área de trabalho do VS Code, retorne ao terminal do navegador e execute az login novamente.
   • Ou, depois de obter um erro de localhost no navegador, copie a URL do navegador e execute curl "<URL>" em uma nova guia de terminal. Você deverá ver uma resposta JSON com a mensagem "Você fez login no Microsoft Azure!"

2. Depois que você se conectar, a CLI do Azure exibirá todas as suas assinaturas e indicará a assinatura padrão 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. Registre os provedores de recursos necessários na sua assinatura:

   Dica

   Esta etapa só precisa ser executada uma vez por assinatura. Para registrar provedores de recursos, você precisa de permissão para fazer a operação /register/action, que está incluída nas funções Colaborador e Proprietário da assinatura. Para saber mais, veja Provedores e tipos 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 na 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 o Arc no cluster do Kubernetes e gerenciá-lo como parte do grupo de recursos do Azure:

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

   Dica

   O valor de $CLUSTER_NAME é automaticamente definido como o nome do codespace. Substitua a variável de ambiente se desejar usar um nome diferente.

6. Obtenha o objectId do aplicativo do Microsoft Entra ID que o serviço do Azure Arc usa no seu locatário e salve-o como uma variável de ambiente. Execute o comando a seguir exatamente no estado em que se encontra, sem alterar o valor da 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 ao local personalizado no seu cluster. Esse comando usa o objectId do aplicativo do Microsoft Entra ID usado pelo serviço do Azure Arc. Execute este comando no computador em que você implantou o cluster do Kubernetes:

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

Instalar a versão mais recente do az iot ops

Este 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 da CLI de Operações IoT do Azure:

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

Criar uma conta de armazenamento e um registro de esquema

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

O comando para criar um registro de esquema nessa seção requer 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 comandos da CLI a seguir no seu terminal do Codespaces.

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

   Espaço reservado	Valor
   <STORAGE_ACCOUNT_NAME>	Um nome para sua conta de armazenamento. Os nomes da conta de armazenamento precisam ter entre 3 e 24 caracteres e só podem conter números e letras minúsculas.
   <SCHEMA_REGISTRY_NAME>	Um nome para o registro de esquema. Os nomes do registro de esquema só podem conter números, letras minúsculas e hifens.
   <SCHEMA_REGISTRY_NAMESPACE>	Um nome para o namespace do registro de esquema. O namespace identifica exclusivamente um registro de esquema em um locatário. Os nomes do namespace do registro de esquema só podem conter números, letras minúsculas e hifens.

   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 blobs chamado schemas 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 IoT do Azure e o Registro de Dispositivos do Azure usam namespaces para organizar ativos e dispositivos. Cada instância de Operações IoT do Azure usa um único namespace para seus ativos e dispositivos.

Execute o comando da CLI a seguir para criar um namespace do Registro de Dispositivos do Azure.

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

Implantar as Operações do Azure IoT

Nesta seção, você vai configurar o cluster com as dependências dos componentes das Operações do Azure IoT e, em seguida, implantará as Operações do Azure IoT.

Execute os comandos da CLI a seguir no seu terminal do Codespaces.

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

   Dica

   O comando init só precisa ser executado uma vez por cluster. Se você estiver reutilizando um cluster que já tinha a última versão das Operações do Azure IoT implantada, pule essa etapa.

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

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

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

   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ê poderá ver o andamento na exibição de progresso da implantação no terminal.

   Se você receber um erro informando que Seu dispositivo precisa ser gerenciado para acessar seu recurso, execute az login novamente e faça o logon de maneira interativa usando um navegador.

Exibir recursos no cluster

Com a implantação concluída, você pode usar comandos do kubectl para observar alterações no cluster ou usar o portal do Azure, já que o cluster está habilitado para o Arc.

Para exibir os pods no seu 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, acesse o grupo de recursos que contém sua instância das Operações do Azure IoT ou pesquise e selecione Operações do Azure IoT.

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

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

   

Como resolvemos o problema?

Neste início rápido, você configurou seu cluster do Kubernetes habilitado para Arc para que ele pudesse se comunicar com segurança com seus componentes das Operações do Azure IoT. Em seguida, você implantou esses componentes no cluster. Para esse cenário de teste, você tem um só cluster do 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.

Limpar os recursos

Se você continuar no próximo início rápido, mantenha todos os seus recursos.

Se você quiser remover a implantação das Operações do Azure IoT, mas quiser manter o 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 no qual você implantou as Operações do Azure IoT e remova o grupo de recursos do Azure que continha o cluster.

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

Próxima etapa