Mock Discovery Handler for Testing
Background
In order to kick start using and debugging Akri, a "debug echo" Discovery Handler has been created. The Discovery Handler "discovers" all devices listed in the descriptions array in the discoveryDetails of a Debug Echo configuration. Devices are visible to the Discovery Handler so long as the word "OFFLINE" does not exist in the file /tmp/debug-echo-availability.txt in the Pod in which the Discovery Handler is running.
Deploying the Debug Echo Discovery Handler
In order for the Agent to know how to discover Debug Echo devices, the Debug Echo Discovery Handler must exist. Akri supports an Agent image that includes all supported Discovery Handlers. This Agent will be used if agent.full=true. By default, a slim Agent without any embedded Discovery Handlers is deployed and the required Discovery Handlers can be deployed as DaemonSets. This documentation will use that strategy, deploying Debug Echo Discovery Handlers by specifying debugEcho.discovery.enabled=true when installing Akri. Notes are provided for how the steps change if using embedded Discovery Handlers.
Since the Debug Echo Discovery Handler is for debugging, its use must be explicitly enabled by setting agent.allowDebugEcho=true.
Quickstart
Installation with Pod Brokers
This section walks through deploying non-terminating Nginx Kubernetes Pods to discovered mock devices. Skip to the next section for instructions on deploying terminating busybox Kubernetes Jobs to discovered mock devices.
To install Akri with external Debug Echo Discovery Handlers and a Configuration to discover unshared debug echo devices, run:
To instead install Akri with Debug Echo Discovery Handlers embedded in the Agent, set agent.full=true and remove debugEcho.discovery.enabled=true like in the following installation:
By default, the Debug Echo Configuration discovers two devices, foo1 and foo2, and automatically deploys an empty nginx broker Pod to each discovered device, so you should see two instances and two brokers created as a result of your installation. By default, it also creates an Instance service for each device and a Configuration service for all discovered devices. The Akri Agents, Controller, and (if using external Discovery Handlers) Debug Echo Discovery Handlers should also be created.
Set debugEcho.configuration.shared=true to discover Debug Echo devices that are shared by all nodes. For example, when Akri is installed like above with debugEcho.configuration.shared=false onto a 3 node cluster. 6 Debug Echo devices will be discovered and 6 Instances will be created, 2 for each Node. However, if debugEcho.configuration.shared=true is set, only 2 will be discovered as it is mocking all 3 nodes "utilizing" the same two devices. Set debugEcho.configuration.capacity=3 to allow all 3 nodes to receive brokers to utilize each of the shared devices. It defaults to 1.
Installation with Job Brokers
This section walks through deploying busybox Kubernetes Jobs to discovered mock devices. Go to the previous section for instructions on deploying non-terminating nginx Kubernetes Pods to discovered mock devices.
To install Akri with external Debug Echo Discovery Handlers and a Configuration to discover unshared debug echo devices, run:
To instead install Akri with Debug Echo Discovery Handlers embedded in the Agent, set agent.full=true and remove debugEcho.discovery.enabled=true like in the following installation:
By default, the Debug Echo Configuration discovers two devices, foo1 and foo2, and automatically deploys an empty nginx broker Pod to each discovered device, so you should see two instances and two brokers created as a result of your installation. By default, it also creates an Instance service for each device and a Configuration service for all discovered devices. The Akri Agents, Controller, and (if using external Discovery Handlers) Debug Echo Discovery Handlers should also be created.
Set debugEcho.configuration.shared=true to discover Debug Echo devices that are shared by all nodes. For example, when Akri is installed like above with debugEcho.configuration.shared=false onto a 3 node cluster. 6 Debug Echo devices will be discovered and 6 Instances will be created, 2 for each Node. However, if debugEcho.configuration.shared=true is set, only 2 will be discovered as it is mocking all 3 nodes "utilizing" the same two devices. Set debugEcho.configuration.capacity=3 to allow all 3 nodes to receive brokers to utilize each of the shared devices. It defaults to 1.
Marking Devices "OFFLINE"
Debug Echo devices are "unplugged"/"disconnected" by writing "OFFLINE" into the /tmp/debug-echo-availability.txt file inside the pod in which the Discovery Handler is running.
By default, Debug Echo Discovery Handlers run in their own Pods, so exec into each to mark the devices offline. For a single node cluster:
shared devices have a 5 minute grace period before their instances are deleted, as they are more often network devices prone to intermittent connectivity.
For multi-node clusters, each Agent or Debug Echo Discovery Handler must be execed into.
If agent.full=true was specified when installing Akri, the Debug Echo Discovery Handlers run inside the Agent, so exec into each Agent to mark the devices offline. For a single node cluster:
Caveat: Debug Echo devices likely should not be marked as shared for multi-node clusters. This is because the contents of /tmp/debug-echo-availability.txt could be different for each node. If one node marks a device as "OFFLINE" but another does not, there is inconsistency around the existence of the device. However, this may be a scenario you want to consider or test.
Marking Devices "ONLINE"
Debug Echo devices are "plugged in"/"reconnected" by removing "OFFLINE" from the /tmp/debug-echo-availability.txt file inside the pod in which the Discovery Handler is running. The commands below replace the file contents with "ONLINE".
By default, Debug Echo Discovery Handlers run in their own Pods, so exec into each to mark the devices offline. For a single node cluster:
For multi-node clusters, each Agent or Debug Echo Discovery Handler must be execed into.
If agent.full=true was specified when installing Akri, the Debug Echo Discovery Handlers run inside the Agent, so exec into each Agent to mark the devices offline. For a single node cluster:
In the Weeds: Debug Echo Configuration Settings
Discovery Handler Discovery Details Settings
Discovery Handlers are passed discovery details that are set in a Configuration to determine what to discover, filter out of discovery, and so on. The Debug Echo Discovery Handler simply "discovers" a device for each string in discoveryDetails.descriptions in a Configuration.
| Helm Key | Value | Default | Description |
|---|---|---|---|
debugEcho.configuration.discoveryDetails.description | array of arbitrary Strings | ["foo1", "foo2"] | Names for fake devices that will be discovered |
Broker Pod Settings
By default, brokers are deployed to discovered Debug Echo devices. Set debugEcho.configuration.brokerPod.image.repository="" to not deploy broker Pods:
| Helm Key | Value | Default | Description |
|---|---|---|---|
debugEcho.configuration.brokerPod.image.repository | image string | nginx | image of broker Pod that should be deployed to discovered devices |
debugEcho.configuration.brokerPod.image.tag | tag string | "latest" | image tag of broker Pod that should be deployed to discovered devices |
Disabling Automatic Service Creation
By default, if a broker Pod is specified, the Debug Echo Configuration will create services for all the brokers of a specific Akri Instance and all the brokers of an Akri Configuration. The creation of these services can be disabled:
| Helm Key | Value | Default | Description |
|---|---|---|---|
debugEcho.configuration.createInstanceServices | true, false | true | a service should be automatically created for each broker Pod |
debugEcho.configuration.createConfigurationService | true, false | true | a single service should be created for all brokers of a Configuration |
Capacity Setting
By default, if a broker Pod is specified, a single broker Pod is deployed to each device. To modify the Configuration so that an OPC UA server is accessed by more or fewer nodes via broker Pods, update the debugEcho.configuration.capacity setting to reflect the correct number. For example, if your high availability needs are met by having 1 redundant pod, you can update the Configuration by setting debugEcho.configuration.capacity=2:
| Helm Key | Value | Default | Description |
|---|---|---|---|
debugEcho.configuration.capacity | number | 1 | maximum number of brokers that can be deployed to utilize a device (up to 1 per Node) |
Modifying a Configuration
Akri provides further documentation on modifying the broker PodSpec, instanceServiceSpec, or configurationServiceSpec More information about how to modify an installed Configuration, add additional Configurations to a cluster, or delete a Configuration can be found in the Customizing an Akri Installation document.
Implementation details
The DebugEcho implementation can be understood by looking at its Discovery Handler, which contains the DebugEchoDiscoveryDetails struct, which describes the expected format of a Configuration's DiscoveryDetails.
Last updated