You should either have an existing k3s or Kubernetes cluster to deploy the Octopus app. For users who don't have an existing Kubernetes cluster can follow the Spin-up k3s Cluster Using k3d to run a quick test.
There are two ways to deploy the Octopus, for convenience, we will use the manifest YAML file to bring up the Octopus. The installer YAML file is under the deploy/e2e directory on Github:
Octopus uses a dummy device for testing, which does not need to be connected to a real physical device. So we can assume that the dummy device is a real-world device here.
First, we need to describe the device as a resource in Kubernetes. This description process is modeling the device. In Kubernetes, the best way to describe resources is to use CustomResourceDefinitions, so defining a device model in Octopus is actually defining the CustomResourceDefinition. Take a quick look at this DummySpecialDevice model(assume this is a smart fan):
description: DummySpecialDevice is the Schema for the dummy special device
API.
properties:
...
spec:
description: DummySpecialDeviceSpec defines the desired state of DummySpecialDevice.
properties:
gear:
description: Specifies how fast the dummy special device should be.
enum:
- slow
- middle
- fast
type: string
"on":
description: Turn on the dummy special device.
type: boolean
protocol:
description: Protocol for accessing the dummy special device.
properties:
location:
type: string
required:
- location
type: object
required:
-"on"
- protocol
type: object
status:
description: DummySpecialDeviceStatus defines the observed state of DummySpecialDevice.
properties:
gear:
description: Reports the current gear of dummy special device.
enum:
- slow
- middle
- fast
type: string
rotatingSpeed:
description: Reports the detail number of speed of dummy special device.
format: int32
type: integer
type: object
type: object
...
status:
...
The dummy adaptor installer YAML file is under the adaptors/dummy/deploy/e2e directory, the all_in_one.yaml contains the device model and the device adaptor, we can apply it into the cluster directly:
Next, we are going to connect the dummy device via DeviceLink YAML. A DeviceLink consists of 3 parts: Adaptor, Model, and Device spec:
The Adaptor defines which adaptor to use and the node that the real-world device should be connected to.
Model describes the model of a device, it is the TypeMeta of the device model CRD.
Device spec describes how to connect to the device and its desired properties or status of the device, those parameters are defined by the device model CRD.
Let's assume that there is a device named living-room-fan that can be connected through the edge-worker node, we can use the following YAML to test how it works.
cat <<EOF | kubectl apply -f -
apiVersion: edge.cattle.io/v1alpha1
kind: DeviceLink
metadata:
name: living-room-fan
namespace: default
spec:
adaptor:
node: edge-worker # select the node that the device will be connect to
name: adaptors.edge.cattle.io/dummy
model:
apiVersion:"devices.edge.cattle.io/v1alpha1"
kind:"DummySpecialDevice"
template:
metadata:
labels:
device: living-room-fan
spec:# specify device specs
protocol:
location:"living_room"
gear: slow
"on":true
EOF
There are several states of a DeviceLink, if we found the PHASE is DeviceConnected and its STATUS is on Healthy, we can now query its status use the same DeviceLink name of device model CRD(i.e dummyspecialdevice in here):