Welcome to KubeEdge’s documentation!

_images/KubeEdge_logo.png

KubeEdge is an open source system for extending native containerized application orchestration capabilities to hosts at Edge.

Welcome to KubeEdge

KubeEdge is an open source system for extending native containerized application orchestration capabilities to hosts at Edge.

Why KubeEdge?

Learn about KubeEdge and the KubeEdge Mission here

First Steps

To get the most out of KubeEdge, start by reviewing a few introductory topics:

How to contribute

Kubeedge is Apache 2.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on commit message formatting, contact points for developers, and other resources to help get contributions into kubeedge.

Email and chat

Getting started

  • Fork the repository on GitHub
  • Read the README.md for build instructions

Reporting bugs and creating issues

Reporting bugs is one of the best ways to contribute. However, a good bug report has some very specific qualities, so please read over our short document on reporting bugs before submitting a bug report. This document might contain links to known issues, another good reason to take a look there before reporting a bug.

Contribution flow

This is a rough outline of what a contributor’s workflow looks like:

  • Create a topic branch from where to base the contribution. This is usually master.
  • Make commits of logical units.
  • Make sure commit messages are in the proper format (see below).
  • Push changes in a topic branch to a personal fork of the repository.
  • Submit a pull request to kubeedge/kubeedge.
  • The PR must receive an approval from two maintainers.

Thanks for contributing!

Code style

The coding style suggested by the Golang community is used in kubeedge. See the style doc for details.

Please follow this style to make kubeedge easy to review, maintain and develop.

Format of the commit message

We follow a rough convention for commit messages that is designed to answer two questions: what changed and why. The subject line should feature the what and the body of the commit should describe the why.

scripts: add test codes for metamanager

this add some unit test codes to imporve code coverage for metamanager

Fixes #12

The format can be described more formally as follows:

<subsystem>: <what changed>
<BLANK LINE>
<why this change was made>
<BLANK LINE>
<footer>

The first line is the subject and should be no longer than 70 characters, the second line is always blank, and other lines should be wrapped at 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

Roadmap

Release 1.0

KubeEdge will provide the fundamental infrastructure and basic functionalities for IOT/Edge workload. This includes:

  • K8s Application deployment through kubectl from Cloud to Edge node(s)
  • K8s configmap, secret deployment through kubectl from Cloud to Edge node(s) and their applications in Pod
  • Bi-directional and multiplex network communication between Cloud and edge nodes
  • K8s Pod and Node status querying with kubectl at Cloud with data collected/reported from Edge
  • Edge node autonomy when its getting offline and recover post reconnection to Cloud
  • Device twin and MQTT protocol for IOT devices talking to Edge node

Release 2.0 and Future

  • Build service mesh with KubeEdge and Istio
  • Enable function as a service at Edge
  • Support more types of device protocols to Edge node such as AMQP, BlueTooth, ZigBee, etc.
  • Evaluate and enable super large scale of Edge clusters with thousands of Edge nodes and millions of devices
  • Enable intelligent scheduling of apps. to large scale of Edge nodes
  • etc.

Support

If you need support, start with the troubleshooting guide, and work your way through the process that we’ve outlined.

Community

Slack channel:

We use Slack for public discussions. To chat with us or the rest of the community, join us in the KubeEdge Slack team channel #general. To sign up, use our Slack inviter link here.

Mailing List

Please sign up on our mailing list

What is KubeEdge

KubeEdge is an open source system extending native containerized application orchestration and device management to hosts at the Edge. It is built upon Kubernetes and provides core infrastructure support for networking, application deployment and metadata synchronization between cloud and edge. It also supports MQTT and allows developers to author custom logic and enable resource constrained device communication at the Edge. Kubeedge consists of a cloud part and an edge part. The edge part has already been open sourced and the cloud part is coming soon!

Advantages

The advantages of Kubeedge include mainly:

  • Edge Computing

    With business logic running at the Edge, much larger volumes of data can be secured & processed locally where the data is produced. This reduces the network bandwidth requirements and consumption between Edge and Cloud. This increases responsiveness, decreases costs, and protects customers’ data privacy.

  • Simplified development

    Developers can write regular http or mqtt based applications, containerize these, and run them anywhere - either at the Edge or in the Cloud - whichever is more appropriate.

  • Kubernetes-native support

    With KubeEdge, users can orchestrate apps, manage devices and monitor app and device status on Edge nodes just like a traditional Kubernetes cluster in the Cloud

  • Abundant applications

    It is easy to get and deploy existing complicated machine learning, image recognition, event processing and other high level applications to the Edge.

Components

KubeEdge is composed of these components:

  • Edged: Edged is an agent running on edge node for managing user’s application.
  • EdgeHub: EdgeHub is a web socket client, which is responsible for interacting with Huawei Cloud IEF service, including sync cloud side resources update, report edged side host and device status changes.
  • EventBus: EventBus is a MQTT client to interact with MQTT server(mosquitto), offer subscribe and publish capability to other components.
  • DeviceTwin: DeviceTwin is responsible for storing device status and syncing device status to the cloud. It also provides query interfaces for applications.
  • MetaManager: MetaManager is the message processor between edged and edgehub. It is also responsible for storing/retrieving metadata to/from a lightweight database(SQLite).

Architecture

KubeEdge Architecture

Getting involved

There are many ways to contribute to Kubeedge, and we welcome contributions!Read the contributor’s guide to get started on the code.

Beehive

Beehive Overview

Beehive is a messaging framework based on go-channels for communication between modules of KubeEdge. A module registered with beehive can communicate with other beehive modules if the name with which other beehive module is registered or the name of the group of the module is known. Beehive supports following module operations:

  1. Add Module
  2. Add Module to a group
  3. CleanUp (remove a module from beehive core and all groups)

Beehive supports following message operations:

  1. Send to a module/group
  2. Receive by a module
  3. Send Sync to a module/group
  4. Send Response to a sync message

Message Format

Message has 3 parts

  1. Header:
    1. ID: message ID (string)
    2. ParentID: if it is a response to a sync message then parentID exists (string)
    3. TimeStamp: time when message was generated (int)
    4. Sync: flag to indicate if message is of type sync (bool)
  2. Route:
    1. Source: origin of message (string)
    2. Group: the group to which the message has to be broadcasted (string)
    3. Operation: what’s the operation on the resource (string)
    4. Resource: the resource to operate on (string)
  3. Content: content of the message (interface{})

Register Module

  1. On starting edge_core, each module tries to register itself with the beehive core.
  2. Beehive core maintains a map named modules which has module name as key and implementation of module interface as value.
  3. When a module tries to register itself with beehive core, beehive core checks from already loaded modules.yaml config file to check if the module is enabled. If it is enabled, it is added in the modules map orelse it is added in the disabled modules map.

Channel Context Structure Fields

(Important for understanding beehive operations)

  1. channels: channels is a map of string(key) which is name of module and chan(value) of message which will used to send message to the respective module.
  2. chsLock: lock for channels map
  3. typeChannels: typeChannels is is map of string(key)which is group name and (map of string(key) to chan(value) of message ) (value) which is map of name of each module in the group to the channels ofcorresponding module.
  4. typeChsLock: lock for typeChannels map
  5. anonChannels: anonChannels is a map of string(parentid) to chan(value) of message which will be used for sending response for a sync message.
  6. anonChsLock: lock for anonChannels map

Module Operations

Add Module

  1. Add module operation first creates a new channel of message type.
  2. Then the module name(key) and its channel(value) is added in the channels map of channel context structure.
  3. Eg: add edged module
coreContext.Addmodule(“edged”)

Add Module to Group

  1. addModuleGroup first gets the channel of a module from the channels map.
  2. Then the module and its channel is added in the typeChannels map where key is the group and in the value is a map in which (key is module name and value is the channel).
  3. Eg: add edged in edged group. Here 1st edged is module name and 2nd edged is the group name.
coreContext.AddModuleGroup(“edged”,”edged”)

CleanUp

  1. CleanUp deletes the module from channels map and deletes the module from all groups(typeChannels map).
  2. Then the channel associated with the module is closed.
  3. Eg: CleanUp edged module
coreContext.CleanUp(“edged”)

Message Operations

Send to a Module

  1. Send gets the channel of a module from channels map.
  2. Then the message is put on the channel.
  3. Eg: send message to edged.
coreContext.Send(“edged”,message)

Send to a Group

  1. Send2Group gets all modules(map) from the typeChannels map.
  2. Then it iterates over the map and sends the message on the channels of all modules in the map.
  3. Eg: message to be sent to all modules in edged group.
coreContext.Send2Group(“edged”,message) message will be sent to all modules in edged group.

Receive by a Module

  1. Receive gets the channel of a module from channels map.
  2. Then it waits for a message to arrive on that channel and returns the message. Error is returned if there is any..
  3. Eg: receive message for edged module
msg,err := coreContext.Receive("edged")

SendSync to a Module

  1. SendSync takes 3 parameters, (module, message and timeout duration)
  2. SendSync first gets the channel of the module from the channels map.
  3. Then the message is put on the channel.
  4. Then a new channel of message is created and is added in anonChannels map where key is the messageID.
  5. Then it waits for the message(response) to be received on the anonChannel it created till timeout.
  6. If message is received before timeout, message is returned with nil error orelse timeout error is returned.
  7. Eg: send sync to edged with timeout duration 60 seconds
response,err := coreContext.SendSync("edged",message,60*time.Second)

SendSync to a Group

  1. Get the list of modules from typeChannels map for the group.
  2. Create a channel of message with size equal to the number of modules in that group and put in anonChannels map as value with key as messageID.
  3. Send the message on channels of all the modules.
  4. Wait till timeout. If the length of anonChannel = no of modules in that group, check if all the messages in the channel have parentID = messageID. If no return error else return nil error.
  5. If timeout is reached,return timeout error.
  6. Eg: send sync message to edged group with timeout duration 60 seconds
err := coreContext.Send2GroupSync("edged",message,60*time.Second)

SendResp to a sync message

  1. SendResp is used to send response for a sync message.
  2. The messageID for which response is sent needs to be in the parentID of the response message.
  3. When SendResp is called, it checks if for the parentID of response message , there exists a channel is anonChannels.
  4. If channel exists, message(response) is sent on that channel.
  5. Or else error is logged.
coreContext.SendResp(respMessage)

EventBus

Overview

Eventbus acts as an interface for sending/receiving messages on mqtt topics.

It supports 3 kinds of mode:

  • internalMqttMode
  • externalMqttMode
  • bothMqttMode

Topic

eventbus subscribes to the following topics:

- $hw/events/upload/#
- SYS/dis/upload_records
- SYS/dis/upload_records/+
- $hw/event/node/+/membership/get
- $hw/event/node/+/membership/get/+
- $hw/events/device/+/state/update
- $hw/events/device/+/state/update/+
- $hw/event/device/+/twin/+

Note: topic wildcards

wildcard Description
# It must be the last character in the topic, and matches the current tree and all subtrees.
+ It matches exactly one item in the topic tree.

Flow chart

1. eventbus sends messages from external client

eventbus sends messages from external client

2. eventbus sends response messages to external client

eventbus sends response messages to external client

MetaManager

Overview

MetaManager is the message processor between edged and edgehub. It’s also responsible for storing/retrieving metadata to/from a lightweight database(SQLite).

Metamanager receives different types of messages based on the operations listed below :

  • Insert
  • Update
  • Delete
  • Query
  • Response
  • NodeConnection
  • MetaSync

Insert Operation

Insert operation messages are received via the cloud when new objects are created. An example could be a new user application pod created/deployed through the cloud.

Insert Operation

The insert operation request is received via the cloud by edgehub. It dispatches the request to the metamanager which saves this message in the local database. metamanager then sends an asynchronous message to edged. edged processes the insert request e,g. by starting the pod and populates the response in the message. metamanager inspects the message, extracts the response and sends it back to edged which sends it back to the cloud.

Update Operation

Update operations can happen on objects at the cloud/edge.

The update message flow is similar to an insert operation. Additionally, metamanager checks if the resource being updated has changed locally. If there is a delta, only then the update is stored locally and the message is passed to edged and response is sent back to the cloud.

Update Operation

Delete Operation

Delete operations are triggered when objects like pods are deleted from the cloud.

Delete Operation

Query Operation

Query operations let you query for metadata either locally at the edge or for some remote resources like config maps/secrets from the cloud. edged queries this metadata from metamanager which further handles local/remote query processing and returns the response back to edged. A Message resource can be broken into 3 parts (resKey,resType,resId) based on separator ‘/’.

Query Operation

Response Operation

Responses are returned for any operations performed at the cloud/edge. Previous operations showed the response flow either from the cloud or locally at the edge.

NodeConnection Operation

NodeConnection operation messages are received from edgeHub to give information about the cloud connection status. metamanager tracks this state in-memory and uses it in certain operations like remote query to the cloud.

MetaSync Operation

MetaSync operation messages are periodically sent by metamanager to sync the status of the pods running on the edge node. The sync interval is configurable in conf\edge.yaml ( defaults to 60 seconds ).

meta:
    sync:
        podstatus:
            interval: 60 #seconds

Edgehub

Overview

Edge hub is a web socket client, which is responsible for interacting with Huawei Cloud IEF service. It supports functions like sync cloud side resources update, report edged side host and device status changes.

It acts as the communication link between the edge and the cloud. It forwards the messages received from the cloud to the corresponding module at the edge and vice-versa.

The main functions performed by edgehub are :-

  • Get CloudHub URL
  • Keep Alive
  • Publish Client Info
  • Route to Cloud
  • Route to Edge

Get CloudHub URL

The main responsibility of get cloudHub URL is to contact the placement server and get the URL of cloudHub.

  1. A HTTPS client is created using the certificates provided
  2. A get request is sent to the placement URL
  3. ProjectID and NodeID are added to the body of the response received from the placement URL to form the cloudHub URL.
bodyBytes, _ := ioutil.ReadAll(resp.Body)
url := fmt.Sprintf("%s/%s/%s/events", string(bodyBytes), ehc.config.ProjectID, ehc.config.NodeID)

Keep Alive

A keep-alive message or heartbeat is sent to cloudHub after every heartbeatPeriod.

Publish Client Info

  • The main responsibility of publish client info is to inform the other groups or modules regarding the status of connection to the cloud.
  • It sends a beehive message to all groups (namely metaGroup, twinGroup and busGroup), informing them whether cloud is connected or disconnected.

Route To Cloud

The main responsibility of route to cloud is to receive from the other modules (through beehive framework), all the messages that are to be sent to the cloud, and send them to cloudHub through the websocket connection.

The major steps involved in this process are as follows :-

  1. Continuously receive messages from beehive Context

  2. Send that message to cloudHub

  3. If the message received is a sync message then :

    3.1 If response is received on syncChannel then it creates a map[string] chan containing the messageID of the message as key

    3.2 It waits for one heartbeat period to receive a response on the channel created, if it does not receive any response on the channel within the specified time then it times out.

    3.3 The response received on the channel is sent back to the module using the SendResponse() function.

Route to Cloud

Route To Edge

The main responsibility of route to edge is to receive messages from the cloud (through the websocket connection) and send them to the required groups through the beehive framework.

The major steps involved in this process are as follows :-

  • Receive message from cloudHub
  • Check whether the route group of the message is found.
  • Check if it is a response to a SendSync() function.
  • If it is not a response message then the message is sent to the required group
  • If it is a response message then the message is sent to the syncKeep channel

Route to Edge

DeviceTwin

Overview

DeviceTwin module is responsible for storing device status, dealing with device attributes, handling device twin operations, creating a membership between the edge device and edge node, syncing device status to the cloud and syncing the device twin information between edge and cloud. It also provides query interfaces for applications. Device twin consists of four sub modules (namely membership module, communication module, device module and device twin module) to perform the responsibilities of device twin module.

Operations Performed By Device Twin Controller

The following are the functions performed by device twin controller :-

  • Sync metadata to/from db ( Sqlite )
  • Register and Start Sub Modules
  • Distribute message to Sub Modules
  • Health Check

Sync Metadata to/from db ( Sqlite )

For all devices managed by the edge node , the device twin performs the below operations :-

  • It checks if the device in the device twin context (the list of devices are stored inside the device twin context), if not it adds a mutex to the context.
  • Query device from database
  • Query device attribute from database
  • Query device twin from database
  • Combine the device, device attribute and device twin data together into a single structure and stores it in the device twin context.

Register and Start Sub Modules

Registers the four device twin modules and starts them as separate go routines

Distribute Message To Sub Modules

  1. Continuously listen for any device twin message in the beehive framework.
  2. Send the received message to the communication module of device twin
  3. Classify the message according to the message source, i.e. whether the message is from eventBus, edgeManager or edgeHub, and fills the action module map of the module (ActionModuleMap is a map of action to module)
  4. Send the message to the required device twin module

Health Check

The device twin controller periodically ( every 60 s ) sends ping messages to submodules. Each of the submodules updates the timestamp in a map for itself once it receives a ping. The controller checks if the timestamp for a module is more than 2 minutes old and restarts the submodule if true.

Modules

DeviceTwin consists of four modules, namely :-

  • Membership Module
  • Twin Module
  • Communication Module
  • Device Module

Membership Module

The main responsibility of the membership module is to provide membership to the new devices added through the cloud to the edge node. This module binds the newly added devices to the edge node and creates a membership between the edge node and the edge devices.

The major functions performed by this module are:-

  1. Initialize action callback map which is a map[string]Callback that contains the callback functions that can be performed
  2. Receive the messages sent to membership module
  3. For each message the action message is read and the corresponding function is called
  4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller

The following are the action callbacks which can be performed by the membership module :-

  • dealMembershipGet
  • dealMembershipUpdated
  • dealMembershipDetail

dealMembershipGet: dealMembershipGet() gets the information about the devices associated with the particular edge node, from the cache.

  • The eventbus first receives a message on its subscribed topic (membership-get topic).

  • This message arrives at the devicetwin controller, which further sends the message to membership module.

  • The membership module gets the devices associated with the edge node from the cache (context) and sends the information to the communication module. It also handles errors that may arise while performing the aforementioned process and sends the error to the communication module instead of device details.

  • The communication module sends the information to the eventbus component which further publishes the result on the specified MQTT topic (get membership result topic).

    Membership Get()

dealMembershipUpdated: dealMembershipUpdated() updates the membership details of the node. It adds the devices, that were newly added, to the edge group and removes the devices, that were removed, from the edge group and updates device details, if they have been altered or updated.

  • The eventbus module receives the message that arrives on the subscribed topic and forwards the message to devicetwin controller which further forwards it to the membership module.

  • The membership module adds devices that are newly added, removes devices that have been recently deleted and also updates the devices that were already existing in the database as well as in the cache.

  • After updating the details of the devices a message is sent to the communication module of the device twin, which sends the message to eventbus module to be published on the given MQTT topic.

    Membership Update

dealMembershipDetail: dealMembershipDetail() provides the membership details of the edge node, providing information about the devices associated with the edge node, after removing the membership details of recently removed devices.

  • The eventbus module receives the message that arrives on the subscribed topic,the message is then forwarded to the devicetwin controller which further forwards it to the membership module.

  • The membership module adds devices that are mentioned in the message, removes devices that that are not present in the cache.

  • After updating the details of the devices a message is sent to the communication module of the device twin.

    Membership Detail

Twin Module

The main responsibility of the twin module is to deal with all the device twin related operations. It can perform operations like device twin update, device twin get and device twin sync-to-cloud.

The major functions performed by this module are:-

  1. Initialize action callback map (which is a map of action(string) to the callback function that performs the requested action)
  2. Receive the messages sent to twin module
  3. For each message the action message is read and the corresponding function is called
  4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller

The following are the action callbacks which can be performed by the twin module :-

  • dealTwinUpdate
  • dealTwinGet
  • dealTwinSync

dealTwinUpdate: dealTwinUpdate() updates the device twin information for a particular device.

  • The devicetwin update message can either be received by edgehub module from the cloud or from the MQTT broker through the eventbus component (mapper will publish a message on the device twin update topic) .

  • The message is then sent to the device twin controller from where it is sent to the device twin module.

  • The twin module updates the twin value in the database and sends the update result message to the communication module.

  • The communication module will in turn send the publish message to the MQTT broker through the eventbus.

    Device Twin Update

dealTwinGet: dealTwinGet() provides the device twin information for a particular device.

  • The eventbus component receives the message that arrives on the subscribed twin get topic and forwards the message to devicetwin controller, which further sends the message to twin module.

  • The twin module gets the devicetwin related information for the particular device and sends it to the communication module, it also handles errors that arise when the device is not found or if any internal problem occurs.

  • The communication module sends the information to the eventbus component, which publishes the result on the topic specified .

    Device Twin Get

dealTwinSync: dealTwinSync() syncs the device twin information to the cloud.

  • The eventbus module receives the message on the subscribed twin cloud sync topic .
  • This message is then sent to the devicetwin controller from where it is sent to the twin module.
  • The twin module then syncs the twin information present in the database and sends the synced twin results to the communication module.
  • The communication module further sends the information to edgehub component which will in turn send the updates to the cloud through the websocket connection.
  • This function also performs operations like publishing the updated twin details document, delta of the device twin as well as the update result (in case there is some error) to a specified topic through the communication module, which sends the data to edgehub, which will send it to eventbus which publishes on the MQTT broker.

Sync to Cloud

Communication Module

The main responsibility of communication module is to ensure the communication functionality between device twin and the other components.

The major functions performed by this module are:-

  1. Initialize action callback map which is a map[string]Callback that contains the callback functions that can be performed
  2. Receive the messages sent to communication module
  3. For each message the action message is read and the corresponding function is called
  4. Confirm whether the actions specified in the message are completed or not, if the action is not completed then redo the action
  5. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller

The following are the action callbacks which can be performed by the communication module :-

  • dealSendToCloud
  • dealSendToEdge
  • dealLifeCycle
  • dealConfirm

dealSendToCloud: dealSendToCloud() is used to send data to the cloudHub component. This function first ensures that the cloud is connected, then sends the message to the edgeHub module (through the beehive framework), which in turn will forward the message to the cloud (through the websocket connection).

dealSendToEdge: dealSendToEdge() is used to send data to the other modules present at the edge. This function sends the message received to the edgeHub module using beehive framework. The edgeHub module after receiving the message will send it to the required recipient.

dealLifeCycle: dealLifeCycle() checks if the cloud is connected and the state of the twin is disconnected, it then changes the status to connected and sends the node details to edgehub. If the cloud is disconnected then, it sets the state of the twin as disconnected.

dealConfirm: dealConfirm() is used to confirm the event. It checks whether the type of the message is right and then deletes the id from the confirm map.

Device Module

The main responsibility of the device module is to perform the device related operations like dealing with device state updates and device attribute updates.

The major functions performed by this module are :-

  1. Initialize action callback map (which is a map of action(string) to the callback function that performs the requested action)
  2. Receive the messages sent to device module
  3. For each message the action message is read and the corresponding function is called
  4. Receive heartbeat from the heartbeat channel and send a heartbeat to the controller

The following are the action callbacks which can be performed by the device module :-

  • dealDeviceUpdated
  • dealDeviceStateUpdate

dealDeviceUpdated: dealDeviceUpdated() deals with the operations to be performed when a device attribute update is encountered. It updates the changes to the device attributes, like addition of attributes, updation of attributes and deletion of attributes, in the database. It also sends the result of the device attribute update to be published to the eventbus component] through the communicate module of devicetwin. The eventbus component further publishes the result on the specified topic.

Device Update

dealDeviceStateUpdate: dealDeviceStateUpdate() deals with the operations to be performed when a device status update is encountered. It updates the state of the device as well as the last online time of the device in the database. It also sends the update state result, through the communication module, to the cloud through the edgehub module and to the eventbus module which in turn publishes the result on the specified topic of the MQTT broker.

Device State Update

Tables

DeviceTwin module creates three tables in the database, namely :-

  • Device Table
  • Device Attribute Table
  • Device Twin Table

Device Table

Device table contains the data regarding the devices added to a particular edge node. The following are the columns present in the device table :

Column Name Description
ID This field indicates the id assigned to the device
Name This field indicates the name of the device
Description This field indicates the description of the device
State This field indicates the state of the device
LastOnline This fields indicates when the device was last online

Operations Performed :-

The following are the operations that can be performed on this data :-

  • Save Device: Inserts a device in the device table
  • Delete Device By ID: Deletes a device by its ID from the device table
  • Update Device Field: Updates a single field in the device table
  • Update Device Fields: Updates multiple fields in the device table
  • Query Device: Queries a device from the device table
  • Query Device All: Displays all the devices present in the device table
  • Update Device Multi: Updates multiple columns of multiple devices in the device table
  • Add Device Trans: Inserts device, device attribute and device twin in a single transaction, if any of these operations fail, then it rolls back the other insertions
  • Delete Device Trans: Deletes device, device attribute and device twin in a single transaction, if any of these operations fail, then it rolls back the other deletions

Device Attribute Table

Device attribute table contains the data regarding the device attributes associated with a particular device in the edge node. The following are the columns present in the device attribute table :

Column Name Description
ID This field indicates the id assigned to the device attribute
DeviceID This field indicates the device id of the device associated with this attribute
Name This field indicates the name of the device attribute
Description This field indicates the description of the device attribute
Value This field indicates the value of the device attribute
Optional This fields indicates whether the device attribute is optional or not
AttrType This fields indicates the type of attribute that is referred to
Metadata This fields describes the metadata associated with the device attribute

Operations Performed :-

The following are the operations that can be performed on this data :

  • Save Device Attr: Inserts a device attribute in the device attribute table
  • Delete Device Attr By ID: Deletes a device attribute by its ID from the device attribute table
  • Delete Device Attr: Deletes a device attribute from the device attribute table by filtering based on device id and device name
  • Update Device Attr Field: Updates a single field in the device attribute table
  • Update Device Attr Fields: Updates multiple fields in the device attribute table
  • Query Device Attr: Queries a device attribute from the device attribute table
  • Update Device Attr Multi: Updates multiple columns of multiple device attributes in the device attribute table
  • Delete Device Attr Trans: Inserts device attributes, deletes device attributes and updates device attributes in a single transaction.

Device Twin Table

Device twin table contains the data related to the device device twin associated with a particular device in the edge node. The following are the columns present in the device twin table :

Column Name Description
ID This field indicates the id assigned to the device twin
DeviceID This field indicates the device id of the device associated with this device twin
Name This field indicates the name of the device twin
Description This field indicates the description of the device twin
Expected This field indicates the expected value of the device
Actual This field indicates the actual value of the device
ExpectedMeta This field indicates the metadata associated with the expected value of the device
ActualMeta This field indicates the metadata associated with the actual value of the device
ExpectedVersion This field indicates the version of the expected value of the device
ActualVersion This field indicates the version of the actual value of the device
Optional This fields indicates whether the device twin is optional or not
AttrType This fields indicates the type of attribute that is referred to
Metadata This fields describes the metadata associated with the device twin

Operations Performed :-

The following are the operations that can be performed on this data :-

  • Save Device Twin: Inserts a device twin in the device twin table
  • Delete Device Twin By Device ID: Deletes a device twin by its ID from the device twin table
  • Delete Device Twin: Deletes a device twin from the device twin table by filtering based on device id and device name
  • Update Device Twin Field: Updates a single field in the device twin table
  • Update Device Twin Fields: Updates multiple fields in the device twin table
  • Query Device Twin: Queries a device twin from the device twin table
  • Update Device Twin Multi: Updates multiple columns of multiple device twins in the device twin table
  • Delete Device Twin Trans: Inserts device twins, deletes device twins and updates device twins in a single transaction.

Pre-requisites

For best understanding of the guides, it’s useful to have some knowledge of the following systems:

Setup KubeEdge

Prerequisites

To use KubeEdge, make sure you have docker in your environment, if don’t have, please reference the following steps to install docker.

Install docker

For ubuntu:

# Install Docker from Ubuntu's repositories:
apt-get update
apt-get install -y docker.io

# or install Docker CE 18.06 from Docker's repositories for Ubuntu or Debian:
apt-get update && apt-get install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"
apt-get update && apt-get install docker-ce=18.06.0~ce~3-0~ubuntu

For centOS:

# Install Docker from CentOS/RHEL repository:
yum install -y docker

# or install Docker CE 18.06 from Docker's CentOS repositories:
yum install yum-utils device-mapper-persistent-data lvm2
yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo
yum update && yum install docker-ce-18.06.1.ce

KubeEdge uses MQTT for communication between deviceTwin and devices. KubeEdge supports 3 MQTT modes:

  1. internalMqttMode: internal mqtt broker is enabled
  2. bothMqttMode: internal as well as external broker are enabled
  3. externalMqttMode: only external broker is enabled

Use mode field in edge.yaml to select the desired mode

To use kubeedge in double mqtt or external mode, make sure you have mosquitto in your environment. Please reference the following steps to install mosquitto if it is not already present in your environment.

Install mosquitto

For ubuntu:

apt install mosquitto

For centOS:

yum install mosquitto

See mosquitto official website for more information.

Build

Clone kubeedge

git clone https://github.com/kubeedge/kubeedge.git $GOPATH/src/github.com/kubeedge/kubeedge
cd $GOPATH/src/github.com/kubeedge/kubeedge
make # or `make edge_core`

Run

# run mosquitto
mosquitto -d -p 1883

# run edge_core
# `conf/` should be in the same directory as the binary
./edge_core
# or
nohup ./edge_core > edge_core.log 2>&1 &

If you are using HuaweiCloud IEF, then the edge node you created should be running (check it in the IEF console page).

Run Unit Tests

make test

To run unit tests of a package individually

export GOARCHAIUS_CONFIG_PATH=$GOPATH/src/github.com/kubeedge/kubeedge
cd <path to package to be tested>
go test -v

Try kubeedge with HuaweiCloud Intelligent EdgeFabric (IEF)

Note: The HuaweiCloud IEF is only available in China now.

  1. Create an account in HuaweiCloud.
  2. Go to IEF and create an Edge node.
  3. Download the node configuration file (<node_name>.tar.gz).
  4. Run cd $GOPATH/src/github.com/kubeedge/kubeedge/edge to enter edge directory.
  5. Run bash -x hack/setup_for_IEF.sh /PATH/TO/<node_name>.tar.gz to modify the configuration files in conf/.

MQTT Message Topics

KubeEdge uses MQTT for communication between deviceTwin and devices/apps. EventBus can be started in multiple MQTT modes and acts as an interface for sending/receiving messages on relevant MQTT topics.

The purpose of this document is to describe the topics which KubeEdge uses for communication. Please read Beehive documentation for understanding about message format used by KubeEdge.

Subscribe Topics

On starting EventBus, it subscribes to these 5 topics:

1. "$hw/events/node/+/membership/get"
2. "$hw/events/device/+/state/update"
3. "$hw/events/device/+/twin/+"
4. "$hw/events/upload/#"
5. "SYS/dis/upload_records"

If the the message is received on first 3 topics, the message is sent to deviceTwin, else the message is sent to cloud via edgeHub.

We will focus on the message expected on the first 3 topics.

  1. "$hw/events/node/+/membership/get": This topics is used to get membership details of a node i.e the devices that are associated with the node. The response of the message is published on "$hw/events/node/+/membership/get/result" topic.
  2. "$hw/events/device/+/state/update”: This topic is used to update the state of the device. + symbol can be replaced with ID of the device whose state is to be updated.
  3. "$hw/events/device/+/twin/+": The two + symbols can be replaced by the deviceID on whose twin the operation is to be performed and any one of(update,cloud_updated,get) respectively.

Following is the explanation of the three suffix used:a. update: this suffix is used to update the twin for the deviceID.b. cloud_updated: this suffix is used to sync the twin status between edge and cloud.c. get: is used to get twin status of a device. The response is published on "$hw/events/device/+/twin/get/result" topic.

Unit Test Guide

The purpose of this document is to give introduction about unit tests and to help contributors in writing unit tests.

Unit Test

Read this article for a simple introduction about unit tests and benefits of unit testing. Go has its own built-in package called testing and command called go test.For more detailed information on golang’s builtin testing package read this document.

Mocks

The object which needs to be tested may have dependencies on other objects. To confine the behavior of the object under test, replacement of the other objects by mocks that simulate the behavior of the real objects is necessary. Read this article for more information on mocks.

GoMock is a mocking framework for Go programming language. Read godoc for more information about gomock.

Mock for an interface can be automatically generated using GoMocks mockgen package.

Note There is gomock package in kubeedge vendor directory without mockgen. Please use mockgen package of tagged version v1.1.1 of GoMocks github repository to install mockgen and generate mocks. Using higher version may cause errors/panics during execution of you tests.

There is gomock package in kubeedge vendor directory without mockgen. Please use mockgen package of tagged version v1.1.1 of GoMocks github repository to install mockgen and generate mocks. Using higher version may cause errors/panics during execution of you tests.

Read this article for a short tutorial of usage of gomock and mockgen.

Ginkgo

Ginkgo is one of the most popular framework for writing tests in go.

Read godoc for more information about ginkgo.

See a sample in kubeedge where go builtin package testing and gomock is used for writing unit tests.

See a sample in kubeedge where ginkgo is used for testing.

Writing UT using GoMock

Example : metamanager/dao/meta.go

After reading the code of meta.go, we can find that there are 3 interfaces of beego which are used. They are Ormer, QuerySeter and RawSeter.

We need to create fake implementations of these interfaces so that we do not rely on the original implementation of this interface and their function calls.

Following are the steps for creating fake/mock implementation of Ormer, initializing it and replacing the original with fake.

  1. Create directory mocks/beego.
  2. use mockgen to generate fake implementation of the Ormer interface
mockgen -destination=mocks/beego/fake_ormer.go -package=beego github.com/astaxie/beego/orm Ormer

destination : where you want to create the fake implementation. package : package of the created fake implementation file github.com/astaxie/beego/orm : the package where interface definition is there Ormer : generate mocks for this interface

  1. Initialize mocks in your test file. eg meta_test.go
mockCtrl := gomock.NewController(t)
defer mockCtrl.Finish()
ormerMock = beego.NewMockOrmer(mockCtrl)
  1. ormermock is now a fake implementation of Ormer interface. We can make any function in ormermock return any value you want.
  2. replace the real Ormer implementation with this fake implementation. DBAccess is variable to type Ormer which we will replace with mock implemention
dbm.DBAccess = ormerMock
  1. If we want Insert function of ormer interface which has return types as (int64,err) to return (1 nil), it can be done in 1 line in your test file using gomock.
ormerMock.EXPECT().Insert(gomock.Any()).Return(int64(1), nil).Times(1)

Expect() : is to tell that a function of ormermock will be called.

Insert(gomock.Any()) : expect Insert to be called with any parameter.

Return(int64(1), nil) : return 1 and error nil

Times(1): expect insert to be called once and return 1 and nil only once.

So whenever insert is called, it will return 1 and nil, thus removing the dependency on external implementation.

FAQs

This page contains a few commonly occuring questions. For further support please contact us using the support page