Azure IoT Operations - Connector

Framework for building Azure IoT Operations connectors that handle device discovery, asset definitions, and data transformation.

Examples | Release Notes

Overview

The Azure IoT Operations Connector framework provides:

• Base Connector: Handles device endpoint and asset lifecycle management from Azure Device Registry
• ADR Discovery: Provides functionality to discover and manage discovered device and asset definitions
• Data Operations: Supports datasets, events, and streams
• Status Reporting: Reports device, endpoint, and asset status back to Azure Device Registry

Build connectors that seamlessly integrate with Azure IoT Operations to transform and forward data from edge devices.

Instructions to deploy sample Rust connector

The sample Rust connector that retrieves ADR definitions is currently under the examples folder of this crate.

To deploy follow these steps (from the root of the crate):

1. Create a binary release of the connector code: cargo build --release --target-dir target --example connector_get_adr_definitions
2. Build the docker container: docker build -t connectorgetadrdefinitions:latest -f examples/connector_get_adr_definitions_resources/Dockerfile .
3. Import into your kubernetes cluster with: k3d image import connectorgetadrdefinitions:latest
4. Apply the connector template: kubectl apply -f examples/connector_get_adr_definitions_resources/connector_template.yaml
5. Deploy a sample device: kubectl apply -f examples/connector_get_adr_definitions_resources/thermostat-device-definition.yaml
6. Deploy a sample asset to the device: kubectl apply -f examples/connector_get_adr_definitions_resources/rest-thermostat-asset-definition.yaml

The sample Rust connector that uses the base connector to retrieve ADR definitions and send transformed data is currently under the examples folder of this crate.

Pre-requisites:

1. Have AIO Deployed with necessary features
2. Have an Azure Container Registry instance

To deploy follow these steps (from the root of the crate):

1. Create a binary release of the connector code: cargo build --release --target-dir target --example base_connector_sample
2. Build the docker container: docker build -t baseconnector:latest -f examples/base_connector_sample_resources/Dockerfile .
3. Tag your docker image docker tag baseconnector <your ACR name>.azurecr.io/baseconnector
4. Make sure you're logged into azure cli az login
5. Login to your ACR az acr login --name <your ACR name>
6. Upload to your ACR instance docker push <your ACR name>.azurecr.io/baseconnector
7. Apply the connector template: kubectl apply -f examples/base_connector_sample_resources/connector_template.yaml
8. Deploy a sample device: kubectl apply -f examples/base_connector_sample_resources/thermostat-device-definition.yaml
9. Deploy a sample asset to the device: kubectl apply -f examples/base_connector_sample_resources/rest-thermostat-asset-definition.yaml

Error Behaviors

Any error that is returned to the Connector Application will not be logged, it is the responsibility of the Connector Application to log them

Errors that could trigger retries

All errors that are retried are logged when retried.

This is the retry strategy used: const RETRY_STRATEGY: tokio_retry2::strategy::ExponentialFactorBackoff = tokio_retry2::strategy::ExponentialFactorBackoff::from_millis(500, 2.0);

Any AIO Protocol Error is considered a "network error" and retriable. This may not be the case, but we currently don't provide enough information on the AIO Protocol Error to be able to distinguish the difference. Once we have that information, we will update handling to only retry actual network errors. Effort has been made to dive into the scenarios and ensure that any non-network errors are already validated against and not possible.

Errors that couldn't trigger retries

Setup

If Connector Artifacts contain invalid or incorrect values, setup of the BaseConnector will return an error indicating the reason.

Fatal

• Creating a new file mount DeviceEndpointCreateObservation is fatal if there's an error. There's no way to recover from this other than restarting the connector. It causes a panic (TODO: we could propogate to the application?)
• There are other .expect()s/.unwrap()s in our code that technically can trigger a panic, but they should not be possible, so will not be defined here.