Skip to content

Commit c415125

Browse files
dominicbettsdominicbetts
committed
Add Akri docs
1 parent 15dc4c2 commit c415125

File tree

5 files changed

+354
-35
lines changed

5 files changed

+354
-35
lines changed

‎articles/iot-operations/.openpublishing.redirection.iot-operations.json

Lines changed: 0 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -135,41 +135,6 @@
135135
"redirect_url": "https://github.com/Azure-Samples/iot-edge-opc-plc/blob/main/README.md",
136136
"redirect_document_id": false
137137
},
138-
{
139-
"source_path_from_root": "/articles/iot-operations/manage-devices-assets/howto-autodetect-opcua-assets-using-akri.md",
140-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
141-
"redirect_document_id": false
142-
},
143-
{
144-
"source_path_from_root": "/articles/iot-operations/manage-devices-assets/concept-akri-architecture.md",
145-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
146-
"redirect_document_id": false
147-
},
148-
{
149-
"source_path_from_root": "/articles/iot-operations/manage-devices-assets/overview-akri.md",
150-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
151-
"redirect_document_id": false
152-
},
153-
{
154-
"source_path_from_root": "/articles/iot-operations/discover-manage-assets/concept-akri-architecture.md",
155-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
156-
"redirect_document_id": false
157-
},
158-
{
159-
"source_path_from_root": "/articles/iot-operations/discover-manage-assets/howto-autodetect-opcua-assets-using-akri.md",
160-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
161-
"redirect_document_id": false
162-
},
163-
{
164-
"source_path_from_root": "/articles/iot-operations/discover-manage-assets/overview-akri.md",
165-
"redirect_url": "/azure/iot-operations/discover-manage-assets/overview-manage-assets",
166-
"redirect_document_id": false
167-
},
168-
{
169-
"source_path_from_root": "/articles/iot-operations/reference/observability-metrics-akri.md",
170-
"redirect_url": "/azure/iot-operations/reference/observability-metrics-opcua-broker",
171-
"redirect_document_id": false
172-
},
173138
{
174139
"source_path_from_root": "/articles/iot-operations/configure-observability-monitoring/howto-add-cluster.md",
175140
"redirect_url": "/azure/iot-operations/configure-observability-monitoring/howto-configure-observability",

‎articles/iot-operations/discover-manage-assets/concept-akri-architecture.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Akri services architecture
3+
description: Understand the key components in the Akri services architecture and how they relate to each other. Includes some information about the CNCF version of Akri
4+
author: dominicbetts
5+
ms.author: dobett
6+
ms.subservice: azure-akri
7+
ms.topic: conceptual
8+
ms.custom:
9+
- ignite-2023
10+
ms.date: 05/13/2024
11+
12+
# CustomerIntent: As an industrial edge IT or operations user, I want to understand the key components in the Akri services architecture so that I understand how it works to enable device and asset discovery for my edge solution.
13+
---
14+
15+
# Akri services architecture
16+
17+
This article helps you understand the architecture of the Akri services. After you learn about the core components of the Akri services, you can use them to detect devices and assets, and add them to your Kubernetes cluster.
18+
19+
The Akri services are a Microsoft-managed commercial version of [Akri](https://docs.akri.sh/), an open-source Cloud Native Computing Foundation (CNCF) project.
20+
21+
## Core components
22+
23+
The Akri services consist of the following five components:
24+
25+
- **Akri configuration** is a custom resource where you name a device. This configuration tells the Akri services what kind of devices to look for.
26+
- **Akri instance** is a custom resource that tracks the availability and usage of a device. Each Akri instance represents a leaf device.
27+
- **Akri discovery handlers** look for the configured device and inform the agent about discovered devices.
28+
- **Akri agent** creates the Akri instance custom resource.
29+
- **Akri controller** helps you to use a configured device. The controller sees each Akri instance and deploys a broker pod that knows how to connect to and use the resource.
30+
31+
:::image type="content" source="media/concept-akri-architecture/akri-architecture.png" alt-text="Diagram for the Akri services architecture." border="false":::
32+
33+
## Custom resource definitions
34+
35+
A custom resource definition (CRD) is a Kubernetes API extension that lets you define new object types. There are two Akri services CRDs:
36+
37+
- Configuration
38+
- Instance
39+
40+
### Akri configuration CRD
41+
42+
The configuration CRD configures the Akri services. You create configurations that describe the resources to discover and the pod to deploy on a node that discovers a resource. To learn more, see [Akri configuration CRD](https://github.com/project-akri/akri/blob/main/deployment/helm/crds/akri-configuration-crd.yaml). The CRD schema specifies the settings all configurations must have, including the following settings:
43+
44+
- The discovery protocol for finding resources. For example, ONVIF or udev.
45+
- `spec.capacity` that defines the maximum number of nodes that can schedule workloads on this resource.
46+
- `spec.brokerPodSpec` that defines the broker pod to schedule for each of these reported resources.
47+
- `spec.instanceServiceSpec` that defines the service that provides a single stable endpoint to access each individual resource's set of broker pods.
48+
- `spec.configurationServiceSpec` that defines the service that provides a single stable endpoint to access the set of all brokers for all resources associated with the configuration.
49+
50+
### Akri instance CRD
51+
52+
Each Akri instance represents an individual resource that's visible to the cluster. For example, if there are five IP cameras visible to the cluster, there are five instances. The instance CRD enables Akri services coordination and resource sharing. These instances store internal state and aren't intended for you to edit. To learn more, see [Resource sharing in-depth](https://docs.akri.sh/architecture/resource-sharing-in-depth).
53+
54+
## Agent
55+
56+
The Akri agent implements [Kubernetes Device-Plugins](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/) for discovered resources. The Akri Agent performs the following tasks:
57+
58+
- It watches for configuration changes to determine the resources to search for.
59+
- It monitors resource availability to determine what resources to advertise. In an edge environment, resource availability changes often.
60+
- It informs Kubernetes of any changes to resource health and availability.
61+
62+
These tasks, combined with the state stored in the instance, enable multiple nodes to share a resource while respecting the limits defined by the `spec.capacity` setting.
63+
64+
To learn more, see [Agent in-depth](https://docs.akri.sh/architecture/agent-in-depth).
65+
66+
## Discovery handlers
67+
68+
A discovery handler finds devices. Examples of device include:
69+
70+
- USB sensors connected to nodes.
71+
- GPUs embedded in nodes.
72+
- IP cameras on the network.
73+
74+
The discovery handler reports all discovered devices to the agent. There are often protocol implementations for discovering a set of devices, whether a network protocol like OPC UA or a proprietary protocol. Discovery handlers implement the `DiscoveryHandler` service defined in [`discovery.proto`](https://github.com/project-akri/akri/blob/main/discovery-utils/proto/discovery.proto). A discovery handler is required to register with the agent, which hosts the `Registration` service defined in [`discovery.proto`](https://github.com/project-akri/akri/blob/main/discovery-utils/proto/discovery.proto).
75+
76+
To learn more, see [Custom Discovery Handlers](https://docs.akri.sh/development/handler-development).
77+
78+
## Controller
79+
80+
The goals of the Akri controller are to:
81+
82+
- Create or delete the pods and services that enable resource availability.
83+
- Ensure that instances are aligned to the cluster state at any given moment.
84+
85+
To achieve these goals, the controller:
86+
87+
- Watches out for instance changes to determine what pods and services should exist.
88+
- Watches for nodes that are contained in instances that no longer exist.
89+
90+
These tasks enable the Akri controller to ensure that protocol brokers and Kubernetes services are running on all nodes and exposing the desired resources, while respecting the limits defined by the `spec.capacity` setting.
91+
92+
For more information, see the documentation for [Controller In-depth](https://docs.akri.sh/architecture/controller-in-depth).

‎articles/iot-operations/discover-manage-assets/howto-autodetect-opcua-assets-using-akri.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Discover OPC UA data sources using the Akri services
3+
description: How to discover and configure OPC UA data sources at the edge automatically by using the Akri services
4+
author: dominicbetts
5+
ms.author: dobett
6+
ms.subservice: azure-akri
7+
ms.topic: how-to
8+
ms.date: 05/15/2024
9+
10+
# CustomerIntent: As an industrial edge IT or operations user, I want to discover and create OPC UA data sources in my industrial edge environment so that I can reduce manual configuration overhead.
11+
---
12+
13+
# Discover OPC UA data sources using the Akri services
14+
15+
In this article, you learn how to discover OPC UA data sources automatically. After you deploy Azure IoT Operations Preview, you configure the Akri services to discover OPC UA data sources at the edge. The Akri services create custom resources in your Kubernetes cluster that represent the data sources it discovers. The ability to discover OPC UA data sources removes the need to [manually configure them by using the operations experience web UI](howto-manage-assets-remotely.md).
16+
17+
> [!IMPORTANT]
18+
> Currently, you can't use Azure Device Registry to manage the assets that the Akri services discover and create.
19+
20+
The Akri services enable you to detect and create assets in the address space of an OPC UA server. The OPC UA asset detection generates `AssetType` and `Asset` custom resources for [OPC UA Device Integration (DI) specification](https://reference.opcfoundation.org/DI/v104/docs/) compliant assets.
21+
22+
## Prerequisites
23+
24+
- Install Azure IoT Operations Preview. To install Azure IoT Operations for demonstration and exploration purposes, see [Quickstart: Run Azure IoT Operations Preview in Github Codespaces with K3s](../get-started-end-to-end-sample/quickstart-deploy.md).
25+
- Verify that the Akri services pods are properly configured by running the following command:
26+
27+
```bash
28+
kubectl get pods -n azure-iot-operations
29+
```
30+
31+
The output includes a line that shows the Akri agent and discovery pods are running:
32+
33+
```output
34+
NAME READY STATUS RESTARTS AGE
35+
aio-akri-agent-daemonset-hwpc7 1/1 Running 0 17mk0s
36+
aio-opc-asset-discovery-wzlnj 1/1 Running 0 8m28s
37+
```
38+
39+
## Configure the OPC UA discovery handler
40+
41+
To configure the OPC UA discovery handler for asset detection, create a YAML configuration file that contains the values described in this section:
42+
43+
| Name | Mandatory | Datatype | Default | Comment |
44+
| ---- | --------- | -------- | ------- | ------- |
45+
| `EndpointUrl` | true | String | null | The OPC UA endpoint URL to use for asset discovery |
46+
| `AutoAcceptUntrustedCertificates` | true ¹ | Boolean | false | Should the client autoaccept untrusted certificates? A certificate can only be autoaccepted as trusted if no nonsuppressible errors occurred during chain validation. For example, a certificate with incomplete chain isn't accepted. |
47+
| `UseSecurity` | true ¹ | Boolean | true | Should the client use a secure connection? |
48+
| `UserName` | false | String | null | The username for user authentication. ² |
49+
| `Password` | false | String | null | The password for user authentication. ² |
50+
51+
¹ The current version of the discovery handler only supports `UseSecurity=false` and requires `autoAcceptUntrustedCertificates=true`.
52+
² A temporary implementation until the Akri services can pass Kubernetes secrets.
53+
54+
The following example demonstrates discovery of an OPC PLC server. You can add the asset parameters for multiple OPC PLC servers.
55+
56+
1. To create the YAML configuration file, copy and paste the following content into a new file, and save it as `opcua-configuration.yaml`:
57+
58+
If you're using the simulated PLC server that was deployed with the Azure IoT Operations Quickstart, you don't need to change the `endpointUrl`. If you have your own OPC UA servers running or are using the simulated PLC servers deployed on Azure, add in your endpoint URL accordingly. Discovery endpoint URLs look like `opc.tcp://<FQDN>:50000/`. To find the FQDNs of your OPC PLC servers, go to your deployment in the Azure portal. For each server, copy and paste the **FQDN** value into your endpoint URLs.
59+
60+
```yaml
61+
apiVersion: akri.sh/v0
62+
kind: Configuration
63+
metadata:
64+
name: aio-akri-opcua-asset
65+
spec:
66+
discoveryHandler:
67+
name: opcua-asset
68+
discoveryDetails: "opcuaDiscoveryMethod:\n - asset:\n endpointUrl: \" opc.tcp://opcplc-000000:50000\"\n useSecurity: false\n autoAcceptUntrustedCertificates: true\n"
69+
brokerProperties: {}
70+
capacity: 1
71+
```
72+
73+
1. To apply the configuration, run the following command:
74+
75+
```bash
76+
kubectl apply -f opcua-configuration.yaml -n azure-iot-operations
77+
```
78+
79+
> [!TIP]
80+
> In a default Azure IoT Operations deployment, the OPC UA discovery handler is already configured to discover the simulated PLC server. If you want to discover assets connected to additional OPC UA servers, you can add them to the configuration file.
81+
82+
## Verify the configuration
83+
84+
To confirm that the asset discovery container is configured and running:
85+
86+
1. Use the following command to check the pod logs:
87+
88+
```bash
89+
kubectl logs <insert aio-opc-asset-discovery pod name> -n azure-iot-operations
90+
```
91+
92+
A log from the `aio-opc-asset-discovery` pod indicates after a few seconds that the discovery handler registered itself with the Akri services:
93+
94+
```2024-08-01T15:04:12.874Z aio-opc-asset-discovery-4nsgs - Akri OPC UA Asset Discovery (1.0.0-preview-20240708+702c5cafeca2ea49fec3fb4dc6645dd0d89016ee) is starting with the process id: 1
95+
2024-08-01T15:04:12.948Z aio-opc-asset-discovery-4nsgs - OPC UA SDK 1.5.374.70 from 07/20/2024 07:37:16
96+
2024-08-01T15:04:12.973Z aio-opc-asset-discovery-4nsgs - OPC UA SDK informational version: 1.5.374.70+1ee3beb87993019de4968597d17cb54d5a4dc3c8
97+
2024-08-01T15:04:12.976Z aio-opc-asset-discovery-4nsgs - Akri agent registration enabled: True
98+
2024-08-01T15:04:13.475Z aio-opc-asset-discovery-4nsgs - Hosting starting
99+
2024-08-01T15:04:13.547Z aio-opc-asset-discovery-4nsgs - Overriding HTTP_PORTS '8080' and HTTPS_PORTS ''. Binding to values defined by URLS instead 'http://+:8080'.
100+
2024-08-01T15:04:13.774Z aio-opc-asset-discovery-4nsgs - Now listening on: http://:8080
101+
2024-08-01T15:04:13.774Z aio-opc-asset-discovery-4nsgs - Application started. Press Ctrl+C to shut down.
102+
2024-08-01T15:04:13.774Z aio-opc-asset-discovery-4nsgs - Hosting environment: Production
103+
2024-08-01T15:04:13.774Z aio-opc-asset-discovery-4nsgs - Content root path: /app
104+
2024-08-01T15:04:13.774Z aio-opc-asset-discovery-4nsgs - Hosting started
105+
2024-08-01T15:04:13.881Z aio-opc-asset-discovery-4nsgs - Registering with Agent as HTTP endpoint using own IP from the environment variable POD_IP: 10.42.0.245
106+
2024-08-01T15:04:14.875Z aio-opc-asset-discovery-4nsgs - Registered with the Akri agent with name opcua-asset for http://10.42.0.245:8080 with type Network and shared True
107+
2024-08-01T15:04:14.877Z aio-opc-asset-discovery-4nsgs - Successfully re-registered OPC UA Asset Discovery Handler with the Akri agent
108+
2024-08-01T15:04:14.877Z aio-opc-asset-discovery-4nsgs - Press CTRL+C to exit
109+
```
110+
111+
After about a minute, the Akri services issue the first discovery request based on the configuration:
112+
113+
```output
114+
2024-08-01T15:04:15.280Z aio-opc-asset-discovery-4nsgs [opcuabroker@311 SpanId:6d3db9751eebfadc, TraceId:e5594cbaf3993749e92b45c88c493377, ParentId:0000000000000000 ConnectionId:0HN5I7CQJPJL0 RequestPath:/v0.DiscoveryHandler/Discover RequestId:0HN5I7CQJPJL0:00000001] - Reading message.
115+
2024-08-01T15:04:15.477Z aio-opc-asset-discovery-4nsgs [opcuabroker@311 SpanId:6d3db9751eebfadc, TraceId:e5594cbaf3993749e92b45c88c493377, ParentId:0000000000000000 ConnectionId:0HN5I7CQJPJL0 RequestPath:/v0.DiscoveryHandler/Discover RequestId:0HN5I7CQJPJL0:00000001] - Received discovery request from ipv6:[::ffff:10.42.0.241]:48638
116+
2024-08-01T15:04:15.875Z aio-opc-asset-discovery-4nsgs [opcuabroker@311 SpanId:6d3db9751eebfadc, TraceId:e5594cbaf3993749e92b45c88c493377, ParentId:0000000000000000 ConnectionId:0HN5I7CQJPJL0 RequestPath:/v0.DiscoveryHandler/Discover RequestId:0HN5I7CQJPJL0:00000001] - Start asset discovery
117+
2024-08-01T15:04:15.882Z aio-opc-asset-discovery-4nsgs [opcuabroker@311 SpanId:6d3db9751eebfadc, TraceId:e5594cbaf3993749e92b45c88c493377, ParentId:0000000000000000 ConnectionId:0HN5I7CQJPJL0 RequestPath:/v0.DiscoveryHandler/Discover RequestId:0HN5I7CQJPJL0:00000001] - Discovering OPC UA opc.tcp://opcplc-000000:50000 using Asset Discovery
118+
2024-08-01T15:04:15.882Z aio-opc-asset-discovery-4nsgs [opcuabroker@311 SpanId:6d3db9751eebfadc, TraceId:e5594cbaf3993749e92b45c88c493377, ParentId:0000000000000000 ConnectionId:0HN5I7CQJPJL0 RequestPath:/v0.DiscoveryHandler/Discover RequestId:0HN5I7CQJPJL0:00000001] - Selected AutoAcceptUntrustedCertificates mode: False
119+
```
120+
121+
After the discovery is complete, the discovery handler sends the result back to the Akri services to create an Akri instance custom resource with asset information and observable variables. The discovery handler repeats the discovery every 10 minutes to detect any changes on the server.
122+
123+
1. To view the discovered Akri instances, run the following command:
124+
125+
```bash
126+
kubectl get akrii -n azure-iot-operations
127+
```
128+
129+
The output from the previous command looks like the following example. You might need to wait for a few seconds for the Akri instance to be created:
130+
131+
```output
132+
NAME CONFIG SHARED NODES AGE
133+
akri-opcua-asset-dbdef0 akri-opcua-asset true ["k3d-k3s-default-server-0"] 24h
134+
```
135+
136+
The connector for OPC UA supervisor watches for new Akri instance custom resources of type `opc-ua-asset`, and generates the initial asset types and asset custom resources for them. You can modify asset custom resources by adding settings such as extended publishing for more data points, or connector for OPC UA observability settings.
137+
138+
1. To confirm that the Akri instance properly connected to the connector for OPC UA, run the following command. Replace the placeholder with the name of the Akri instance that was included in the output of the previous command:
139+
140+
```bash
141+
kubectl get akrii <AKRI_INSTANCE_NAME> -n azure-iot-operations -o json
142+
```
143+
144+
The command output includes a section that looks like the following example. The snippet shows the Akri instance `brokerProperties` values and confirms that the connector for OPC UA is connected.
145+
146+
```json
147+
"spec": {
148+
149+
"brokerProperties": {
150+
"ApplicationUri": "Boiler #2",
151+
"AssetEndpointProfile": "{\"spec\":{\"uuid\":\"opc-ua-broker-opcplc-000000-azure-iot-operation\"……
152+
```

‎articles/iot-operations/discover-manage-assets/media/concept-akri-architecture/akri-architecture.png

37.9 KB
Loading

0 commit comments

Comments
 (0)