Implementación de módulos y definiciones de grafos de WebAssembly (WASM)

Los gráficos de flujo de datos de Operaciones de IoT de Azure admiten módulos de WebAssembly (WASM) para el procesamiento de datos personalizado en el borde. Puede implementar transformaciones de datos y lógica de negocios personalizadas como parte de las canalizaciones de flujo de datos.

Prerrequisitos

• Instancia de Operaciones de IoT de Azure implementada en un clúster de Kubernetes. Para obtener más información, consulte Deploy Operaciones de IoT de Azure.

• Punto de conexión del registro que apunta al registro de contenedores del que desea extraer módulos y grafos. Para más información, consulte Configuración de puntos de conexión del Registro. Para empezar sin configurar su propio registro, use el punto de conexión de ejemplo público ghcr.io descrito en Uso de módulos creados previamente desde un registro público.

Para insertar sus propios módulos y gráficos en un registro privado como Azure Container Registry (ACR), también necesita lo siguiente:

• Acceso a un registro de contenedor como ACR para almacenar gráficos y módulos WASM.
• La CLI de OCI Registry As Storage (ORAS) para enviar módulos WASM al registro.

Los CLI de Azure ejemplos de este artículo usan variables de entorno para que puedas establecer cada valor una vez y luego copiar y pegar los comandos as-is. Si usas el entorno Operaciones de IoT de Azure Codespaces del quickstart, estas variables ya están configuradas para ti y puedes saltarte este paso. De lo contrario, configura las siguientes variables de entorno en tu shell antes de ejecutar los comandos.

Los siguientes scripts establecen las variables de entorno más 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>"

Solo necesitas establecer las variables que utiliza este artículo. Este artículo podría utilizar variables de entorno adicionales para los nombres de recursos que elijas. El artículo explica cómo situarlos donde se introducen.

Información general

Los módulos WASM en los gráficos de flujo de datos y conectores de Operaciones de IoT de Azure permiten procesar datos en el borde con un alto rendimiento y seguridad. WASM se ejecuta en un entorno de espacio aislado y admite Rust y Python.

Uso de módulos creados previamente desde un registro público

Puedes usar los módulos de ejemplo preconstruidos de WASM y las definiciones de grafos que se publican en el Registro de Contenedores público de GitHub (ghcr.io) bajo azure-samples/explore-iot-operations.

Artefactos de ejemplo disponibles

Después de crear el punto de conexión de registro public-ghcr, haga referencia a él en los grafos de flujo de datos mediante registryEndpointRef: public-ghcr. Dado que el host del punto de conexión del registro es ghcr.io, incluya la ruta del repositorio azure-samples/explore-iot-operations en las referencias de artefactos. Están disponibles los siguientes módulos de ejemplo y definiciones de grafos:

Para usar el gráfico simple con el registro público, vea Ejemplo 1: Implementación básica con un módulo WASM y uso public-ghcr como nombre del punto de conexión del Registro.

Uso de un registro privado

Si necesita usar módulos personalizados o desea hospedar sus propias copias de los módulos de ejemplo, configure un registro de contenedor privado como Azure Container Registry (ACR).

Configuración del registro de contenedor

Operaciones de IoT de Azure necesita un registro de contenedor para extraer módulos WASM y definiciones de grafos. Puede usar Azure Container Registry (ACR) u otro registro compatible con OCI. Para crear una instancia de ACR, consulte Implementación de Azure Container Registry. Una vez que el registro exista, cree un punto de conexión del Registro que apunte a él; consulte Creación de un punto de conexión del Registro.

Instalar la CLI de ORAS

Use la CLI de ORAS para insertar módulos de WASM y definiciones de grafos en el registro de contenedor. Para obtener instrucciones de instalación, consulte Instalar ORAS.

Extracción de módulos de ejemplo del registro público

Use módulos de ejemplo creados previamente:

# 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

Inserción de módulos en el Registro

Una vez que tenga los módulos y gráficos de ejemplo, insértelos en el registro de contenedor. Define la variable de entorno ACR_NAME con el nombre de tu registro de contenedor de Azure.

Elección de un diseño de artefacto

Los nombres de artefactos que utilice al insertar grafos y módulos determinan las referencias de módulos que necesita dentro de la definición del grafo. Para obtener información sobre cómo se relacionan el host del punto de conexión del registro, la ruta del artefacto y la referencia del módulo, consulte Rutas de artefactos y referencias de módulos en el gráfico.

Para los grafos de ejemplo de Azure, mantenga la ruta del repositorio de ejemplo al copiar artefactos en su propio registro. Las definiciones de grafos hacen referencia a los módulos usando esa ruta:

<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 en el gráfico de flujo de datos. La definición del grafo usa module: "azure-samples/explore-iot-operations/temperature:1.0.0".

Para sus propios gráficos, puede elegir un diseño plano:

<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 en el gráfico de flujo de datos y module: "temperature:1.0.0" dentro de la definición del grafo.

O elija su propio diseño anidado:

<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 en el gráfico de flujo de datos y module: "factory/graphs/temperature:1.0.0" dentro de la definición del grafo.

Para asegurarse de que los grafos y módulos están visibles en la interfaz de usuario web de la experiencia de operaciones, agregue las marcas --config y --artifact-type como se muestra en el ejemplo siguiente:

# 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

Actualización de un módulo en un grafo en ejecución

Puede actualizar un módulo WASM en un grafo en ejecución sin detener el gráfico. Esto resulta útil cuando desea actualizar la lógica de un operador sin detener el flujo de datos. Por ejemplo, para actualizar el módulo de conversión de temperatura de la versión 1.0.0 a 2.0.0 en el diseño de artefacto de ejemplo de Azure, cargue la nueva versión de la siguiente manera:

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

Desarrollo de módulos de WASM personalizados

Para crear lógica de procesamiento de datos personalizada para los gráficos de flujo de datos, desarrolle módulos WebAssembly en Rust o Python. Los módulos personalizados permiten implementar lógica de negocios especializada, transformaciones de datos y análisis que no están disponibles en los operadores integrados.

Para obtener instrucciones de desarrollo completas, que incluyan:

• Configuración del entorno de desarrollo
• Creación de operadores en Rust y Python
• Descripción del modelo de datos e interfaces
• Compilación y prueba de los módulos

Consulte Desarrollo de módulos de WebAssembly para obtener grafos de flujo de datos.

Para obtener información detallada sobre cómo crear y configurar las definiciones de grafos de YAML que definen los flujos de trabajo de procesamiento de datos, consulte Configurar definiciones de grafos de WebAssembly.

Requisitos de registro de artefactos

La experiencia de operaciones usa metadatos de artefactos OCI para detectar y mostrar gráficos y módulos. Comprender estos requisitos es importante al compilar canalizaciones de CI/CD personalizadas, copiar artefactos entre registros o solucionar problemas de artefactos que faltan en la interfaz de usuario.

Funcionamiento de la detección de artefactos

Al insertar un artefacto en un registro con ORAS, el manifiesto de OCI incluye dos campos pertinentes:

• Tipo de medio de configuración: identifica qué tipo de artefacto es. La experiencia de operaciones filtra este campo para buscar gráficos y módulos.
• Tipo de medio de capa: describe el formato de contenido del archivo real (YAML o WASM).

La experiencia de operaciones utiliza el tipo de medio de configuración para la detección, no el tipo de medio de capa. Si falta el tipo de medio de configuración o es incorrecto, el artefacto existe en el Registro, pero no aparece en la interfaz de usuario.

Tipos de medios necesarios

Para las definiciones de gráficos, pase el tipo de medio de la configuración con el indicador --config. Establece la REGISTRY variable de entorno a tu host de registro (por ejemplo, <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 los módulos WASM, páselo con la --artifact-type bandera:

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

Observaciones sobre canalizaciones de CI/CD

Si usa canalizaciones automatizadas para copiar o promover artefactos entre registros (por ejemplo, desde un registro de ensayo a un registro de producción), compruebe que la canalización conserva los metadatos del artefacto de OCI. Algunas herramientas quitan o reemplazan el tipo de medio de configuración durante la transferencia, lo que hace que los artefactos desaparezcan silenciosamente de la experiencia de operaciones.

Para comprobar que un artefacto tiene los metadatos correctos después de la transferencia, inspeccione su manifiesto:

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

La salida debe mostrar:

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

Si configMediaType muestra un valor genérico como application/vnd.oci.empty.v1+json, se han eliminado los metadatos y el artefacto debe volver a subirse con las marcas correctas.

Contenido relacionado

• módulos Develop WebAssembly para escribir operadores en Rust y Python (incluye inicio rápido de un extremo a otro)
• Configura las definiciones de grafos de WebAssembly para la estructura YAML y los parámetros de configuración de grafos
• Uso de WebAssembly con gráficos de flujo de datos para la configuración y ejemplos de recursos de DataflowGraph
• Compilación de módulos WASM con la extensión de VS Code para el desarrollo basado en IDE
• Configuración de puntos de conexión del Registro