From d302c3909fd143a050cec8a09a8cbd51032a4187 Mon Sep 17 00:00:00 2001 From: Leo Lu Date: Mon, 15 Aug 2022 11:46:37 +0800 Subject: [PATCH 1/2] integrate external device inventory proposal draft first version. Akri can get more device related information beyond discovery. Suggest Akri agent talking with an external device inventory POD/service Signed-off-by: Leo Lu --- ...grate-extenal-device-inventory-diagram.svg | 4 ++ ...ntegrate with external device inventory.md | 42 +++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 media/integrate-extenal-device-inventory-diagram.svg create mode 100644 proposals/Integrate with external device inventory.md diff --git a/media/integrate-extenal-device-inventory-diagram.svg b/media/integrate-extenal-device-inventory-diagram.svg new file mode 100644 index 0000000..e219895 --- /dev/null +++ b/media/integrate-extenal-device-inventory-diagram.svg @@ -0,0 +1,4 @@ + + + +
Leaf Device
Leaf Device
Akri Agent
Akri Agent
Akri controller
Akri controller
External Device Inventory
POD
External Device Inve...
Being discovered
because of
matching
 Akri config
Being discovered...
HTTP POST
URI: /queryDevice
BODY: discovered device info, 
such as MAC address
HTTP POST...
User can tell Akri name of a existing external device inventory POD. This POD provides a few REST API for Akri agent to talk with
User can tell Akri name of a existing exter...
HTTP POST Response
Additional device infomation,
such as device credential
HTTP POST Response...
in case of onvif camera device,
 agent may use
 onvif credentail to query video
 stream source URI
in case of onvif camera device,...
in case of onvif camera device,
give back stream source URI
in case of onvif camera device,...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Attach all device related
 information as a JSON string
 to each created Akri instance
Attach all device related...
Detect Akri
 instance change
Detect Akri...
Broker POD
Broker P...
Broker POD
Broker P...
Broker POD
Broker P...
create broker POD and
 transfer all device
 information
create broker POD and...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/proposals/Integrate with external device inventory.md b/proposals/Integrate with external device inventory.md new file mode 100644 index 0000000..430dae7 --- /dev/null +++ b/proposals/Integrate with external device inventory.md @@ -0,0 +1,42 @@ +# Integrate with external device inventory + +## Background +Akri extracts device information (onvif,opcua or udev device) only from discovery procedure. + + +For example, Akri discovers onvif camera and extracts information such as video stream source URI through ONVIF discovery and ONVIF command. Video source URI is then used in broker POD to build connection with the camera. + +But there are other important device information that can not be extracted through discovery procedure itself. It limits Akri being used in real world production environment. + +1. If ONVIF devices are protected by credential, Akri agent won't be able to find out video stream source URI because the ONVIF command need pass authentication. If RTSP stream is also protected with its own credential, broker POD will not be able to receive video stream. Same problem happens when OPC UA servers (such as facotry PLCs) only serve those OPCUA clients having approved X509 cert and related private key. Broker pod is unable to build a OPC UA connection since Akri does not have PLCs's authentication information. + +2. Not only credential, there maybe also important device meta data information that is essential for business logic implementation in broker POD, such as the PLC machine's serial number or asset hierachy information. + +3. Real world projects may ask for a proper device provisioning enrollment procedure. Before a device is enrolled, even it is discovered, broker POD should not be created and started. Akri acts on discovery automatically now without considering device provisioning. + +The above issues can be resolved by allowing Akri getting additional device infomration from an external optional device inventory system. This proposal will introduce a few additional steps in Akri's workflow to allow Akri extracting addtioanl device information from external source. + + +## Proposal + +The below workflow presents a new flow from discovering device till creating broker POD. Additional steps are highlighted as yellow color. + + +- Introduce a new setting that user can specify the name of a customized external device inventory POD or service, so Akri agent can request for additional device information. The proposed external device inventory POD/service must expose a REST POST API /queryDevice for Akri Agent to raise request. +- Instead of directly creating Akri instance after Akri agent discovers new devices, Akri agent will query the external device inventory POD/service to get more device related information, including credential. +- Please note for protected ONVIF device, Akri agent should use the ONVIF credential to finish a successful discovery work, such as querying stream URI. + +This proposed external device inventory POD/service name should be set within each Akri configuration, so it is possible that different discovery config has specified external device inventory system. Another flag is proposed to define if the related external device inventory sytem is also device provisioning database. If it is provisioning database, when Akri agent can not fetch any record of a discovered device, it wont create Akri instance for this device. There wont be broker POD created neither for that device. + +The external device inventory POD is not deployed by Akri but solution developer will take care. One possible implementation of the device inventory POD can be a POD with a mounted Azure Key Vault drive using AKV ARC extenstion. It can fetch device credential and assist Akri agent. The benefit is that device credential can be centrally managed from cloud. + + +## Additional Usage 1: what if a device is undiscoverable but can be added manually +With this new proposed connection between Akri Agent and external device inventory system, Akri can achieve one more new feature. Akri can create broker POD for an undiscoverable device, such case like a camera does not support ONVIF discovery but we know its RTSP stream URI. +To achieve this, Akri Agent may provide a HTTP POST REST API with URI /addDevice. External inventory system may trigger a manual device adding procedure with all necessary device infomation. After receiving "/addDevice" request, Akri agent can still create a Akrii and in the end a broker POD is created to process this manually added device. + + + + +## Additional Usage 2: what if a device's credential is changed +Akri agent may provide another HTTP POST REST API with URI /updateDevice. External inventory system may update Akri agent that device information is changed. Akri agent may recreate or update a Akri instance. Akri controller will detect the customer resource change and schdule new broker POD. \ No newline at end of file From 8d6009516cdc0814508384e23d5ff86a6812eaaa Mon Sep 17 00:00:00 2001 From: Leo Lu Date: Thu, 25 Aug 2022 16:25:12 +0800 Subject: [PATCH 2/2] Add device discovery handler into diagram Make the proposal clearer by drawing device discovery handler in, since I found device discovery handler is not inside Akri agent Signed-off-by: Leo Lu --- media/integrate-extenal-device-inventory-diagram.svg | 2 +- proposals/Integrate with external device inventory.md | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/media/integrate-extenal-device-inventory-diagram.svg b/media/integrate-extenal-device-inventory-diagram.svg index e219895..87b8a88 100644 --- a/media/integrate-extenal-device-inventory-diagram.svg +++ b/media/integrate-extenal-device-inventory-diagram.svg @@ -1,4 +1,4 @@ -
Leaf Device
Leaf Device
Akri Agent
Akri Agent
Akri controller
Akri controller
External Device Inventory
POD
External Device Inve...
Being discovered
because of
matching
 Akri config
Being discovered...
HTTP POST
URI: /queryDevice
BODY: discovered device info, 
such as MAC address
HTTP POST...
User can tell Akri name of a existing external device inventory POD. This POD provides a few REST API for Akri agent to talk with
User can tell Akri name of a existing exter...
HTTP POST Response
Additional device infomation,
such as device credential
HTTP POST Response...
in case of onvif camera device,
 agent may use
 onvif credentail to query video
 stream source URI
in case of onvif camera device,...
in case of onvif camera device,
give back stream source URI
in case of onvif camera device,...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Attach all device related
 information as a JSON string
 to each created Akri instance
Attach all device related...
Detect Akri
 instance change
Detect Akri...
Broker POD
Broker P...
Broker POD
Broker P...
Broker POD
Broker P...
create broker POD and
 transfer all device
 information
create broker POD and...Viewer does not support full SVG 1.1 \ No newline at end of file +
Leaf Device
Leaf Device
Akri Agent
Akri Agent
Akri controller
Akri controller
External Device Inventory
POD
External Device Inve...
Being discovered
because of
matching
 Akri config
Being discovered...
HTTP POST
URI: /queryDevice
BODY: discovered device info, 
such as MAC address
HTTP POST...
User can specify an existing external device inventory POD. This POD provides a few REST API for Akri agent to talk with
User can specify an existing external devic...
HTTP POST Response
Additional device infomation,
such as device credential
HTTP POST Response...
call gRPC
RequestDeviceInfo

Example,
for onvif camera device,
 device discovery
handler ask Akri Agent
for onvif credential
call gRPC...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Akri Instance
Akri Insta...
Attach all device related
 information as a JSON string
 to each created Akri instance
Attach all device related...
Detect Akri
 instance change
Detect Akri...
Broker POD
Broker P...
Broker POD
Broker P...
Broker POD
Broker P...
create broker POD and
 transfer all device
 information
create broker POD and...
Device Discovery Handler
Device Discovery Han...
Implement a new gPRC Service: RequestDeviceInfo
Implement a new gPR...
Get Device Info from 
RequestDeviceInfo
Get Device Info from...
Continue Device
 Discovery

For example,
for Onvif, fetch
video stream URI
with credential
Continue Device...
Complete discoverying 
new device
Complete discoverying...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/proposals/Integrate with external device inventory.md b/proposals/Integrate with external device inventory.md index 430dae7..6c5094b 100644 --- a/proposals/Integrate with external device inventory.md +++ b/proposals/Integrate with external device inventory.md @@ -22,13 +22,12 @@ The above issues can be resolved by allowing Akri getting additional device info The below workflow presents a new flow from discovering device till creating broker POD. Additional steps are highlighted as yellow color. -- Introduce a new setting that user can specify the name of a customized external device inventory POD or service, so Akri agent can request for additional device information. The proposed external device inventory POD/service must expose a REST POST API /queryDevice for Akri Agent to raise request. -- Instead of directly creating Akri instance after Akri agent discovers new devices, Akri agent will query the external device inventory POD/service to get more device related information, including credential. -- Please note for protected ONVIF device, Akri agent should use the ONVIF credential to finish a successful discovery work, such as querying stream URI. +- Introduce a new setting that user can specify a customized external device inventory POD or service, so Akri agent can request for additional device information. The proposed external device inventory POD/service must expose a REST POST API /queryDevice for Akri Agent to raise request. +- Implement a new Akri Agent gRPC service: RequestDeviceInfo. During the procedure of discovering a new device, discovery handler can invoke Akri agent RequestDeviceInfo, and Akri agent will query external device inventory POD/service to get more device related information, including credential. Response device info will be fed back to device handler so it can continue device discovery step. For example, for protected ONVIF device, device discovery handler will use the ONVIF credential to query for camera's stream URI. This proposed external device inventory POD/service name should be set within each Akri configuration, so it is possible that different discovery config has specified external device inventory system. Another flag is proposed to define if the related external device inventory sytem is also device provisioning database. If it is provisioning database, when Akri agent can not fetch any record of a discovered device, it wont create Akri instance for this device. There wont be broker POD created neither for that device. -The external device inventory POD is not deployed by Akri but solution developer will take care. One possible implementation of the device inventory POD can be a POD with a mounted Azure Key Vault drive using AKV ARC extenstion. It can fetch device credential and assist Akri agent. The benefit is that device credential can be centrally managed from cloud. +The external device inventory POD is not deployed by Akri but solution developer will take care its creation. One possible implementation of the device inventory POD can be a POD with a mounted Azure Key Vault drive using AKV ARC extenstion. It can fetch device credential and assist Akri agent. The benefit is that device credential can be centrally managed from cloud. ## Additional Usage 1: what if a device is undiscoverable but can be added manually