Project: Shifu (Provisioning / Automation & Configuration)
File: design-shifu.md

- - - - - - - - - - - - - - - - - Shifu's foremost job is to make developers and operators happy. Thus, all Shifu's designs are human centric. Thus, there are a few design requirements to achieve the human centric goal: Shifu can always be deployed by one single line of command. Shifu should be able to recognize and start providing basic functionalities to the newly added IoT device automagically. Once the developer finishes filling out Shifu's template, all designed features of the device should be immediately available. The developer can further implement Shifu's interface/SDKs to create customized features and open up endless possibilities. Shifu aims to achieve zero maintenance by adopting cutting edge cloud native best practices. After all, Shifu should be able to take care of himself and make operators' lives easier! It is extremely important to have a simple architecture and logic to preserve a high standard of readability and maintainability. An easy-to-read and easy-to-change code base will enable developers to improve *Shifu or even create their very own versions of Shifu*. Being *Shifu, robustness is a must. A highly resilient Shifu* is very important to operator's mental health. Who wants to deal with crash loops everyday? *Shifu* should always be able to heal itself upon unexpected events and drive itself towards goal state. *Shifu* aims to achieve high availability and eliminate your operation costs. *Shifu* should be able to run on all major platforms, including but not limited to x86/64, ARM64, etc. Being an IoT framework running on the edge, *Shifu* has to be lightweight. Hey Shifu, time to lose some weights! With so many heterogenous IoT devices around the world, *Shifu* needs to be extensible and flexible to accommodate different scenarios. Our first priority is to ensure *shifu* runs on Kubernetes smoothly. We might provide standalone version in the future. *Shifu's design has built-in fault-tolerance. Shifu* strives to achieve >99.9999% up-time, but doesn't aim for 100% up-time. The current version of *Shifu* resembles a . By leveraging the operator pattern, Shifu automatically gains all the benefits of Kubernetes offers. *edgeDevice is a physical IoT device managed by Shifu*. *edgeNode is a that can connect to multiple edgeDevices. By default, all worker nodes in the Kubernetes cluster are with

For example User is able to configure nodes to not be an edgeNode, therefore isolating their application Pods and deviceShifu* Pods. *shifud is a daemonset runs on every edgeNode monitoring hardware changes, i.e., edgeDevice connect/disconnect events. shifud is managed by shifuController*. *shifuController is a listens to hardware events sent by shifud and make corresponding actions to manage the lifecycle of deviceShifu*. *deviceShifu is an structural of the edgeDevice. We call it structural because it's not only a virtual presentation of the edgeDevice but also it's capable of driving the corresponding edgeDevice towards its goal state. For example, if you want your robot to move a box but it's currently busy on something else, deviceShifu will cache your instructions and tell your robot to move the box whenever it's available. For the basic part, deviceShifu provides some general functionalities such as edgeDevice health monitoring, state caching, etc. By implementing the interface of deviceShifu, your edgeDevice* can achieve everything its designed for, and much more! *deviceShifu* has two operation modes: *standalone mode: standalone mode is designed to manage a single complex edgeDevice like robotic arm to provide high quality 1-to-1 management for the edgeDevice*. *swarm mode: swarm mode is designed to manage massive simple edgeDevices of the same kind like temperature sensors to provide efficient 1-to-N management for the edgeDevices*. 1.1 connect: an *edgeDevice physically connects to an edgeNode*. 1.2 device connect: *shifud detects the newly connected device, and sends the event to shifuController*. 1.3 create: *shifuController creates a deviceShifu in standalone/swarm mode for the edgeDevice*. 1.4 manage: *deviceShifu starts to manage the newly connected edgeDevice*. Upon an *edgeDevice connects to the edgeNode, Shifu will create a deviceShifu, an augmented digital twin of the edgeDevice* to manage it. ](/img/shifu-device-connect.svg) During normal operation, *shifud and shifuController don't do much. User workloads interacts deviceShifu directly. For example, you can call deviceShifu's API to retrieve device metadata, device health, etc. Since it's two-way communication, once you implement your edgeDevice's specific methods in deviceShifu's API, can also call deviceShifu's API to manage your edgeDevice*. For example, you can setup your video camera's video stream through a few lines of code. ](/img/shifu-device-operating.svg) 3.1 disconnect: an *edgeDevice physically disconnects to an edgeNode*. 3.2 device disconnect: *shifud detects the newly disconnected device, and sends the event to shifuController*. 3.3 delete: *shifuController deletes the deviceShifu for the edgeDevice*. The delete process might take longer due to cleanup. ](/img/shifu-device-disconnect.svg)