Implantar módulos de WebAssembly (WASM) e definições de grafo

Os grafos de fluxo de dados de Operações do Azure IoT dão suporte a módulos WASM (WebAssembly) para processamento de dados personalizados na borda. Você pode implantar transformações de dados e lógica de negócios personalizadas como parte de seus pipelines de fluxo de dados.

Pré-requisitos

• Uma instância de Operações do Azure IoT implantada em um cluster do Kubernetes. Para obter mais informações, consulte Deploy Operações do Azure IoT.

• Um endpoint de registro que aponta para o registro de contêiner de onde você deseja extrair módulos e grafos. Para obter mais informações, consulte Configurar pontos de extremidade do Registro. Para começar sem configurar seu próprio repositório, use o endpoint público de exemplo ghcr.io descrito em Usar módulos pré-compilados de um repositório público.

Para enviar por push seus próprios módulos e grafos para um registro privado como Registro de Contêiner do Azure (ACR), você também precisa:

• Acesso a um registro de contêiner, como o ACR, para armazenar módulos e grafos WASM.
• A CLI do OCI Registry As Storage (ORAS) para enviar módulos WASM para o registro.

Os CLI do Azure exemplos deste artigo usam variáveis de ambiente para que você possa definir cada valor uma vez e então copiar e colar os comandos as-is. Se você está usando o ambiente Operações do Azure IoT Codespaces do quickstart, essas variáveis já estão definidas para você e você pode pular essa etapa. Caso contrário, defina as seguintes variáveis de ambiente no seu shell antes de executar os comandos.

Os seguintes scripts definem as variáveis de ambiente mais comumente usadas:

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

$SUBSCRIPTION_ID = "<subscription-id>"
$RESOURCE_GROUP = "<resource-group-name>"
$AIO_INSTANCE_NAME = "<instance-name>"
$CLUSTER_NAME = "<cluster-name>"
$LOCATION = "<region>"

Você só precisa definir as variáveis que este artigo utiliza. Este artigo pode usar variáveis adicionais de ambiente para nomes de recursos que você escolher. O artigo explica como posicioná-los onde são apresentados.

Visão geral

Os módulos WASM em grafos de fluxo de dados e conectores do Operações do Azure IoT permitem processar dados na borda com alto desempenho e segurança. O WASM é executado em um ambiente em área restrita e dá suporte a Rust e Python.

Usar módulos predefinidos de um registro público

Você pode usar os módulos de exemplo pré-construídos do WASM e as definições de grafos que são publicados no Registro de Contêineres público do GitHub (ghcr.io) sob azure-samples/explore-iot-operations.

Artefatos de exemplo disponíveis

Depois de criar o endpoint de registro public-ghcr, faça referência a esse endpoint nos grafos de fluxo de dados usando o registryEndpointRef: public-ghcr. Como o host do ponto de extremidade do registro é ghcr.io, inclua o caminho do repositório azure-samples/explore-iot-operations nas referências de artefatos. Os seguintes módulos de exemplo e definições de grafo estão disponíveis:

Para usar o grafo simples com o registro público, consulte Exemplo 1: Implantação básica com um módulo WASM e use public-ghcr como o nome do ponto de extremidade do registro.

Usar um registro privado

Se você precisar usar módulos personalizados ou quiser hospedar suas próprias cópias dos módulos de exemplo, configure um registro de contêiner privado como Registro de Contêiner do Azure (ACR).

Configurar o registro de contêiner

Operações do Azure IoT precisa de um registro de contêiner para obter módulos WASM e definições de grafo. Você pode usar Registro de Contêiner do Azure (ACR) ou outro registro compatível com OCI. Para criar uma instância do ACR, consulte Implantar Registro de Contêiner do Azure. Depois que o registro existir, crie um ponto de extremidade do Registro que aponte para ele – consulte Criar um ponto de extremidade do Registro.

Instalar a CLI do ORAS

Use a CLI do ORAS para enviar por push módulos WASM e definições de grafo para o registro de contêiner. Para obter instruções de instalação, consulte Instalar o ORAS.

Efetuar pull de módulos de exemplo do registro público

Use módulos de exemplo predefinidos:

# Pull sample modules and graphs
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/temperature:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/window:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/snapshot:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/format:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/humidity:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/collection:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/enrichment:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/filter:1.0.0

Enviar módulos por push para o registro

Ao obter os módulos e grafos de exemplo, envie-os por push para o registro de contêiner. Defina a ACR_NAME variável ambiente para o nome do seu Registro de Contêiner do Azure.

Escolha um layout de artefato

Os nomes de artefato que você usa ao fazer push de grafos e módulos determinam quais referências de módulo você precisa usar na definição do grafo. Para obter informações sobre como o host do ponto de extremidade de registro, o caminho do artefato e a referência do módulo se relacionam, consulte Caminhos de artefato e referências de módulo de grafo.

Para os grafos de exemplo do Azure, preserve o caminho do repositório de exemplo ao copiar os artefatos para seu próprio registro. As definições do grafo fazem referência a módulos usando esse caminho:

<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0

Use artifact: azure-samples/explore-iot-operations/graph-simple:1.0.0 no grafo de fluxo de dados. A definição do grafo usa module: "azure-samples/explore-iot-operations/temperature:1.0.0".

Para seus próprios grafos, você pode escolher um layout simples:

<YOUR_ACR_NAME>.azurecr.io/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/temperature:1.0.0

Use artifact: graph-simple:1.0.0 no grafo de fluxo de dados e module: "temperature:1.0.0" dentro da definição do grafo.

Ou então, escolha seu próprio layout aninhado:

<YOUR_ACR_NAME>.azurecr.io/factory/graphs/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/factory/graphs/temperature:1.0.0

Use artifact: factory/graphs/graph-simple:1.0.0 no grafo de fluxo de dados e module: "factory/graphs/temperature:1.0.0" dentro da definição do grafo.

Para garantir que os gráficos e módulos estejam visíveis na interface da experiência de operações na Web, adicione os --config e --artifact-type sinalizadores, conforme mostrado no exemplo a seguir.

# Log in to your ACR
az acr login --name $ACR_NAME

# Push modules to your registry
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-simple.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-complex.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/window:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm window.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/snapshot:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm snapshot.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/format:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm format.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/humidity:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm humidity.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/collection:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm collection.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/enrichment:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm enrichment.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/filter:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm filter.wasm:application/wasm

Atualizar um módulo em um grafo em execução

Você pode atualizar um módulo WASM em um grafo em execução sem parar o grafo. Isso é útil quando você deseja atualizar a lógica de um operador sem interromper o fluxo de dados. Por exemplo, para atualizar o módulo de conversão de temperatura da versão 1.0.0 para 2.0.0 no layout de artefato de exemplo Azure, carregue a nova versão da seguinte maneira:

oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:2.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm

Desenvolver módulos WASM personalizados

Para criar uma lógica de processamento de dados personalizada para seus grafos de fluxo de dados, desenvolva módulos WebAssembly no Rust ou Python. Os módulos personalizados permitem implementar lógica de negócios especializada, transformações de dados e análises que não estão disponíveis nos operadores internos.

Para diretrizes abrangentes de desenvolvimento, incluindo:

• Configurar o seu ambiente de desenvolvimento
• Criando operadores no Rust e no Python
• Noções básicas sobre o modelo de dados e as interfaces
• Compilar e testar seus módulos

Consulte Desenvolver módulos WebAssembly para grafos de fluxo de dados.

Para obter informações detalhadas sobre como criar e configurar as definições de grafo YAML que definem seus fluxos de trabalho de processamento de dados, consulte Configurar definições de grafo WebAssembly.

Requisitos de artefatos de registro

A experiência operacional utiliza os metadados dos artefatos do OCI para identificar e exibir gráficos e módulos. Entender esses requisitos é importante quando você cria pipelines personalizados de CI/CD, copia artefatos entre registros ou soluciona os problemas de artefatos ausentes na interface do usuário.

Como funciona a descoberta de artefatos

Ao enviar um artefato para um registro usando o ORAS, o manifesto OCI inclui dois campos relevantes:

• Configurar tipo de mídia: identifica que tipo de artefato este é. As operações experimentam filtros nesse campo para localizar grafos e módulos.
• Tipo de mídia de camada: descreve o formato de conteúdo do arquivo real (YAML ou WASM).

A experiência operacional utiliza o tipo de mídia de configuração para a descoberta, e não o tipo de mídia de camada. Se o tipo de mídia de configuração estiver ausente ou incorreto, o artefato existirá no registro, mas não aparecerá na interface do usuário.

Tipos de mídia necessários

Para definições de gráfico, passe o tipo de mídia de configuração com o sinalizador --config. Defina a REGISTRY variável de ambiente para o host do seu registro (por exemplo, <your-registry>.azurecr.io):

oras push $REGISTRY/my-graph:1.0.0 \
  --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml \
  graph.yaml:application/yaml \
  --disable-path-validation

Para módulos WASM, passe-o com o sinalizador --artifact-type:

oras push $REGISTRY/my-module:1.0.0 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  module.wasm:application/wasm

Considerações sobre o pipeline de CI/CD

Se você utiliza pipelines automatizados para copiar ou promover artefatos entre registros (por exemplo, de um registro de teste para um registro de produção), verifique se o pipeline preserva os metadados dos artefatos OCI. Algumas ferramentas removem ou substituem o tipo de mídia de configuração durante a transferência, o que faz com que os artefatos desapareçam silenciosamente da experiência de operações.

Para verificar se um artefato tem os metadados corretos após a transferência, inspecione seu manifesto:

oras manifest fetch $REGISTRY/my-graph:1.0.0 | jq '{mediaType, configMediaType: .config.mediaType}'

A saída deve mostrar:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "configMediaType": "application/vnd.microsoft.aio.graph.v1+yaml"
}

Se configMediaType exibir um valor genérico como application/vnd.oci.empty.v1+json, os metadados foram removidos e o artefato precisa ser reenviado com os sinalizadores corretos.

Conteúdo relacionado

• Desenvolver módulos WebAssembly para escrever operadores em Rust e Python (inclui início rápido de ponta a ponta)
• Configurar definições de gráfico do WebAssembly para estrutura YAML de gráfico e parâmetros de configuração
• Usar o WebAssembly com grafos de fluxo de dados para configuração de recursos do DataflowGraph e exemplos
• Compilar módulos WASM com extensão do VS Code para desenvolvimento baseado em IDE
• Configurar pontos de extremidade do registro