Merge pull request #314808 from dominicbetts/aio-config-notes

AIO: Emphasize Kubernetes CR messaging

Author: prmerger-automator[bot]

articles/iot-operations/connect-to-cloud/overview-dataflow-comparison.md

@@ -18,13 +18,13 @@ Azure IoT Operations provides two ways to process and route data: **data flows**
 
 ## What are data flows?
 
-A [data flow](overview-dataflow.md) is a simple, linear pipeline that moves data from a source to a destination with optional transformations. The transformation stage runs three operations in a fixed order: enrich, filter, then map. You configure a data flow by creating a `Dataflow` custom resource.
+A [data flow](overview-dataflow.md) is a simple, linear pipeline that moves data from a source to a destination with optional transformations. The transformation stage runs three operations in a fixed order: enrich, filter, then map. You configure a data flow by using the operations experience web UI, the Azure CLI, or Azure Resource Manager templates.
 
 Data flows are generally available and support all endpoint types.
 
 ## What are data flow graphs?
 
-A [data flow graph](concept-dataflow-graphs.md) is a composable, graph-based pipeline that connects multiple transforms in any topology you define. You can chain, branch, and merge processing steps. Each transform is a pre-built processing unit (map, filter, branch, window, enrichment) that you configure with rules. You configure a data flow graph by creating a `DataflowGraph` custom resource.
+A [data flow graph](concept-dataflow-graphs.md) is a composable, graph-based pipeline that connects multiple transforms in any topology you define. You can chain, branch, and merge processing steps. Each transform is a pre-built processing unit (map, filter, branch, window, enrichment) that you configure with rules. You configure a data flow graph by using the operations experience web UI, the Azure CLI, or Azure Resource Manager templates.
 
 Data flow graphs support MQTT, Kafka, and OpenTelemetry endpoints.
 

articles/iot-operations/connect-to-cloud/overview-dataflow.md

@@ -13,7 +13,7 @@ ms.date: 03/19/2026
 
 # Process and route data with data flows
 
-Data flows simplify the setup of data paths to move, transform, and enrich data. By using data flows, you can connect various data sources and perform data operations. The data flow component is part of Azure IoT Operations, which you deploy as an Azure Arc extension. You configure a data flow by using Kubernetes custom resource definitions (CRDs).
+Data flows simplify the setup of data paths to move, transform, and enrich data. By using data flows, you can connect various data sources and perform data operations. The data flow component is part of Azure IoT Operations, which you deploy as an Azure Arc extension. You configure a data flow by using the operations experience web UI, the Azure CLI, or Azure Resource Manager templates.
 
 You can write configurations for various use cases, such as:
 
@@ -50,13 +50,13 @@ You can apply transformations to data during the processing stage to perform var
 
 ### Configuration and deployment
 
-Specify the configuration by using Kubernetes CRDs. Based on this configuration, the data flow operator creates data flow instances to ensure high availability and reliability.
+Specify the configuration by using the operations experience web UI, the Azure CLI, or Azure Resource Manager templates. Based on this configuration, the data flow operator creates data flow instances to ensure high availability and reliability.
 
 ## Benefits
 
 - **Simplified setup**: Easily connect data sources and destinations.
 - **Flexible transformations**: Perform a wide range of data operations.
-- **Scalable configuration**: Use Kubernetes CRDs for scalable and manageable configurations.
+- **Scalable configuration**: Use Azure tools for scalable and manageable configurations.
 - **High availability**: Kubernetes native resource ensures reliability.
 
 By using data flows, you can efficiently manage your data paths. You can ensure that data is accurately sent, transformed, and enriched to meet your operational needs.

articles/iot-operations/discover-manage-assets/concept-assets-devices.md

@@ -72,6 +72,8 @@ An asset is a configuration resource that represents a physical device or asset
 - An Azure Resource Manager resource in the cloud.
 - A Kubernetes custom resource at the edge.
 
+The cloud is always the source of truth for asset configuration. Always create and modify assets through Azure—by using the operations experience, the Azure portal, the Azure CLI, or ARM/Bicep templates. Don't create or edit the Kubernetes custom resources directly on the cluster.
+
 When you define an asset by using the operations experience or the Azure IoT Operations CLI, set up schema information like data points, tags, events, and streams for each asset.
 
 The type of inbound endpoint that the asset connects to determines what schema elements you define for the asset. For example, if the asset connects to an OPC UA server, define tags and events. If the asset connects to a media resource, define streams.

articles/iot-operations/discover-manage-assets/overview-manage-assets.md

@@ -107,6 +107,9 @@ Device Registry uses namespaces to organize assets and devices. Each Azure IoT O
 
 Manage devices and assets through the operations experience or through Azure APIs and tools like Azure Resource Graph. Changes made in the cloud sync to the edge and appear as custom resources in the Kubernetes cluster.
 
+> [!IMPORTANT]
+> The cloud is always the source of truth for device and asset configuration. Always create and modify devices and assets through Azure—by using the operations experience, the Azure portal, the Azure CLI, or ARM/Bicep templates. Don't create or edit Kubernetes custom resources directly on the cluster. Resources created directly on the cluster don't sync to the cloud, and direct edits to existing custom resources on the cluster can cause the cloud and edge to go out of sync.
+
 ### Akri services
 
 Akri services in Azure IoT Operations:

articles/iot-operations/discover-manage-assets/overview-opc-ua-connector.md

@@ -48,7 +48,7 @@ The connector for OPC UA supports the following features as part of Azure IoT Op
 | Certificate trust list | Yes | For secure, encrypted OPC UA connections |
 | OpenTelemetry integration | Yes | |
 | Automatic reconnection | Yes | Reconnects to OPC UA servers after failures |
-| Multiple server connections | Yes | Configured using Kubernetes `device` CRs |
+| Multiple server connections | Yes | Configured using `device` resources |
 | OPC UA PubSub format | Yes | JSON-encoded data value changes |
 | CloudEvents headers | Yes | Message headers as MQTT user properties |
 | OPC UA events | Yes | Predefined event fields |

articles/iot-operations/manage-mqtt-broker/overview-broker.md

@@ -53,6 +53,9 @@ For configuration, the MQTT broker uses several Kubernetes custom resources to d
 - A Broker resource can have up to three [BrokerListeners](/rest/api/iotoperations/broker-listener), each of which listens for incoming MQTT connections on the specified service type (`NodePort`, `LoadBalancer`, or `ClusterIP`). Each BrokerListener resource can have multiple ports.
 - Each port within a BrokerListener resource can be associated with a [BrokerAuthentication](/rest/api/iotoperations/broker-authentication) resource and a [BrokerAuthorization](/rest/api/iotoperations/broker-authorization) resource. These authentication and authorization policies determine which clients can connect to the port and what actions they can perform on the broker.
 
+> [!IMPORTANT]
+> Use the Azure portal or Azure CLI to manage broker listeners.
+
 The relationship between Broker and BrokerListener is *one-to-many*, while the relationship between BrokerListener and BrokerAuthentication/BrokerAuthorization is *many-to-many*. The entity relationship diagram for these resources is:
 
 <!-- ```mermaid

articles/iot-operations/troubleshoot/tips-tools.md

@@ -27,6 +27,9 @@ However, in a debug or test environment you can  manage the components of Azure
 - Unless you enable resource sync in Azure IoT Operations using `az iot ops enable-rsync` command, changes made to the resources using Kubernetes deployment manifests are not synced to Azure. To learn more about resource sync, see [Resource sync](/azure/azure-arc/data/resource-sync).
 - Even if resource sync is enabled, brand new resources created using Kubernetes deployment manifests are not synced to Azure. Only changes to existing resources are synced.
 
+> [!IMPORTANT]
+> In production, the cloud is always the source of truth. Always create and modify resources through Azure—by using the operations experience, the Azure portal, the Azure CLI, or ARM/Bicep templates. Creating resources directly on the cluster or editing existing Kubernetes custom resources can cause the cloud and edge to go out of sync and isn't supported in production environments.
+
 ### `kubectl`
 
 `kubectl` is the Kubernetes command-line tool for managing your cluster. It has many capabilities that you can learn about in the official [kubernetes documentation](https://kubernetes.io/docs/reference/kubectl/introduction/). This article describes the common uses for `kubectl` when you're working with Azure IoT Operations such as listing the running pods and viewing logs.