Shared endpoints

Author: dominicbetts

articles/iot-operations/discover-manage-assets/howto-configure-opc-ua.md

@@ -435,7 +435,7 @@ Now you can define the events associated with the event group. To add OPC UA eve
 
 # [Azure CLI](#tab/cli)
 
-To add an event group and events to an existing asset, use the `az iot ops ns asset opcua event-group` and `az iot ops ns asset custom event` commands:
+To add an event group and events to an existing asset, use the `az iot ops ns asset opcua event-group` and `az iot ops ns asset opcua event` commands:
 
 ```azurecli
 # Add an event group to the thermostat asset
@@ -444,17 +444,17 @@ az iot ops ns asset opcua event-group add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
-  --name alerts
+  --name alerts \
+  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600
 
 # Add an event to the event group
-az iot ops ns asset custom event add \
+az iot ops ns asset opcua event add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
   --event-group alerts \
   --name serverObjectNotifier \
-  --data-source "ns=0;i=2253" \
-  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600
+  --data-source "ns=0;i=2253"
 
 # List the event groups for the asset
 az iot ops ns asset opcua event-group list \
@@ -469,7 +469,7 @@ When you add an event group by using the Azure CLI, you can configure:
 - Publishing interval and queue size
 - Event destinations (MQTT topic, QoS, retain, TTL)
 
-To add individual events to an event group, use the `az iot ops ns asset custom event add` command with the `--event-group` parameter.
+To add individual events to an event group, use the `az iot ops ns asset opcua event add` command with the `--event-group` parameter.
 
 To remove an event group, use the `az iot ops ns asset opcua event-group remove` command.
 
@@ -542,14 +542,13 @@ The following screenshot shows an example event filter:
 The following command updates an existing event definition to include an event filter by using the `config` parameter:
 
 ```azurecli
-az iot ops ns asset custom event add \
+az iot ops ns asset opcua event add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
   --event-group alerts \
   --name serverObjectNotifier \
   --data-source "ns=0;i=2253" \
-  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600 \
   --replace true \
   --config "{\"eventFilter\":{\"selectClauses\":[{\"browsePath\":\"EventId\",\"typeDefinitionId\":\"ns=0;i=2041\",\"fieldId\":\"myEventId\"},{\"browsePath\":\"EventType\",\"typeDefinitionId\":\"ns=0;i=2041\",\"fieldId\":\"EventType\"},{\"browsePath\":\"SourceName\",\"typeDefinitionId\":\"\",\"fieldId\":\"mySourceName\"},{\"browsePath\":\"Severity\",\"typeDefinitionId\":\"\",\"fieldId\":\"Severity\"}]}}"
 ```
@@ -875,6 +874,72 @@ To delete individual resources by using Bicep, see [Deployment stacks](/azure/az
 
 ---
 
+
+## Configure a shared endpoint
+
+By default, each asset opens its own dedicated OPC UA session. You can configure a *shared* endpoint so that the connector uses a single session for all assets that reference the endpoint. To learn more about shared endpoints and when to use them, see [Shared endpoint mode](overview-opc-ua-connector.md#shared-endpoint-mode).
+
+To enable shared mode, set `"shared": true` in the `additionalConfiguration` JSON of a device inbound endpoint:
+
+```json
+{
+  "properties": {
+    "endpoints": {
+      "inbound": {
+        "my-opcua-endpoint": {
+          "address": "opc.tcp://my-plc.my-namespace:4840",
+          "endpointType": "Microsoft.OpcUa",
+          "authentication": {
+            "method": "Anonymous"
+          },
+          "additionalConfiguration": "{\"shared\": true}"
+        }
+      }
+    }
+  }
+}
+```
+
+If you omit the `shared` property from `additionalConfiguration`, the default value is `false` and each asset opens its own dedicated OPC UA session.
+
+The `shared` flag is also supported on legacy `AssetEndpointProfile` resources. However, for new deployments, use the device/asset (namespaced) resource model.
+
+Multiple assets can then reference the same shared endpoint:
+
+```yaml
+apiVersion: namespaces.deviceregistry.microsoft.com/v1
+kind: Asset
+metadata:
+  name: asset-temperature
+  namespace: azure-iot-operations
+spec:
+  deviceRef:
+    deviceName: my-shared-plc
+    endpointName: my-opcua-endpoint
+  datasets:
+    - name: temperature-data
+      dataPoints:
+        - name: temperature
+          dataSource: "ns=2;i=1001"
+---
+apiVersion: namespaces.deviceregistry.microsoft.com/v1
+kind: Asset
+metadata:
+  name: asset-pressure
+  namespace: azure-iot-operations
+spec:
+  deviceRef:
+    deviceName: my-shared-plc
+    endpointName: my-opcua-endpoint
+  datasets:
+    - name: pressure-data
+      dataPoints:
+        - name: pressure
+          dataSource: "ns=2;i=1002"
+```
+
+Both `asset-temperature` and `asset-pressure` reuse the single OPC UA session that the connector established for `my-opcua-endpoint`.
+
 ## Related content
 
 - [Manage asset and device configurations](howto-use-operations-experience.md)

articles/iot-operations/discover-manage-assets/howto-control-opc-ua.md

@@ -376,7 +376,7 @@ The response to a successfully executed request is a message that contains all t
 
 Endpoint operations are process control calls that work on an inbound endpoint only. They don't need an asset.
 
-For example, to dump the address space of an OPC UA server, send a message to the topic `azure-iot-operations/endpoint-operations/{InboundEndpointName}/browse`.
+For example, to dump the address space of an OPC UA server, send a message to the topic `azure-iot-operations/endpoint-operations/{DeviceName}/{EndpointName}/{ActionName}`.
 
 If the payload contains an empty JSON object, the entire address space is returned.
 

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

@@ -55,6 +55,7 @@ The connector for OPC UA supports the following features as part of Azure IoT Op
 | Payload compression | Yes | Supports `gzip` and `brotli` |
 | [Dynamic node resolution](#resolve-nodes-dynamically-by-using-browse-paths) | Yes | Using `TranslateBrowsePathToNodeId` service |
 | State store synchronization | Yes | Sync OPC UA node properties to distributed state store |
+| [Shared endpoint mode](#shared-endpoint-mode) | Yes | Multiple assets share a single OPC UA session |
 | [Key frame generation](#understand-key-frames-for-opc-ua-data-points) | Yes | Enables downstream services to recover state more quickly |
 
 ## How it works
@@ -97,6 +98,67 @@ To configure this behavior, select **Sync properties into state store** when you
 
 You can also force a synchronization of all properties by making an MQTT RPC call to the `azure-iot-operation/asset-operations/{AssetName}/builtin/syncProperties` topic. A payload `{}` forces a synchronization without observing `ModelChange` events. A payload `{"observeModelChanges": true}` forces a synchronization that observes `ModelChange` events.
 
+## Shared endpoint mode
+
+By default, each asset that connects to an OPC UA server opens its own independent OPC UA session. This default behavior is called *dedicated* mode.
+
+When you set the `shared` flag to `true` on a device's inbound endpoint, the connector establishes a single OPC UA session for the endpoint and reuses it across all assets that reference that endpoint. This behavior is called *shared* mode.
+
+```
+Dedicated mode (default)           Shared mode
+─────────────────────────          ─────────────────────────
+Asset A  →  Session A              Asset A ─┐
+Asset B  →  Session B              Asset B ──┼─→  Session (shared)
+Asset C  →  Session C              Asset C ─┘
+(3 sessions to the server)         (1 session to the server)
+```
+
+### When to use shared mode
+
+Use shared mode when:
+
+- The OPC UA server enforces a low session limit, for example a PLC that allows only a few simultaneous connections.
+- You have many assets pointing to the same server and want to minimize the connection footprint.
+- You want to reduce resource consumption (memory, TCP connections, licensing) on the OPC UA server.
+
+The `shared` flag is independent of the authentication method. The single shared session uses whichever authentication method you configure on the endpoint. Telemetry payload, topic structure, and message schema are identical regardless of session mode.
+
+You can mix shared and dedicated assets on the same device. Create separate endpoints, for example `my-opcua-endpoint-shared` and `my-opcua-endpoint-dedicated`, each with its own `shared` flag. Assets reference a specific endpoint by name through `deviceRef.endpointName`.
+
+### Constraints and trade-offs
+
+| Aspect | Dedicated mode | Shared mode |
+|---|---|---|
+| Sessions to server | One per asset | One per endpoint |
+| Server session limit impact | High | Low |
+| Isolation between assets | Full (each asset has its own session) | None (all assets share the same session) |
+| Session disconnect impact | Only the affected asset reconnects | All assets on the endpoint are affected |
+| Certificate update | Each asset reconnects independently | The single shared session is recreated; all assets on the endpoint are briefly interrupted |
+
+> [!IMPORTANT]
+> When the shared OPC UA session disconnects because of a network failure, server restart, or certificate rotation, all assets that reference the endpoint temporarily lose telemetry until the session is reestablished.
+
+### Shared endpoint lifecycle
+
+1. When you create or update a device resource, the connector reads the `shared` flag.
+1. If `shared` is `true`, the connector opens one OPC UA session before any asset connects. The endpoint transitions to the `Shared` state.
+1. When an asset connects, its `ConnectedAsset` record links to the existing session—no second session opens.
+1. When you remove an asset, the OPC UA session stays open for other assets. Only the removed asset's subscriptions are torn down.
+1. When you delete or update the device, the shared session disconnects and all linked assets are requeued.
+
+If you change `shared` from `true` to `false` on a running device, the connector disconnects the shared session and requeues all affected assets. Each asset then establishes its own dedicated session. Expect a brief interruption in telemetry.
+
+### Health states for shared endpoints
+
+- The **InboundEndpoint** health state reports `Available` or `Unavailable` for the single shared session.
+- Each **Asset** health state also reports `Available` or `Unavailable`. Because all assets share the same session, a session drop marks all linked assets as `Unavailable` simultaneously.
+
+### Certificate rotation for shared endpoints
+
+When the connector's application certificate is renewed, it recreates the secure channel of the shared session once. All assets on the endpoint are briefly interrupted, then automatically recover without requiring individual reconnects.
+
+To learn how to configure a shared endpoint, see [Configure a shared endpoint](howto-configure-opc-ua.md#configure-a-shared-endpoint).
+
 ## Connector for OPC UA message format
 
 The connector for OPC UA publishes messages from OPC UA servers to the MQTT broker as JSON. Each message has a payload and a collection of properties that are part of the MQTT user properties section. The payload contains the messages from the OPC UA server, and the properties provide metadata.