Fix WASM docs: add public registry path, fix links, add troubleshooting

jlian · jlian · commit 4abc6590e07e · 2026-02-19T16:16:34.000-08:00
Based on MaibornWolff partner feedback on AIO 1.2.112:

- Add ghcr.io public registry quickstart path to reduce getting-started
  friction (no ACR setup needed for evaluation)
- Add registry endpoint examples for ghcr.io with anonymous auth
- Fix broken cross-reference link in configure-wasm-graph-definitions.md
  (pointed to connect-to-cloud/ instead of develop-edge-apps/)
- Add clear Data Flow vs Data Flow Graph distinction note
- Add troubleshooting section for RegistryEndpoint not found errors
- Update host pattern docs to show non-ACR registries are supported
- Improve prerequisites with two clear paths (public vs private registry)
diff --git a/articles/iot-operations/connect-to-cloud/howto-dataflow-graph-wasm.md b/articles/iot-operations/connect-to-cloud/howto-dataflow-graph-wasm.md
@@ -26,7 +26,12 @@ Azure IoT Operations data flow graphs support WebAssembly (WASM) modules for cus
 ## Prerequisites
 
 - Deploy an Azure IoT Operations instance on an Arc-enabled Kubernetes cluster. For more information, see [Deploy Azure IoT Operations](../deploy-iot-ops/howto-deploy-iot-operations.md).
-- Configure your container registry and add the sample graph definitions and WASM modules by following guidance in [Deploy WebAssembly (WASM) modules and graph definitions](../develop-edge-apps/howto-deploy-wasm-graph-definitions.md).
+- Configure a registry endpoint to access WASM modules and graph definitions. You have two options:
+  - **Quick start with public registry**: Create a registry endpoint pointing to `ghcr.io/azure-samples/explore-iot-operations` with anonymous authentication. See [Use prebuilt modules from a public registry](../develop-edge-apps/howto-deploy-wasm-graph-definitions.md#use-prebuilt-modules-from-a-public-registry) for instructions.
+  - **Private registry**: Set up your own container registry and push the sample modules by following guidance in [Deploy WebAssembly (WASM) modules and graph definitions](../develop-edge-apps/howto-deploy-wasm-graph-definitions.md).
+
+> [!NOTE]
+> **Data flows vs. data flow graphs**: A *data flow* is a pipeline that moves and transforms data between endpoints using built-in transformations. A *data flow graph* extends data flows with custom processing logic implemented as WebAssembly modules. Data flow graphs use YAML graph definitions that specify how WASM operators connect, while the data flow graph resource wraps this definition and maps its abstract source/sink operations to concrete endpoints (MQTT topics, Kafka topics, etc.). Use data flows for built-in transformations and data flow graphs when you need custom processing logic.
 
 ## Overview
 
@@ -1056,6 +1061,50 @@ Registry endpoints provide access to container registries for pulling WASM modul
 For detailed configuration information, see [Configure registry endpoints](../develop-edge-apps/howto-configure-registry-endpoint.md).
 
 
+## Troubleshoot data flow graphs
+
+### RegistryEndpoint not found
+
+If the data flow graph fails to start and reports that it can't find the registry endpoint, verify the following:
+
+1. **Registry endpoint name matches**: The `registryEndpointRef` value in your data flow graph must exactly match the `name` of your `RegistryEndpoint` resource. Check for typos and case sensitivity.
+
+   ```bash
+   # List all registry endpoints in the namespace
+   kubectl get registryendpoints -n azure-iot-operations
+   ```
+
+1. **Registry endpoint is in the correct namespace**: The registry endpoint must be in the `azure-iot-operations` namespace (or the same namespace as your data flow graph).
+
+1. **Registry endpoint is ready**: Check the status of your registry endpoint:
+
+   ```bash
+   kubectl describe registryendpoint <REGISTRY_ENDPOINT_NAME> -n azure-iot-operations
+   ```
+
+1. **Authentication is configured correctly**: If using managed identity, ensure the Azure IoT Operations Arc extension has `AcrPull` permissions on the registry. If using anonymous authentication with a public registry, verify the host URL is correct.
+
+1. **Artifacts exist in the registry**: Verify that the graph definition and WASM modules referenced in your graph are available at the expected tags in the registry:
+
+   ```bash
+   # Check if artifacts exist (example with ORAS)
+   oras manifest fetch <REGISTRY_HOST>/graph-simple:1.0.0
+   ```
+
+### Data flow graph is running but not processing data
+
+If the data flow graph is deployed but messages aren't being processed:
+
+1. **Check data flow graph status**: Look for errors in the data flow graph resource status:
+
+   ```bash
+   kubectl get dataflowgraph <GRAPH_NAME> -n azure-iot-operations -o yaml
+   ```
+
+1. **Verify MQTT topics**: Ensure the source topics in your data flow graph match the topics where you're publishing data.
+
+1. **Check timestamps**: Data flow graphs use Hybrid Logical Clock (HLC) timestamps for message processing. Include the `__ts` user property when publishing MQTT messages to ensure timely processing.
+
 ## Related content
 
 - [Configure MQTT data flow endpoints](howto-configure-mqtt-endpoint.md)
diff --git a/articles/iot-operations/develop-edge-apps/howto-configure-registry-endpoint.md b/articles/iot-operations/develop-edge-apps/howto-configure-registry-endpoint.md
@@ -180,10 +180,11 @@ This section describes the configuration options available for registry endpoint
 The `host` property specifies the container registry hostname. For ACR, use the format `<registry-name>.azurecr.io`. The host property supports HTTPS URLs or just the hostname.
 
 **Examples**:
-- `myregistry.azurecr.io`
-- `https://myregistry.azurecr.io`
+- `myregistry.azurecr.io` (Azure Container Registry)
+- `ghcr.io/azure-samples/explore-iot-operations` (GitHub Container Registry with path)
+- `docker.io/myorg` (Docker Hub)
 
-**Pattern**: Must match the pattern `^(https:\/\/)?[a-zA-Z0-9\-]+\.azurecr\.io$` for ACR.
+The host property supports any OCI-compatible registry hostname, with an optional path prefix for registries that use repository namespaces.
 
 ### Authentication methods
 
@@ -303,16 +304,65 @@ ACR is the recommended container registry for Azure IoT Operations. ACR provides
 1. **Configure permissions**: Ensure the Azure IoT Operations managed identity has `AcrPull` permissions on the registry.
 1. **Push artifacts**: Upload your WASM modules and graph definitions to the registry using tools like ORAS CLI.
 
+## Use a public registry like GitHub Container Registry (ghcr.io)
+
+You can configure a registry endpoint to point directly at a public OCI-compatible registry. This approach lets you use prebuilt WASM modules and graph definitions without setting up your own private registry, which is ideal for getting started quickly or for evaluation.
+
+For example, the Azure IoT Operations sample WASM modules and graph definitions are published at `ghcr.io/azure-samples/explore-iot-operations`. You can create a registry endpoint that points directly to this public registry by using anonymous authentication.
+
+# [Bicep](#tab/bicep)
+
+```bicep
+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: {}
+    }
+  }
+}
+```
+
+# [Kubernetes](#tab/kubernetes)
+
+```yaml
+apiVersion: connectivity.iotoperations.azure.com/v1beta1
+kind: RegistryEndpoint
+metadata:
+  name: public-ghcr
+  namespace: azure-iot-operations
+spec:
+  host: ghcr.io/azure-samples/explore-iot-operations
+  authentication:
+    method: Anonymous
+    anonymousSettings: {}
+```
+
+---
+
+After you create this registry endpoint, you can reference it in your data flow graph as `registryEndpointRef: public-ghcr`. No ORAS pull/push steps are needed because the runtime pulls the artifacts directly from the public registry.
+
+> [!NOTE]
+> Public registries don't require authentication, but they may have rate limits. For production workloads, consider using a private registry like Azure Container Registry.
+
 ## Other container registries
 
-Registry endpoints also support other OCI-compatible container registries such as:
+Registry endpoints support any OCI-compatible container registry, including:
 
 - Docker Hub
+- GitHub Container Registry (ghcr.io)
 - Harbor
 - AWS Elastic Container Registry (ECR)
 - Google Container Registry (GCR)
 
-For these registries, you typically use artifact pull secrets for authentication, unless they support Azure managed identity.
+For public registries, use anonymous authentication. For private registries, use artifact pull secrets or managed identity authentication as appropriate.
 
 ## Next steps
 
diff --git a/articles/iot-operations/develop-edge-apps/howto-configure-wasm-graph-definitions.md b/articles/iot-operations/develop-edge-apps/howto-configure-wasm-graph-definitions.md
@@ -281,4 +281,4 @@ For a complete implementation example, see the [branch module](https://github.co
 
 - [Develop WebAssembly modules for data flow graphs](howto-develop-wasm-modules.md)
 - [Use WebAssembly with data flow graphs](../connect-to-cloud/howto-dataflow-graph-wasm.md)
-- [Configure registry endpoints](../connect-to-cloud/howto-configure-registry-endpoint.md)
+- [Configure registry endpoints](howto-configure-registry-endpoint.md)
diff --git a/articles/iot-operations/develop-edge-apps/howto-deploy-wasm-graph-definitions.md b/articles/iot-operations/develop-edge-apps/howto-deploy-wasm-graph-definitions.md
@@ -23,16 +23,93 @@ Azure IoT Operations data flow graphs support WebAssembly (WASM) modules for cus
 ## Prerequisites
 
 - Deploy an Azure IoT Operations instance on an Arc-enabled Kubernetes cluster. For more information, see [Deploy Azure IoT Operations](../deploy-iot-ops/howto-deploy-iot-operations.md).
-- Use a container registry like Azure Container Registry (ACR) to store WASM modules and graphs.
-- Configure a registry endpoint to enable your Azure IoT Operations instance to access your container registry. For more information, see [Configure registry endpoints](howto-configure-registry-endpoint.md).
+- Configure a registry endpoint to enable your Azure IoT Operations instance to access a container registry. For more information, see [Configure registry endpoints](howto-configure-registry-endpoint.md).
+
+If you want to use a private registry like Azure Container Registry (ACR), you also need:
+
+- Access to a container registry like ACR to store WASM modules and graphs.
 - Install the OCI Registry As Storage (ORAS) CLI to push WASM modules to the registry.
-- Develop custom WASM modules by following guidance in [Build WASM modules for data flows in VS Code](howto-build-wasm-modules-vscode.md) or [Develop WebAssembly (WASM) modules and graph definitions for data flow graphs](howto-develop-wasm-modules.md).
+
+> [!TIP]
+> For a quick start without setting up a private registry, you can use the prebuilt sample modules directly from the public GitHub Container Registry (ghcr.io). See [Use prebuilt modules from a public registry](#use-prebuilt-modules-from-a-public-registry) for instructions.
 
 ## Overview
 
 WASM modules in Azure IoT Operations data flow graphs and connectors let you process data at the edge with high performance and security. WASM runs in a sandboxed environment and supports Rust and Python.
 
-## Set up container registry
+## Use prebuilt modules from a public registry
+
+The fastest way to get started is to use the prebuilt sample WASM modules and graph definitions directly from the public GitHub Container Registry. This approach doesn't require setting up a private registry, ORAS CLI, or any pull/push steps.
+
+### Create a registry endpoint for the public registry
+
+Create a registry endpoint that points to the public registry where the sample modules are hosted:
+
+# [Bicep](#tab/bicep)
+
+```bicep
+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: {}
+    }
+  }
+}
+```
+
+# [Kubernetes](#tab/kubernetes)
+
+```yaml
+apiVersion: connectivity.iotoperations.azure.com/v1beta1
+kind: RegistryEndpoint
+metadata:
+  name: public-ghcr
+  namespace: azure-iot-operations
+spec:
+  host: ghcr.io/azure-samples/explore-iot-operations
+  authentication:
+    method: Anonymous
+    anonymousSettings: {}
+```
+
+Apply the manifest:
+
+```bash
+kubectl apply -f registry-endpoint.yaml
+```
+
+---
+
+After you create this registry endpoint, you can reference it in your data flow graphs by using `registryEndpointRef: public-ghcr`. The following sample modules and graph definitions are available:
+
+| Artifact | Description |
+|----------|-------------|
+| `graph-simple:1.0.0` | Simple temperature conversion graph definition |
+| `graph-complex:1.0.0` | Multi-sensor processing graph definition |
+| `temperature:1.0.0` | Temperature conversion module (Fahrenheit to Celsius) |
+| `window:1.0.0` | Time-based windowing module |
+| `snapshot:1.0.0` | Image processing and object detection module |
+| `format:1.0.0` | Image format conversion module |
+| `humidity:1.0.0` | Humidity data processing module |
+| `collection:1.0.0` | Multi-sensor data aggregation module |
+| `enrichment:1.0.0` | Metadata enrichment module |
+| `filter:1.0.0` | Data filtering module |
+
+To use the simple graph with the public registry, see [Example 1: Basic deployment with one WASM module](../connect-to-cloud/howto-dataflow-graph-wasm.md#example-1-basic-deployment-with-one-wasm-module) and use `public-ghcr` as the registry endpoint name.
+
+## Use a private registry
+
+If you need to use custom modules or want to host your own copies of the sample modules, set up a private container registry like Azure Container Registry (ACR).
+
+### Set up container registry
 
 Azure IoT Operations needs a container registry to pull WASM modules and graph definitions. You can use Azure Container Registry (ACR) or another OCI-compatible registry.
 
