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

Neste guia de início rápido, você implanta o Operações do Azure IoT em um cluster Kubernetes com suporte do Azure Arc para que você possa gerenciar remotamente seus dispositivos e 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

Esta série de tutoriais rápidos destina-se a ajudá-lo a começar com o Operações do Azure IoT o mais rápido possível, para que você possa avaliar um cenário completo. 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 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 nestas guias de início rápido.

Usamos GitHub Codespaces 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 Operações do Azure IoT em um cluster local no Ubuntu ou AKS (Serviço de Kubernetes do Azure), consulte Prepare seu cluster kubernetes habilitado para Azure Arc.

Pré-requisitos

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

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

• Uma conta GitHub.

• Visual Studio Code instalado em seu computador de desenvolvimento. Para obter mais informações, consulte Download Visual Studio Code.

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

Quais problemas vamos resolver?

Operações do Azure IoT é 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 em GitHub Codespaces.
2. Conecte o cluster ao Azure Arc para gerenciamento remoto.
3. Crie um registro de esquema.
4. Implante Operações do Azure IoT em seu cluster.

Criar um cluster

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

O Azure-Samples/explore-iot-operations codespace é 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 em GitHub Codespaces.

   

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

   Parâmetro	Valor
   ID_DE_ASSINATURA	Sua ID de assinatura Azure.
   GRUPO_DE_RECURSOS	Um nome para um novo grupo de recursos Azure em que o cluster será criado.
   LOCATION	Uma região Azure perto de 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 GitHub a ser usada neste e no futuro 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. Em Visual Studio Code, selecione View>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 ambiente de codificação, faça login no CLI do Azure:

   az login
   

   Dica

   Se você estiver usando o ambiente de codespace GitHub em um navegador em vez da área de trabalho do VS Code, executar az login retornará um erro localhost. 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 o erro localhost no navegador, copie a URL do navegador e execute curl "<URL>" em uma nova guia de terminal. Você deve ver uma resposta JSON com a mensagem "Você fez logon em o Microsoft Azure!"

2. Depois de entrar, CLI do Azure exibirá todas as suas assinaturas e indicará sua assinatura padrão com um asterisco *. Para continuar com sua assinatura padrão, selecione Enter. Caso contrário, digite o número da assinatura 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 obter mais informações, consulte provedores de recursos e tipos 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 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 cluster do Kubernetes e gerenciá-lo como parte do grupo de recursos 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 Microsoft Entra ID que o serviço Azure Arc usa em 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 Microsoft Entra ID que o serviço Azure Arc usa. 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 Operações do Azure IoT. Para instalar a versão mais recente, você precisa da versão mais recente da extensão da CLI Operações do Azure IoT:

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. Operações do Azure IoT requer um registro de esquema no cluster. O registro de esquema requer uma conta de armazenamento Azure para as informações de esquema armazenadas na nuvem.

O comando para criar um registro de esquema nesta seção requer Microsoft.Authorization/roleAssignments/write permissão 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 Azure

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

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

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

Implantar as operações do Azure IoT

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

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

1. Inicialize o cluster para 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 versão mais recente do Operações do Azure IoT 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ê poderá ver o andamento na exibição de progresso da implantação no terminal.

2. Implantar Operações do Azure IoT. Esse comando inclui o conector para OPC UA opcional que você usa nos inícios rápidos a seguir.

   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  --feature opcua.mode=Stable
   

   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

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

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

kubectl get pods -n azure-iot-operations

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

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

2. Selecione o nome da instância de 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 kubernetes habilitado para Arc para que ele possa se comunicar com segurança com seus componentes 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 Operações do Azure IoT 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 no qual você implantou Operações do Azure IoT e remova o grupo de recursos Azure que continha o cluster.

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

Próxima etapa