Note: different tools are needed depending on what parts of Akri you are developing. This document aims to make that clear.

• ​Requirements​
• ​Build and Test Akri's Components​
• ​Running Akri's Components Locally​
• ​Building Akri Containers​
• ​Installing Akri with newly built containers​
• ​Useful Helm commands​
• ​Testing with Debug Echo Discovery Handler​
• ​Discovery Handler and Broker Development​
• ​Developing Akri's non-Rust components​
• ​Naming Guidelines​

1. 1.

   Fork and clone Akri. Then, navigate to the repo's top folder.
2. 2.

   To install Rust and Akri's component's dependencies, run Akri's setup script:

   1

   ./build/setup.sh

   Copied!

   If you previously installed Rust, ensure you are using the v1.55.0 toolchain that Akri's build system uses:

   1

   sudo curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain=1.55.0

   Copied!

   Then, configure your current shell to see Cargo and set v1.55.0 as default toolchain.

   1

   source $HOME/.cargo/env

   2

   rustup default 1.55.0

   3

   cargo version

   Copied!
3. 3.

   Build Controller, Agent, Discovery Handlers, and udev broker

   1

   cargo build

   Copied!

   Note: To build a specific component, use the -p parameter along with the workspace member. For example, to only build the Agent, run cargo build -p agent

4. 4.

   To run all unit tests:

   1

   cargo test

   Copied!

   Note: To test a specific component, use the -p parameter along with the workspace member. For example, to only test the Agent, run cargo test -p agent

1. 1.

   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 cluster setup instructions if needed.
2. 2.

   Build the repo with all default features by running cargo build
3. 3.

   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):

   1

   cd akri/controller

   2

   RUST_LOG=info METRICS_PORT=8081 KUBECONFIG=$HOME/.kube/config cargo run

   Copied!

   METRICS_PORT can 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:

   1

   cd akri/agent

   2

   sudo -E DEBUG_ECHO_INSTANCES_SHARED=true ENABLE_DEBUG_ECHO=1 RUST_LOG=info METRICS_PORT=8082 KUBECONFIG=$HOME/.kube/config DISCOVERY_HANDLERS_DIRECTORY=~/tmp/akri AGENT_NODE_NAME=myNode HOST_CRICTL_PATH=/usr/bin/crictl HOST_RUNTIME_ENDPOINT=/var/run/dockershim.sock HOST_IMAGE_ENDPOINT=/var/run/dockershim.sock $HOME/.cargo/bin/cargo run

   Copied!

   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, and HOST_IMAGE_ENDPOINT are 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, use HOST_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.sock and for K3s, use HOST_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:

   1

   cd akri/discovery-handler-modules/onvif-discovery-handler/

   2

   sudo -E RUST_LOG=info DISCOVERY_HANDLERS_DIRECTORY=~/tmp/akri AGENT_NODE_NAME=myNode $HOME/.cargo/bin/cargo run

   Copied!

   To run the debug echo Discovery Handler, 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:

   1

   cd akri/discovery-handler-modules/debug-echo-discovery-handler/

   2

   RUST_LOG=info DEBUG_ECHO_INSTANCES_SHARED=false DISCOVERY_HANDLERS_DIRECTORY=~/tmp/akri AGENT_NODE_NAME=myNode $HOME/.cargo/bin/cargo run

   Copied!

• The Cross tool can be installed with this command: cargo install cross.
• qemu can be installed with:

  1

  sudo apt-get install -y qemu qemu qemu-system-misc qemu-user-static qemu-user binfmt-support

  Copied!

  For qemu to be fully configured on Ubuntu 18.04, after running apt-get install, run these commands:

  1

  sudo mkdir -p /lib/binfmt.d

  2

  sudo sh -c 'echo :qemu-arm:M::\\x7fELF\\x01\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x28\\x00:\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\xfe\\xff\\xff\\xff:/usr/bin/qemu-arm-static:F > /lib/binfmt.d/qemu-arm-static.conf'

  3

  sudo sh -c 'echo :qemu-aarch64:M::\\x7fELF\\x02\\x01\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\xb7\\x00:\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\xfe\\xff\\xff\\xff:/usr/bin/qemu-aarch64-static:F > /lib/binfmt.d/qemu-aarch64-static.conf'

  4

  sudo systemctl restart systemd-binfmt.service

  Copied!

• <component> = rust-crossbuild | 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>
• <label> = the label is defined in ../build/intermediate-containers.mk​

• <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>

• Several sample brokers and applications for demo purposes.
• A certificate generator for testing and using Akri's OPC UA Discovery Handler
• Python script for running end-to-end integration tests.
• Python script for testing Akri's Configuration validation webhook.

• Akri uses English
• Akri is written principally in Rust, and Rust naming conventions are used
• Types need not be included in names unless ambiguity would result
• Shorter, simpler names are preferred

• snake_case names
• (widely understood) initializations|acronyms are preferred

• 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

NOTE Even though the initialization of ONVIF 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.

• CRDS: Configurations, Instances
• Instances: akri-agent-daemonset, akri-controller-deployment, akri-onvif, akri-opcua, akri-udev

• 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-daemonset contradicts the general principle of not including types, if it had been named after these guidelines were drafted, it would be named akri-agent.

Kubernetes' resources are strongly typed and the typing is evident through the CLI e.g. kubectl get daemonsets/akri-agent-daemonset and through a resource's Kind (e.g. DaemonSet). Including such types in the name is redundant.