Developer Guide
Last updated
Was this helpful?
Last updated
Was this helpful?
This document will walk you through how to set up a local development environment, build Akri component containers, and test Akri using your newly built containers. It also includes instructions on running Akri locally, naming guidelines, and points to documentation on extending Akri with new Discovery Handlers and brokers.
Note: different tools are needed depending on what parts of Akri you are developing. This document aims to make that clear.
To develop, you'll need a Linux environment whether on amd64 or arm64v8. We recommend using an Ubuntu VM; however, WSL2 should work for building and testing (but has not been extensively tested).
The majority of Akri is written in Rust. To install Rust and Akri's component's dependencies, run Akri's setup script:
If you previously installed Rust ensure you are using the v1.73.0 toolchain that Akri's build system uses:
To install Rust and Akri's component's dependencies, run Akri's setup script:
If you previously installed Rust, ensure you are using the v1.73.0 toolchain that Akri's build system uses:
Then, configure your current shell to see Cargo and set v1.73.0 as default toolchain.
Build Controller, Agent, Discovery Handlers, and udev broker
To run all unit tests:
Before running Akri agent or controller locally, please ensure the Akri configuration and instance CRDs are applied to cluster, otherwise use the below command to apply them.
To locally run Akri's Agent, Controller, and Discovery Handlers as part of a Kubernetes cluster, follow these steps:
Build the repo with all default features by running cargo build
Run the desired component by navigating to the appropriate directory and using cargo run
Run the Controller locally with info-level logging and using 8081 to serve Akri's metrics (for Prometheus integration):
METRICS_PORTcan be set to any value as it is only used if Prometheus is enabled. Just ensure that the Controller and Agent use different ports if they are both running.
Run the Agent locally with info-level logging, debug echo enabled for testing, and a metrics port of 8082. The Agent must be run privileged in order to connect to the kubelet. Specify the user path to cargo $HOME/.cargo/bin/cargo so you do not have to re-install cargo for the sudo user:
Note:
DISCOVERY_HANDLERS_DIRECTORYis where Akri agent creates an unix domain socket for discovery handler's registeration. This example uses ~/tmp/akri that should exist or is created before executing this command.
By default, the Agent does not have embedded Discovery Handlers. To allow embedded Discovery Handlers in the Agent, turn on the agent-full feature and the feature for each Discovery Handler you wish to embed -- Debug echo is always included if agent-full is turned on. For example, to run the Agent with OPC UA, ONVIF, udev, and debug echo Discovery Handlers add the following to the above command: --features "agent-full udev-feat opcua-feat onvif-feat".
Note: The environment variables
HOST_CRICTL_PATH,HOST_RUNTIME_ENDPOINT, andHOST_IMAGE_ENDPOINTare for slot-reconciliation (making sure Pods that no longer exist are not still claiming Akri resources). The values of these vary based on Kubernetes distribution. The above is for vanilla Kubernetes. For MicroK8s, useHOST_CRICTL_PATH=/usr/local/bin/crictl HOST_RUNTIME_ENDPOINT=/var/snap/microk8s/common/run/containerd.sock HOST_IMAGE_ENDPOINT=/var/snap/microk8s/common/run/containerd.sockand for K3s, useHOST_CRICTL_PATH=/usr/local/bin/crictl HOST_RUNTIME_ENDPOINT=/run/k3s/containerd/containerd.sock HOST_IMAGE_ENDPOINT=/run/k3s/containerd/containerd.sock.
To run Discovery Handlers locally, simply navigate to the Discovery Handler under akri/discovery-handler-modules/ and run using cargo run, setting where the Discovery Handler socket should be created in the DISCOVERY_HANDLERS_DIRECTORY variable. The discovery handlers must be run privileged in order to connect to the Agent. For example, to run the ONVIF Discovery Handler locally:
Makefile has been created to help with the more complicated task of building the Akri components and containers for the various supported platforms.
In order to cross-build Akri's Rust code for both ARM and x64 containers, several tools are leveraged.
qemu can be installed with:
For qemu to be fully configured on Ubuntu 18.04, after running apt-get install, run these commands:
To build containers, log into the desired repository:
To ensure quick builds, we have created a number of intermediate containers that rarely change.
By default, Makefile will try to create containers with tag following this format: <repo>/$USER/<component>:<label> where
<component> = opencv-base
<repo> = devcaptest.azurecr.io
<repo> can be overridden by setting REGISTRY=<desired repo>
$USER = the user executing Makefile (could be root if using sudo)
<repo>/$USER can be overridden by setting PREFIX=<desired container path>
These containers allow the ONVIF broker to be created without rebuilding OpenCV for .NET each time. There is a container built for AMD64 and it is used to crossbuild to each supported platform. The dockerfile can be found here: build/containers/intermediate/Dockerfile.opencvsharp-build.
By default, Makefile will try to create containers with tag following this format: <repo>/$USER/<component>:<label> where
<component> = controller | agent | etc
<repo> = devcaptest.azurecr.io
<repo> can be overridden by setting REGISTRY=<desired repo>
$USER = the user executing Makefile (could be root if using sudo)
<repo>/$USER can be overridden by setting PREFIX=<desired container path>
<label> = v$(cat version.txt)
<label> can be overridden by setting LABEL_PREFIX=<desired label>
Run the following to inspect an already running Akri installation in order to see the currently applied yamls such as the Configuration CRD, Instance CRD, protocol Configurations, Agent DaemonSet, and Controller Deployment:
Akri existed before naming guidelines were documented and may not employ the guidelines summarized here. However, it is hoped that developers will, at least, consider these guidelines when extending Akri.
Akri uses English
Types need not be included in names unless ambiguity would result
Shorter, simpler names are preferred
Various Discovery Handlers have been developed: debug_echo, onvif, opcua, udev
Guidance:
snake_case names
(widely understood) initializations|acronyms are preferred
Various samples Brokers have been developed: onvif-video-broker, opcua-monitoring-broker, udev-video-broker
Guidance:
Broker names should reflect Discovery Handler (Protocol) names and be suffixed -broker
Use Programming language-specific naming conventions when developing Brokers in non-Rust languages
Various Kubernetes Resources have been developed:
CRDS: Configurations, Instances
Instances: akri-agent-daemonset, akri-controller-deployment, akri-onvif, akri-opcua, akri-udev
Guidance:
Kubernetes Convention is that resources (e.g. DaemonSet) and CRDs use (upper) CamelCase
Akri Convention is that Akri Kubernetes resources be prefixed akri-, e.g. akri-agent-daemonset
Names combining words should use hyphens (-) to separate the words e.g. akri-debug-echo
NOTE
akri-agent-daemonsetcontradicts the general principle of not including types, if it had been named after these guidelines were drafted, it would be namedakri-agent.Kubernetes' resources are strongly typed and the typing is evident through the CLI e.g.
kubectl get daemonsets/akri-agent-daemonsetand through a resource'sKind(e.g.DaemonSet). Including such types in the name is redundant.
Fork and clone . Then, navigate to the repo's top folder.
Note: To build a specific component, use the -p parameter along with the . For example, to only build the Agent, run cargo build -p agent
Note: To test a specific component, use the -p parameter along with the . For example, to only test the Agent, run cargo test -p agent
Create or provide access to a valid cluster configuration by setting KUBECONFIG (can be done in the command line) ... for the sake of this, the config is assumed to be in $HOME/.kube/config. Reference Akri's if needed.
To run the , an environment variable, DEBUG_ECHO_INSTANCES_SHARED, must be set to specify whether it should register with the Agent as discovering shared or unshared devices. Run the debug echo Discovery Handler to discover mock unshared devices like so:
Containers for Akri are currently hosted in ghcr.io/project-akri/akri using the new . Any container repository can be used for private containers. If you want to enable GHCR, you can follow the .
<label> = the label is defined in
For more detailed information about the Akri build infrastructure and other Makefile targets, review the
When installing Akri using helm, you can set the imagePullSecrets, image.repository and image.tag to point to your newly created containers. For example, to install Akri with custom Controller and Agent containers, run the following, specifying the image.tag version to reflect :
More information about the Akri Helm charts can be found in the .
If you make changes to anything in the , you will probably need to create a new Helm chart for Akri. This can be done using the command. To create a chart using the current state of the Helm templates and CRDs, run (from one level above the Akri directory) helm package akri/deployment/helm/. You will see a tgz file called akri-<akri-version>.tgz at the location where you ran the command. Now, install Akri using that chart:
When you install Akri using Helm, Helm creates the DaemonSet, Deployment, and Configuration yamls for you (using the values set in the install command) and applies them to the cluster. To inspect those yamls before installing Akri, you can use . For example, you will see the image in the Agent DaemonSet set to image: "ghcr.io/<your-github-alias>/agent:v<akri-version>-amd64" if you run the following:
To modify an Akri installation to reflect a new state, you can use . See the for further explanation.
In order to kickstart using and debugging Akri, a debug echo Discovery Handler has been created. See its to start using it.
Akri was made to be easily extensible as Discovery Handlers and brokers can be implemented in any language and deployed in their own Pods. Reference the and documents to get started, or if you prefer to learn by example, reference the .
This document focuses on developing Akri's Rust components; however, Akri has several non-Rust components. Reference their respective READMEs in for instructions on developing.
Several and for demo purposes.
A for testing and using Akri's OPC UA Discovery Handler
Python script for running .
Python script for .
One of the in Computer Science is naming things. It is proposed that Akri adopt naming guidelines to make developers' lives easier by providing consistency and reduce naming complexity.
Akri is written principally in Rust, and Rust conventions are used
NOTE Even though the initialization of includes "Video", the specification is broader than video and the broker name adds specificity by including the word (onvif-video-broker) in order to effectively describe its functionality.