Distribuire moduli WebAssembly (WASM) e definizioni di grafi

I grafici del flusso di dati di Azure IoT Operations supportano i moduli WebAssembly (WASM) per l'elaborazione dati personalizzata all'edge. È possibile distribuire trasformazioni di dati e logica di business personalizzate come parte delle pipeline del flusso di dati.

Prerequisiti

• Distribuire un'istanza di Azure IoT Operations in un cluster Kubernetes abilitato per Arc. Per altre informazioni, vedere Deploy Azure IoT Operations.
• Configurare un endpoint del registro per consentire all'istanza di Operazioni di Azure IoT di accedere a un registro contenitori. Per altre informazioni, vedere Configurare gli endpoint del Registro di sistema.

Se si vuole usare un registro privato come Azure Container Registry (Registro Azure Container), è necessario:

• Accesso a un registro di contenitori, come Azure Container Registry (ACR), per archiviare moduli e grafici WASM.
• Installare l'interfaccia della riga di comando di OCI Registry As Storage (ORAS) per eseguire il push dei moduli WASM nel registro.

Informazioni generali

I moduli WASM nei grafici di flusso di dati e connettori di Azure IoT Operations consentono di elaborare i dati ai margini con prestazioni e sicurezza elevate. WASM viene eseguito in un ambiente in modalità sandbox e supporta Rust e Python.

Usare moduli predefiniti da un registro pubblico

Il modo più rapido per iniziare consiste nell'usare i moduli WASM di esempio predefiniti e le definizioni dei grafi direttamente dal registro contenitori GitHub pubblico. Questo approccio non richiede la configurazione di un registro privato, dell'interfaccia della riga di comando ORAS o di qualsiasi passaggio pull/push.

Creare un endpoint per il registro pubblico

Creare un endpoint del Registro di sistema che punti al Registro di sistema pubblico in cui sono ospitati i moduli di esempio:

resource publicRegistryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2025-10-01-preview' = {
  parent: aioInstance
  name: 'public-ghcr'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: 'ghcr.io/azure-samples/explore-iot-operations'
    authentication: {
      method: 'Anonymous'
      anonymousSettings: {}
    }
  }
}

apiVersion: connectivity.iotoperations.azure.com/v1
kind: RegistryEndpoint
metadata:
  name: public-ghcr
  namespace: azure-iot-operations
spec:
  host: ghcr.io/azure-samples/explore-iot-operations
  authentication:
    method: Anonymous
    anonymousSettings: {}

kubectl apply -f registry-endpoint.yaml

Dopo aver creato questo endpoint del Registro di sistema, è possibile farvi riferimento nei grafici del flusso di dati usando registryEndpointRef: public-ghcr. Sono disponibili i moduli di esempio e le definizioni di grafo seguenti:

Per usare il grafico semplice con il registro pubblico, vedere Esempio 1: Distribuzione di base con un modulo WASM e usare public-ghcr come nome dell'endpoint del Registro di sistema.

Usare un registro privato

Se è necessario usare moduli personalizzati o ospitare copie personalizzate dei moduli di esempio, configurare un registro contenitori privato, ad esempio Azure Container Registry (ACR).

Configurare il registro contenitori

Operazioni di Azure IoT richiede un registro contenitori per eseguire il pull di moduli WASM e definizioni di grafo. È possibile usare Azure Container Registry (ACR) o un altro registro compatibile con OCI.

Per creare e configurare un Azure Container Registry, vedere Deploy Azure Container Registry.

Installare l'interfaccia della riga di comando di ORAS

Usare l'interfaccia della riga di comando di ORAS per eseguire il push di moduli WASM e delle definizioni dei grafici nel registro contenitori. Per istruzioni di installazione, vedere Installare ORAS.

Eseguire il pull dei moduli di esempio dal registro pubblico

Usare moduli di esempio predefiniti:

# 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

Eseguire il push dei moduli nel registro

Dopo aver ottenuto i moduli e i grafici di esempio, esegui il push dei moduli e dei grafici nel registro contenitori. Sostituire <YOUR_ACR_NAME> con il nome del Azure Container Registry.

Per assicurarsi che i grafici e i moduli siano visibili nell'interfaccia utente Web dell'esperienza operativa, aggiungere i --config flag e --artifact-type come illustrato nell'esempio seguente:

# Log in to your ACR
az acr login --name <YOUR_ACR_NAME>

# Push modules to your registry
oras push <YOUR_ACR_NAME>.azurecr.io/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 <YOUR_ACR_NAME>.azurecr.io/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 <YOUR_ACR_NAME>.azurecr.io/temperature:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/window:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm window.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/snapshot:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm snapshot.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/format:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm format.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/humidity:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm humidity.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/collection:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm collection.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/enrichment:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm enrichment.wasm:application/wasm
oras push <YOUR_ACR_NAME>.azurecr.io/filter:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm filter.wasm:application/wasm

Aggiornare un modulo in un grafico in esecuzione

È possibile aggiornare un modulo WASM in un grafico in esecuzione senza arrestare il grafico. Ciò è utile quando si vuole aggiornare la logica di un operatore senza arrestare il flusso di dati. Ad esempio, per aggiornare il modulo di conversione della temperatura dalla versione 1.0.0 a 2.0.0, caricare la nuova versione come indicato di seguito:

oras push <YOUR_ACR_NAME>.azurecr.io/temperature:2.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm

Sviluppare moduli WASM personalizzati

Per creare logica di elaborazione dati personalizzata per i grafici del flusso di dati, sviluppare moduli WebAssembly in Rust o Python. I moduli personalizzati consentono di implementare logica di business specializzata, trasformazioni dei dati e analisi non disponibili negli operatori predefiniti.

Per indicazioni complete sullo sviluppo, tra cui:

• Configurazione dell'ambiente di sviluppo
• Creazione di operatori in Rust e Python
• Informazioni sul modello di dati e sulle interfacce
• Compilazione e test dei moduli

Vedere Sviluppare moduli WebAssembly per grafici del flusso di dati.

Per informazioni dettagliate sulla creazione e la configurazione delle definizioni di grafici YAML che definiscono i flussi di lavoro di elaborazione dati, vedere Configurare le definizioni dei grafici WebAssembly.

Requisiti dell'oggetto del Registro di sistema

L'esperienza operativa usa i metadati degli artefatti OCI per individuare e visualizzare grafici e moduli. Comprendere questi requisiti è importante quando si compilano pipeline CI/CD personalizzate, si copiano elementi tra registri o si risolvono i problemi relativi agli artefatti mancanti nell'interfaccia utente.

Il funzionamento dell'individuazione degli artefatti

Quando si esegue il push di un artefatto in un registro con ORAS, il manifesto OCI include due campi pertinenti:

• Tipo di media di configurazione: Identifica di che tipo di artefatto si tratta. L'esperienza operativa filtra questo campo per trovare grafici e moduli.
• Tipo di media del livello: descrive il formato del contenuto del file effettivo (YAML o WASM).

L'esperienza delle operazioni usa il tipo di supporto di configurazione per l'individuazione, non il tipo di supporto del livello. Se il tipo di supporto di configurazione manca o non è corretto, l'artefatto esiste nel Registro di sistema ma non viene visualizzato nell'interfaccia utente.

Tipi di supporti necessari

Per le definizioni del grafo, passare il tipo di supporto di configurazione con il flag --config.

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

Per i moduli WASM, passali con l'opzione --artifact-type:

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

Considerazioni sulla pipeline CI/CD

Se si usano pipeline automatizzate per copiare o alzare di livello gli artefatti tra registri (ad esempio, da un registro di gestione temporanea a un registro di produzione), verificare che la pipeline mantenga i metadati degli artefatti OCI. Alcuni strumenti rimuovono o sostituiscono il tipo di supporto di configurazione durante il trasferimento, facendo scomparire silenziosamente gli artefatti dall'esperienza delle operazioni.

Per verificare che un artefatto abbia i metadati corretti dopo il trasferimento, controllare il relativo manifesto:

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

L'output dovrebbe visualizzare:

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

Se configMediaType mostra un valore generico come application/vnd.oci.empty.v1+json, i metadati sono stati rimossi e l'artefatto deve essere nuovamente sottoposto a push con i flag corretti.

Contenuti correlati

• Sviluppare moduli WebAssembly per scrivere operatori in Rust e Python (incluso l'avvio rapido end-to-end)
• Configurare le definizioni del grafo WebAssembly per la struttura YAML del grafo e i parametri di configurazione
• Usare WebAssembly con grafi di flusso di dati per la configurazione delle risorse DataflowGraph e per gli esempi
• Compilare moduli WASM con l'estensione VS Code per lo sviluppo basato su IDE
• Configurare gli endpoint del Registro di sistema