AWS iot-sitewise documentation change
Summary
Added comprehensive documentation for configuring OPC UA sources in AWS IoT SiteWise Edge, including console/CLI instructions, security configurations, authentication methods, data filtering, and storage options
Security assessment
The changes add documentation about security features including message security modes (SIGN/SIGN_AND_ENCRYPT), certificate trust policies, Secrets Manager integration for authentication, and warnings about deprecated security policies. However, there's no evidence this addresses a specific existing vulnerability.
Diff
diff --git a/iot-sitewise/latest/userguide/configure-opcua-source.md index 8b1378917..0c22da1e2 100644 --- a/iot-sitewise/latest/userguide/configure-opcua-source.md +++ b/iot-sitewise/latest/userguide/configure-opcua-source.md @@ -0,0 +1 @@ +[](/pdfs/iot-sitewise/latest/userguide/iot-sitewise-guide.pdf#configure-opcua-source "Open PDF") @@ -1,0 +3,902 @@ +[Documentation](/index.html)[AWS IoT SiteWise](/iot-sitewise/index.html)[User Guide](what-is-sitewise.html) + +Configure an OPC UA source (console)Configure an OPC UA source (CLI) + +# Set up an OPC UA source in SiteWise Edge + +You can use the AWS IoT SiteWise console or a SiteWise Edge gateway capability to define and add an OPC UA source to your SiteWise Edge gateway to represent a local OPC UA server. + +###### Topics + + * Configure an OPC UA source (console) + + * Configure an OPC UA source (AWS CLI) + + + + +## Configure an OPC UA source (console) + +You can use the console to configure the OPC UA source with the following procedure. + +###### Note + +Warning: Duplicate TQVs may result in double charging. + +###### To configure an OPC UA source using the AWS IoT SiteWise console + + 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). + + 2. In the left navigation, choose **Edge gateways** in the **Edge** section. + + 3. Select the SiteWise Edge gateway to add an OPC UA source. + + 4. Choose **Add data source**. + + 5. Enter a name for the source. + + 6. Enter the **Local endpoint** of the data source server. The endpoint can be the IP address or hostname. You may also add a port number to the local endpoint. For example, your local endpoint might look like this: `opc.tcp://203.0.113.0:49320` + + 7. (Optional) For **Node ID for selection** , add node filters to limit which data streams are ingested to the AWS Cloud. By default, SiteWise Edge gateways use the root node of a server to ingest all data streams. You can use node filters to reduce your SiteWise Edge gateway's startup time and CPU usage by only including paths to data that you model in AWS IoT SiteWise. By default, SiteWise Edge gateways upload all OPC UA paths except those that start with `/Server/`. To define OPC UA node filters, you can use node paths and the `*` and `**` wildcard characters. For more information, see [Use OPC UA node filters in SiteWise Edge](./opc-ua-node-filters.html). + + 8. **Destinations** vary between MQTT-enabled, V3 gateways and Classic streams, V2 gateways. + + * **Classic steams, V2 gateway destinations** have a 1:1 relationship with the source. Each source sends data to a particular destination. + + * **MQTT-enabled, V3 gateway destinations** are set up separately because the hub and spoke model lets you centralize configuration and management of multiple data sources across different gateways. To set up destinations in a V3 gateway, see [Understand AWS IoT SiteWise Edge destinations](./source-destination.html). + +Classic steams, V2 gateway destinations + + + * **AWS IoT SiteWise real-time** – Choose this to send data directly to AWS IoT SiteWise storage. Ingest and monitor data in real-time at the edge. + + * **AWS IoT SiteWise Buffered using Amazon S3** – Send data in Parquet format to Amazon S3 and then import into AWS IoT SiteWise storage. Choose this option to ingest data in batches, and store historical data in a cost-effective way. You can configure your preferred Amazon S3 bucket location, and the frequency at which you want data to be uploaded to Amazon S3. You can also choose what to do with the data after ingestion into AWS IoT SiteWise. You can choose to have the data available in both AWS IoT SiteWise and Amazon S3 or you can choose to delete it automatically from Amazon S3 after it has been imported into AWS IoT SiteWise. + + * The Amazon S3 bucket is a staging and buffering mechanism and supports files in the Parquet format. + + * If you select the check box **Import data into AWS IoT SiteWise storage** , data is uploaded into Amazon S3 first, and then into AWS IoT SiteWise storage. + + * If you select the check box **Delete data from Amazon S3** , data is deleted from Amazon S3, after it is imported into SiteWise storage. + + * If you clear the check box **Delete data from Amazon S3** , data is stored both in Amazon S3, and in SiteWise storage. + + * If you clear the check box **Import data into AWS IoT SiteWise storage** , data is stored only in Amazon S3. It is not imported into SiteWise storage. + +Visit [Manage data storage](./manage-data-storage.html) for details on the various storage options AWS IoT SiteWise provides. To learn more about pricing options, see [AWS IoT SiteWise pricing](https://aws.amazon.com/iot-sitewise/pricing/). + + * **AWS IoT Greengrass stream manager** – Use AWS IoT Greengrass stream manager to send data to the following AWS Cloud destinations: channels in AWS IoT Analytics, streams in Amazon Kinesis Data Streams, asset properties in AWS IoT SiteWise, or objects in Amazon Simple Storage Service (Amazon S3). For more information, see [Manage data streams on the AWS IoT Greengrass Core](https://docs.aws.amazon.com/greengrass/v2/developerguide/manage-data-streams.html) in _AWS IoT Greengrass Version 2 Developer Guide_. + +Enter a name for the AWS IoT Greengrass stream. + +MQTT-enabled, V3 gateway destinations + + + 1. See [MQTT-enabled, V3 Gateways for AWS IoT SiteWise Edge](./mqtt-enabled-v3-gateway.html) for information on adding your relevant destinations. + + 2. Return to this procedure after adding your source destinations. + + 9. In the **Advanced configuration** pane, you can do the following: + + 1. Choose a **Message security mode** for connections and data in transit between your source server and your SiteWise Edge gateway. This field is the combination of the OPC UA security policy and message security mode. Choose the same security policy and message security mode that you specified for your OPC UA server. + + 2. If your source requires authentication, choose an AWS Secrets Manager secret from the **Authentication configuration** list. The SiteWise Edge gateway uses the authentication credentials in this secret when it connects to this data source. You must attach secrets to your SiteWise Edge gateway's AWS IoT Greengrass component to use them for data source authentication. For more information, see [Configure data source authentication for SiteWise Edge](./configure-source-authentication-ggv2.html). + +###### Tip + +Your data server might have an option named **Allow anonymous login**. If this option is **Yes** , then your source doesn't require authentication. + + 3. (Optional) You can activate a data stream prefix by selecting **Activate data stream prefix -_optional_**. + + 1. Enter a **Data stream prefix**. The SiteWise Edge gateway adds this prefix to all data streams from this source. Use a data stream prefix to distinguish between data streams that have the same name from different sources. Each data stream should have a unique name within your account. + + 4. (Optional) Choose a **Data type conversion** option to convert unsupported OPC UA data types into strings before ingesting them into AWS IoT SiteWise. Convert array values with simple data types to JSON strings and DateTime data types to ISO 8601 strings. For more information, see [Converting unsupported data types](./string-conversion.html). + + 5. (Optional) For **Property groups** , choose **Add new group**. + + 1. Enter a **Name** for the property group. + + 2. For **Properties** : + + 1. For **Node paths** , add OPC UA node filters to limit which OPC UA paths are uploaded to AWS IoT SiteWise. The format is similar to **Node ID for selection**. + + 3. For **Group settings** , do the following: + + 1. For **Data quality setting** , choose the type of data quality that you want AWS IoT SiteWise Collector to ingest. + + 2. For **Scan mode setting** , configure the standard subscription properties using **Scan mode**. You can select **Subscribe** or **Poll**. For more information about scan mode, see [Filter data ingestion ranges with OPC UA](./opcua-data-acquisition.html). + +Subscribe + + +###### To send every data point + + 1. Choose **Subscribe** and set the following: + + 1. **[Data change trigger](https://reference.opcfoundation.org/v104/Core/docs/Part4/7.17.2/)** – The condition that initiates a data change alert. + + 2. **[Subscription queue size](https://reference.opcfoundation.org/v104/Core/docs/Part4/7.16/)** – The depth of the queue on an OPC–UA server for a particular metric where notifications for monitored items are queued. + + 3. **[Subscription publishing interval](https://reference.opcfoundation.org/v104/Core/docs/Part4/5.13.2/)** – The interval (in milliseconds) of publishing cycle specified when subscription is created. + + 4. **Snapshot interval -_Optional_** – The snapshot frequency timeout setting to ensure that AWS IoT SiteWise Edge ingests a steady stream of data. + + 5. **Scan rate** – The rate that you want the SiteWise Edge gateway to read your registers. AWS IoT SiteWise automatically calculates the minimum allowable scan rate for your SiteWise Edge gateway. + + 6. **Timestamp** – The timestamp to include with your OPC UA data points. You can use the server timestamp or your device's timestamp. + +###### Note + +Use version 2.5.0 or later of the IoT SiteWise OPC UA collector component. If you use the timestamp feature with earlier versions, configuration updates fail. For more information, see [Update the version of an AWS IoT SiteWise component](./manage-gateways-ggv2.html#update-component-version). + + 2. In **Deadband settings** , configure a **Deadband type**. The deadband type controls what data your source sends to your AWS IoT SiteWise, and what data it discards. For more information about the deadband setting, see [Filter data ingestion ranges with OPC UA](./opcua-data-acquisition.html). + + * **None** – The associated server sends all data points for this property group. + + * **Percentage** – The associated server only sends data that falls outside a specified percentage of the data's range. This range is computed by the server based on the engineering unit minimum and maximum defined for each node. If the server does not support percentage deadbands or lacks defined engineering units, the gateway calculates the range using the minimum and maximum values provided below. + + * **Absolute** – The associated server only sends data that falls outside of a specific range. + + 1. Set the **Deadband value** as the percentage of the data range to deadband. + + 2. (Optional) Specify a minimum and maximum for the deadband range using **Minimum range -_optional_** and **Maximum range -_optional_**. + +Poll + + +###### To send data points at a specific interval + + * Choose **Poll** and set the following: + + 1. **Scan rate** – The rate that you want the SiteWise Edge gateway to read your registers. AWS IoT SiteWise automatically calculates the minimum allowable scan rate for your SiteWise Edge gateway. + + 2. **Timestamp** – The timestamp to include with your OPC UA data points. You can use the server timestamp or your device's timestamp. + +###### Note + +Use version 2.5.0 or later of the IoT SiteWise OPC UA collector component. If you use the timestamp feature with earlier versions, configuration updates fail. For more information, see [Update the version of an AWS IoT SiteWise component](./manage-gateways-ggv2.html#update-component-version). + +###### Note + +**Deadband settings** are applicable when you've selected **Subscribe** in the **Scan mode settings**. + + 10. Choose **Save**. + + + + +## Configure an OPC UA source (AWS CLI) + +You can define OPC UA data sources for an SiteWise Edge gateway using the AWS CLI. To do this, create an OPC UA capability configuration JSON file and use the [ update-gateway-capability-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotsitewise/update-gateway-capability-configuration.html#) command to update the SiteWise Edge gateway configuration. You must define all of your OPC UA sources in a single capability configuration. + +MQTT-enabled, V3 gateway + + +This capability has the following namespace. + + * `iotsitewise:opcuacollector:3` + + + + + + { + "sources": [ + { + "name": "string", + "endpoint": { + "certificateTrust": { + "type": "TrustAny" | "X509", + "certificateBody": "string", + "certificateChain": "string", + }, + "endpointUri": "string", + "securityPolicy": "NONE" | "BASIC128_RSA15" | "BASIC256" | "BASIC256_SHA256" | "AES128_SHA256_RSAOAEP" | "AES256_SHA256_RSAPSS",