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

Artigo
11/20/2024

Nesse início rápido, você implantará o Azure IoT Operations em um cluster Kubernetes habilitado para Azure Arc para poder 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 amostra, pipelines de processamento de dados e visualizações.

Antes de começar

Essa série de inícios rápidos destina-se a ajudá-lo a começar com as Operações 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.

Também usamos o GitHub Codespaces como um ambiente virtual para esse início rápido, para que você possa testar o cenário sem instalar novas ferramentas em suas próprias máquinas. No entanto, se você quiser implantar o Azure IoT Operations em um cluster local no Ubuntu ou no Azure Kubernetes Service (AKS), veja Preparar seu cluster 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 em seu computador de desenvolvimento. Para obter mais informações, confira Baixar o Visual Studio Code.
Permissões Microsoft.Authorization/roleAssignments/write no nível do grupo de recursos.

Que problema vamos resolver?

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

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

Criar cluster

O Azure IoT Operations pode ser implantado no K3s no Ubuntu, no Azure Kubernetes Service (AKS) Edge Essentials e no AKS no Azure Local. No entanto, para obter velocidade e conveniência, esse início rápido usa o GitHub Codespaces para hospedar seu cluster. Para saber como implantar o Azure IoT Operations em um cluster no Windows ou Ubuntu, veja Preparar seu cluster Kubernetes habilitado para Azure Arc.

Observação

Os codespaces são fáceis de configurar rapidamente e desmontar posteriormente, mas não são adequados para avaliação de desempenho ou testes de escala. Use o GitHub Codespaces somente para exploração.

O ambiente Codespaces é suficiente para concluir as etapas de início rápido, mas não oferece suporte a configurações avançadas.

Nessa 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 codespace Azure-Samples/explore-iot-operations já vem pré-configurado com:

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

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

Crie um codespace no GitHub Codespaces.

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

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

Dica

Os valores que você fornece como segredos nesta etapa são salvos em sua conta do GitHub para serem usados neste e em seus 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.

Selecione Criar novo codespace.
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.
Se solicitado, instale a extensão GitHub Codespaces para Visual Studio Code e entre no GitHub.
No Visual Studio Code, selecione Exibir>Terminal.

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

Conecte o cluster ao Azure Arc

Para conectar seu cluster ao Azure Arc:

No seu terminal codespace, inscreva-se no CLI do Azure:
```
az login
```
Dica

Se você estiver usando o ambiente de codespace do GitHub em um navegador em vez do desktop do VS Code, a execução 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 receber o erro localhost no navegador, copie a URL do navegador e execute curl "<URL>" em uma nova guia do terminal. Você deverá ver uma resposta JSON com a mensagem "Você entrou no Microsoft Azure!".
Depois de entrar, a CLI do Azure exibe todas as suas assinaturas e indica 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.
Registre os provedores de recursos necessários em sua assinatura:

Observação

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. Confira mais informações em 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"
```
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
```
Use o comando az connectedk8s connect para habilitar o Arc no seu cluster do 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
```
Dica

O valor de $CLUSTER_NAME é automaticamente definido como o nome do seu codespace. Substitua a variável de ambiente se desejar usar um nome diferente.
Obtenha o objectId do aplicativo do Microsoft Entra ID que o serviço do Azure Arc usa em seu locatário e salve-o como uma variável de ambiente. Execute o seguinte comando exatamente como está, sem alterar o valor da GUID.
```
export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
```
Use o comando az connectedk8s enable-features para habilitar o suporte ao local personalizado em 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
```

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. As Operações do Azure IoT exigem 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 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 seguintes comandos CLI em seu terminal Codespaces.

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 devem 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.
<SCHEMA_REGISTRY_NAMESPACE>	Um nome para o namespace do registro de esquema. O namespace identifica exclusivamente um registro de esquema em um locatário.

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

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

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)

Implantar as Operações do Azure IoT

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

Execute os seguintes comandos CLI em seu terminal Codespaces.

Inicialize seu cluster para as 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 Azure IoT Operations 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ê pode ver o andamento na exibição de progresso da implantação no terminal.

Implantar 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) --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 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 login de forma 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, como o cluster está habilitado para Arc, você poderá usar o portal do Azure.

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

kubectl get pods -n azure-iot-operations

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

No portal do Azure, acesse o grupo de recursos que contém sua instância do Azure IoT Operations ou pesquise e selecione Azure IoT Operations.
Selecione o nome da sua instância das Operações do Azure IoT.
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, implantou esses componentes em seu cluster. Para esse cenário de teste, você tem um único 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 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 os Codespaces para esses inícios rápidos, exclua seu Codespace do GitHub.

Próxima etapa

Início Rápido: configure seu cluster

Compartilhar via