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

Artigo
11/20/2024

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.

Também usamos o 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 suas 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:

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

Criar cluster

As Operações IoT do Azure podem ser implantadas no K3s no Ubuntu, no Serviço Kubernetes do Azure (AKS) Edge Essentials e no AKS no Azure Local. No entanto, para velocidade e conveniência, este guia de início rápido usa o GitHub Codespaces para hospedar seu cluster. Para saber como implantar as Operações IoT do Azure em um cluster no Windows ou no Ubuntu, consulte Preparar seu cluster Kubernetes habilitado para Azure Arc.

Nota

Os espaços de código são fáceis de configurar rapidamente e de desmontar mais tarde, mas não são adequados para avaliação de desempenho ou testes de escala. Use o GitHub Codespaces apenas para exploração.

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

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:

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

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

Parâmetro	Value
SUBSCRIPTION_ID	O seu ID de subscrição do Azure.
RESOURCE_GROUP	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 espaços de código. 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.

Selecione Criar novo espaço de código.
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.
Se solicitado, instale a extensão Codespaces do GitHub para Visual Studio Code e entre no GitHub.
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:

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 .
- Ou, depois de obter o erro localhost no navegador, copie o URL do navegador e execute curl "<URL>" em uma nova guia do terminal. Você verá uma resposta JSON com a mensagem "Você fez login no Microsoft Azure!".
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.
Registe os fornecedores de recursos necessários na sua subscrição:

Nota

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"
```
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 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.
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)
```
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
```

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.

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

Marcador de Posição	Value
<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.
<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.

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

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.

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.

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

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.
Selecione o nome da sua instância de Operações do Azure IoT.
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

Guia de início rápido: configurar o cluster

Partilhar via