Welcome to BAETYL’s documentation!¶

Baetyl, extend cloud computing, data and service seamlessly to edge devices.

What is Baetyl¶

Baetyl is an open edge computing framework of Linux Foundation Edge that extends cloud computing, data and service seamlessly to edge devices. It can provide temporary offline, low-latency computing services include device connection, message routing, remote synchronization, function computing, video capture, AI inference, status reporting, configuration ota etc.

Baetyl v2 provides a new edge cloud integration platform, which adopts cloud management and edge operation solutions, and is divided into Edge Computing Framework and Cloud Management Suite supports varius deployment methods. It can manage all resources in the cloud, such as nodes, applications, configuration, etc., and automatically deploy applications to edge nodes to meet various edge computing scenarios. It is especially suitable for emerging strong edge devices, such as AI all-in-one machines and 5G roadside boxes.

The main differences between v2 and v1 versions are as follows:

Edge and cloud frameworks have all evolved to cloud native, and already support running on K8S or K3S.
Introduce declarative design, realize data synchronization (OTA) through shadow (Report/Desire).
The edge framework does not support native process mode currently. Since it runs on K3S, the overall resource overhead will increase.
The edge framework will support edge node clusters in the future.

Architecture¶

_images/baetyl-arch-v2.svg Architecture

Edge Computing Framework¶

The Edge Computing Framework runs on Kubernetes at the edge node, manages and deploys all applications which provide various capabilities. Applications include system applications and common applications. All system applications are officially provided by Baetyl, and you do not need to configure them.

There are currently several system applications:

baetyl-init: responsible for activating the edge node to the cloud and initializing baetyl-core, and will exit after all tasks are completed.
baetyl-core: responsible for local node management (node), data synchronization with cloud (sync) and application deployment (engine).
baetyl-function: the proxy for all function runtime services, function invocations are passed through this module.

Currently the framework supports Linux/amd64, Linux/arm64, Linux/armv7, If the resources of the edge nodes are limited, consider to use the lightweight kubernetes: K3S.

Hardware requirements scale based on the size of your applications at edge. Minimum recommendations are outlined here.

RAM: 1GB Minimum
CPU: 1 Minimum

Cloud Management Suite¶

The Cloud Management Suite is responsible for managing all resources, including nodes, applications, configuration, and deployment. The realization of all functions is plug-in, which is convenient for function expansion and third-party service access, and provides rich applications. The deployment of the cloud management suite is very flexible. It can be deployed on public clouds, private cloud environments, and common devices. It supports K8S/K3S deployment, and supports single-tenancy and multi-tenancy.

The basic functions provided by the cloud management suite in this project are as follows:

Edge node management
- Online installation of edge computing framework
- Synchronization (shadow) between edge and cloud
- Node information collection
- Node status collection
- Application status collection
Application deployment management
- Container application
- Function application
- Node matching (automatic)
Configuration management
- Common configuration
- Function configuration
- Secrets
- Certificates
- Registry credentials

_The open source version contains the RESTful API of all the above functions, but does not include the front-end dashboard. _

Contact us¶

As the first open edge computing framework in China, Baetyl aims to create a lightweight, secure, reliable and scalable edge computing community that will create a good ecological environment. In order to create a better development of Baetyl, if you have better advice about Baetyl, please contact us:

Welcome to join Baetyl’s Wechat
Welcome to join Baetyl’s LF Edge Community
Welcome to send email to baetyl@lists.lfedge.org
Welcome to submit an issue

测试环境(Chinese)¶

下面是我们部署在百度云上的测试环境，提供给大家试玩。

http://106.12.34.129:30494/

免责申明：该测试环境只用于测试目的，我们会定期升级服务和清理数据，请不要用于生产环境。

欢迎大家反馈问题，提供建议，让 Baetyl 发展的更好，查看联系方式。

边缘节点(Chinese)¶

功能简介¶

节点是边缘设备在云端的映射，云端一个节点代表一个边缘设备。通过在云端创建节点，在边缘设备完成节点安装后，就可以对边缘设备进行管理。此外，还可以在云端查看已有的节点，编辑节点的信息，删除节点。

使用说明¶

对节点的操作包括创建节点，删除节点，对节点编辑，以及安装节点。

创建节点¶

左侧菜单栏点击边缘节点，进入边缘节点页面并点击 创建节点，进入节点创建页面

_images/01-create-node-11.png 创建节点1

_images/02-create-node-21.png 创建节点2

名称: 节点名称，不可为空，不可重复
描述：描述可以为空
标签：对节点进行标识，用于关联应用，可以不绑定标签，也可以绑定多个标签
认证方式: 节点端云同步使用证书（强制）

点击确定完成节点创建后可以在节点列表看到已创建节点。

_images/03-node-list.png 节点列表

删除节点¶

在节点列表页面点击删除，弹出确定窗口

_images/04-delete-node.png 删除节点

点击确定后完成节点删除。

节点编辑¶

点击节点进入节点详情页可对节点描述信息和标签进行编辑，可以添加新的标签，修改已有标签键值，或删除已有标签。

_images/05-node-update-labels.png 编辑节点标签

节点安装¶

节点安装现仅支持在线安装。baetyl运行模式包括 k3s+docker 和 k3s+containerd 两种，在设备安装后，会检查设备上是否有docker, k3s环境，由用户选择确认进行安装。如使用 k3s+docker 模式，则需要选择安装docker后再安装k3s。设备上已有上述环境时不会再安装。如果原有k3s基于docker，baetyl运行模式为 k3s+docker，如果基于containerd，运行模式则为 k3s+containerd。

k3s+containerd模式

在节点详情页点击安装弹出窗口，复制安装命令，在设备上执行命令，当选择是否安装k3s时输入 y，选择containerd（Yes）和 docker (No)时输入 y

_images/06-node-installation-containerd-1.png 节点安装-containerd-1

_images/07-node-installation-containerd-2.png 节点安装-containerd-2

k3s+docker模式

在节点详情页点击安装弹出窗口，复制安装命令，在设备上执行命令，当选择是否安装k3s时输入 y，选择containerd（Yes）和 docker (No)时输入 n

_images/08-node-installation-docker-1.png 节点安装-docker-1

_images/09-node-installation-docker-2.png 节点安装-docker-2

采用上述两种模式安装都会在 baetyl-edge-system 部署 baetyl-core 和 baetyl-function 两个服务。查看 baetyl-edge-system 命名空间下的pod均处于运行状态即表示节点安装完成。

_images/10-node-check.png 节点检查

查看节点¶

在节点详情页可以看到节点已连接，显示了节点的详细信息与资源使用情况，这里需要手动刷新状态，默认20秒会上报一次状态，无需频繁刷新。

_images/11-node-detail-1.png 节点详情1

点击左边栏应用部署菜单可以查看已部署的应用相关信息和资源使用情况。

_images/12-node-detail-2.png 节点详情2

应用部署(Chinese)¶

名词定义¶

容器应用：由容器服务配置和数据卷配置组成的应用。
函数应用：由函数服务配置和数据卷配置组成的应用。

功能简介¶

应用是用于定义在一个或一组边缘节点上的部署任务，会将服务配置及存储卷配置下发到匹配的目标设备上，并进行部署。应用根据边缘节点的标签来匹配目标设备，每一次应用信息的更改都会自动地下发到目标设备，并进行服务重部署及配置的更新。

应用分为容器应用和函数应用。

使用流程¶

创建应用流程有两种，分别为创建容器应用流程和创建函数应用流程。

应用列表¶

应用列表分页展示出当前实例下所有的应用信息。

在实例详情页的左侧菜单中点击应用部署，您将看到如下界面

_images/01-create-app.png 01-create-app.png

右上角搜索框支持对应用名称进行模糊查询。

创建容器应用¶

基本信息¶

在应用列表页面点击创建应用进入应用创建页面。

_images/02-create-container-app.png 02-create-container-app.png

填写应用基本信息

【名称】表示应用的名称，不可为空，不可重复
【应用类型】表示应用的类型，此处选择容器应用
【描述】表示应用的文字性描述
【标签】表示用来标识应用的信息

点击添加标签进入标签设置界面，填写应用标签。

_images/03-create-container-app.png 03-create-container-app.png

服务配置¶

点击下一步进入服务配置界面。

_images/04-create-container-app-config.png 04-create-container-app-config.png

点击添加服务进入服务配置页面

_images/05-create-container-app-config.png 05-create-container-app-config.png

填写容器服务基本信息

【名称】表示服务的名称，不可为空。同一个应用中的服务名称不可重复，包含相同服务名称的不同应用部署到同一个节点会导致其中一个部署报错
【镜像地址】表示服务对应的镜像地址，不可为空。该地址应该填写在边缘节点（设备）上可以通过docker拉取的镜像地址
【卷配置】表示容器挂载的存储卷信息，支持hostPath、配置项和密文三种卷的挂载。 hostPath：挂载宿主机目录到容器目录；配置项：配置管理的配置信息；密文：配置管理里的密文信息。配置项创建在这里，密文创建在这里
【端口映射】表示容器内与宿主机的端口映射，支持TCP和UDP两种端口映射

点击添加卷进行卷配置

_images/07-create-container-app-volume.png 07-create-container-app-volume.png

点击端口映射进行端口映射配置

_images/08-create-container-app-port.png 08-create-container-app-port.png

如果还需要更多配置，点击页面最下方的 高级设置项 进入配置设置

_images/09-create-container-app-more.png 09-create-container-app-more.png

填写高级设置项

【副本数】表示服务启动的容器个数（如果配置了宿主机端口，副本数不能大于1，否则会导致端口冲突）
【环境变量】表示服务容器的环境变量
【启动参数】表示启动时服务的参数
【资源限制】表示启动服务容器的资源限制，目前支持设置CPU和内存
【host网络】表示服务容器是否使用host网络，默认使用桥接网络
【特权选项】表示是否使用特权模式挂载资源，一般在摄像头，GPU或FPGA等需要较高权限访问的特殊资源时，设置为是

至此服务配置设置完成，点击确定关闭服务配置界面。

如需要设置镜像库凭证，点击引入凭证进入引入镜像库凭证界面

_images/10-create-container-app-registry.png 10-create-container-app-registry.png

填写镜像库凭证

【镜像库凭证】表示拉取镜像时需要的凭证信息，一般用于需要凭证的镜像仓库配置，镜像仓库凭证在这里创建

目标设备¶

服务配置设置完成之后，点击下一步进入目标设备匹配界面

_images/11-create-container-app-matcher.png 11-create-container-app-matcher.png

点击匹配标签，弹出标签匹配界面

_images/12-create-container-app-kv.png 12-create-container-app-kv.png

输入想要匹配的节点标签名称及值，点击确定，会自动匹配出符合条件的节点

_images/13-create-container-app-select.png 13-create-container-app-select.png

点击创建完成应用的创建，跳转到应用列表界面，就可以看到刚才创建的应用信息了

_images/14-create-container-app-complete.png 14-create-container-app-complete.png

容器应用创建步骤到此全部完成。

创建函数应用¶

基本信息¶

在应用列表页面，点击创建应用进入应用创建页面。

_images/15-create-function-app.png 15-create-function-app.png

填写应用基本信息

【名称】表示应用的名称，不可为空，不可重复
【应用类型】表示应用的类型，此处选择函数应用
【描述】表示应用的文字性描述
【标签】表示用来标识应用的信息

点击添加标签进入标签设置界面，填写应用标签。

_images/16-create-function-app-label.png 16-create-function-app-label.png

函数服务¶

点击下一步进入函数服务界面

_images/17-create-function-app-service.png 17-create-function-app-service.png

点击添加服务进入服务配置页面

_images/18-create-function-app-service-config.png 18-create-function-app-service-config.png

填写函数服务基本信息

【名称】表示函数服务的名称，不可为空。同一个应用中的服务名称不可重复，包含相同服务名称的不同应用部署到同一个节点会导致其中一个部署报错
【函数配置项】表示选择配置管理里预先配置的函数，函数配置在这里创建
【运行时】表示需要选择的函数运行时环境，目前运行时环境支持python3，nodejs10和sql
【函数列表】表示设置函数配置项里选择的函数的函数调用入口，支持多个函数调用

如果还需要更多配置，点击页面最下方的 高级设置项 进入配置设置

填写高级设置项

【副本数】表示服务启动的容器个数
【卷配置】表示配置函数存储的容器的目录
【资源限制】表示启动服务容器的资源限制，目前支持设置CPU和内存

至此函数服务设置完成，点击确定关闭服务配置界面。

_images/19-create-function-app-service.png 19-create-function-app-service.png

目标设备¶

点击下一步进入目标设备匹配界面

_images/20-create-function-app-selector.png 20-create-function-app-selector.png

点击匹配标签，弹出标签匹配界面

_images/21-create-function-app-kv.png 21-create-function-app-kv.png

输入想要匹配的node标签名称及值，点击确定，会自动匹配出符合条件的节点

_images/22-create-function-app-select.png 22-create-function-app-select.png

点击创建完成应用的创建，跳转到应用列表界面，就可以看到刚才创建的应用信息了

_images/23-create-function-app-complete.png 23-create-function-app-complete.png

函数应用创建步骤到此全部完成。

应用修改¶

在应用列表页面，点击准备修改的应用名称 或查看，例如function-test，进入应用详情页面

_images/24-modify-app.png 24-modify-app.png

修改操作参考应用新建功能。

注意：应用修改后最新的应用配置会自动地下发到匹配的边缘节点，并进行更新。

应用删除¶

在应用列表页面，点击需要删除的应用后面的删除按钮

_images/25-delete-app.png 25-delete-app.png

应用部署¶

应用创建后，需要了解应用在边缘节点部署情况。打开应用详情页面

_images/26-deploy-app.png 26-deploy-app.png

点击目标节点里的节点名，跳转到节点详情页面，边缘节点创建在这里

_images/27-app-details.png 27-app-details.png

如果当前边缘节点没有在设备上安装，点击安装按钮，弹出在线安装命令

_images/28-app-install-cmd.png 28-app-install-cmd.png

复制在线安装框里的命令，在设备上执行。注意：需要设备已经连接网络，设备能够访问我们的云端服务，设备端安装k8s或k3s。

安装如下：

_images/29-app-start.png 29-app-start.png

期间可能需要输入用户密码。

安装完成后，可以看到应用已部署。

_images/30-app-deployed.png 30-app-deployed.png

配置管理(Chinese)¶

功能简介¶

配置是一种用于存储应用所需配置信息的资源类型，配置允许您将配置信息从应用容器镜像中解耦，从而增强应用的可移植性。配置资源可抽象成以下四类：

配置项
函数配置项
密文
镜像仓库凭证

配置项¶

配置项主要用于存储常规的配置信息，例如一组配置文件。应用将配置项以数据卷挂载的方式使用。例如，在“卷配置”中挂载配置项类型的卷，使其成为容器中的文件。对于配置项的任何更新，都会通过 Report/Desire 机制自动更新到正在使用它的容器里。配置项跟 Kubernets 中的 ConfigMap 概念类似，可参考 Kubernetes文档。

配置价值如下：

使用配置功能可以帮您管理不同环境、不同业务的配置
方便您部署相同应用的不同环境，配置文件支持多版本，方便您进行更新和回滚应用
方便您快速将您的配置以文件的形式导入到容器中

目前配置项分为普通配置项和函数配置项。函数配置项用于存储函数应用需要加载的程序脚本，支持 Python36、Nodejs10、Sql 等运行时。函数配置项通过添加函数标签来进行标识。添加函数标签后，可以在创建函数应用时选择使用。 _images/function-labels-create.png 创建函数标签.png

创建配置项¶

选择左侧导航栏 “配置管理 > 配置项 > 创建配置项”；

创建配置项.png
填写配置项信息
- 名称：配置项名称，不可为空，不可重复
- 描述：配置项描述信息，可为空
- 配置项数据: 配置项数据是键值对形式，请输入属性名和属性值。可为空
- 运行时：目前支持 Python36、Nodejs10、Sql 运行时，可为空
填写配置项信息.png

配置项挂载到应用中的服务里后，在服务对应的容器中会根据配置项的内容在挂载目录下创建文件，每条配置数据（属性名-属性值）为一个文件，其中属性名即文件的名称，属性值为文件的内容。例如某条数据的属性名为 “key”，属性值为 “value”，挂载到 /test 目录下。如果挂载成功后，在 /test 目录下就存在一个名为 “key” 的文件，其内容为 “value”。

配置项数据支持两种添加方式。

添加配置数据¶

手动添加配置数据。变量名为文件名，变量值为文件内容。

_images/config-add.png 添加配置数据.png

引入文件¶

从对象存储引入文件，通常为大容量文件。支持的对象存储类型有 “百度云对象存储服务(BOS)” 或者符合 AWSS3 接口的对象存储，例如 Minio，CEPH。

_images/file-import.png 引入文件.png

对于使用百度云 BOS 服务的用户，可以事先将需要引入的压缩包上传至 BOS，且需要位于同一个区域。然后选择对象存储类型为 “BOS”、bucket 名称、文件名称以及是否解压，并点击 “确定”。如果选择了 “解压”，该压缩包下发端侧时会进行解压操作。用户需要自行保证解压后的文件与其他配置项数据的冲突问题。

_images/object-import.png 从对象存储引入文件.png

对于外部的对象存储，可以支持符合 AWSS3 接口的对象存储，例如 Minio，CEPH。用户需要填写 endpoint、bucket名称、文件名称、是否解压等选项。如果用户不填写 AK/SK，则认为用户提供的文件具有 “公共读” 权限，并且在下发端上的时候不会进行 MD5 文件校验。

_images/object-import-awss3.png 从对象存储引入文件-awss3.png

为了保证文件在下载后的数据完整性，我们采用了 MD5 校验。在引入文件的时候支持填写 MD5 值，端侧设备在下载后将会计算文件的 MD5 值，然后与云端的 MD5 值进行比对，确保数据完整性。

查找配置项¶

选择左侧导航栏 “配置管理 > 配置项 > 搜索栏”；

_images/config-get.png 查找配置项.png

删除配置项¶

选择左侧导航栏 “配置管理 > 配置项 > 删除”；

_images/config-delete.png 删除配置项.png

函数配置项¶

函数配置项是配置项的子集，默认添加了函数标签。用于存储函数应用需要加载的程序脚本，支持 Python36、Nodejs10、Sql 等运行时。添加函数标签后，可以在创建函数应用时选择该配置项使用。

创建函数配置项¶

选择左侧导航栏 “配置管理 > 函数 > 创建函数”；

创建函数配置项.png
填写配置项信息
- 名称：配置项名称，不可为空，不可重复
- 描述：配置项描述信息，可为空
- 配置项数据: 配置项数据是键值对形式，请输入属性名和属性值。可为空
- 运行时：目前支持 Python36、Nodejs10、Sql 运行时，可为空
填写函数配置项信息.png

添加函数脚本¶

我们在本地调试好函数脚本后，可以添加到配置项数据中。

对于 Python36 运行时的函数配置项，我们可以添加一段 Python 脚本。

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

def handler(event, context):
  return "Hello world!"

对于 Nodejs10 运行时的函数配置项，我们可以添加一段 js 脚本。

#!/usr/bin/env node

exports.handler = (event, context, callback) => {
  callback(null, "Hello world");
};

对于 Sql 运行时的函数配置项，我们可以添加一段 sql 脚本。

select name as result where uid > 6

查找函数配置项¶

选择左侧导航栏 “配置管理 > 函数 > 搜索栏”；

_images/config-function-get.png 查找函数配置项.png

删除函数配置项¶

选择左侧导航栏 “配置管理 > 函数 > 删除”；

_images/config-function-delete.png 删除函数配置项.png

密文¶

密文用于存储敏感数据，例如密码，令牌或密钥。它们可能包含一个或多个键值对。与添加配置项一样，应用服务将密文以数据卷挂载的方式使用。例如，在“卷配置”中挂载密文类型的卷，使其成为容器中的文件。对于密文的任何更新，都会自动更新到使用他的容器中。密文跟 Kubernets 中的 Secret 概念类似，可参考 Kubernetes文档。

创建密文¶

选择左侧导航栏 “配置管理 > 密文 > 创建密文”；

创建密文.png
填写密文信息
- 名称：密文名称，不可为空，不可重复
- 描述：密文描述信息，可为空
- 密文数据: 密文数据是键值对形式，请输入属性名和属性值。可为空
填写密文.png

查找密文¶

选择左侧导航栏 “配置管理 > 密文 > 搜索栏”；

_images/secret-get.png 查找密文.png

删除密文¶

选择左侧导航栏 “配置管理 > 密文 > 删除”；

_images/secret-delete.png 删除密文.png

仓库镜像凭证¶

镜像库凭证是用于向私有 Docker 镜像库进行身份验证的凭据。资源创建完成后，可在添加应用时选择 “镜像库凭证” 引入凭证。镜像库凭证本质上也是一个 Kubernets Secret，可参考 Kubernetes文档。

创建凭证¶

选择左侧导航栏 “配置管理 > 镜像仓库凭证 > 创建凭证”；

创建凭证.png
填写凭证信息。
- 名称：凭证名称，不可为空，不可重复
- 描述：凭证描述信息，可以为空
- 凭证数据: 私有 Docker 镜像库登录信息，分别为镜像地址、用户名、密码
填写凭证信息.png

查找凭证¶

选择左侧导航栏 “配置管理 > 镜像仓库凭证 > 搜索栏”。

_images/registry-get.png 查找凭证.png

重设密码¶

对于已创建的凭证，可以重设凭证数据中的密码。更新后的密码都会通过 Report/Desire 机制自动更新到正在使用它的容器里。

_images/password-reset.png 重设密码.png

删除凭证¶

选择左侧导航栏 “配置管理 > 镜像仓库凭证 > 删除”；

_images/registry-delete.png 删除凭证.png

Practice of Application Deployment¶

To create applications through the cloud and deploy them to edge devices, operations such as node creation, node installation, application creation and application node matching should be completed. Node installation can be completed before or after the application creation and node matching. Application and node matching is achieved by configuring the application with the same “match label” specified by selector field as the node label (note that it is not the same as the application label). In this way, an application can be matched to more than one node, and a node can be associated with more than one application. The cloud monitors the target node based on the “match label” and performs application deployment for all nodes that meet the matching criteria. Multiple labels matching is also supported with “and” relationships between multiple labels. Applications are divided into container applications and function applications. Take container applications as an example, an application contains service configuration, data volume, mirror repository credentials, matching node labels, etc. An application may contain multiple services, but it is recommended that an application contain only one service. A service needs to configure the port, the number of copies, etc. In addition, it may also need to manage the configuration files and related data used by the service. We will deploy a Mosquitto Broker app at the edge device, which contains a Broker’s service, configuration used by application, matches labels, and more.

Create Node¶

Open Postman, then set Content-type to application/json in Headers. Add node name,description and labels to the body. Please note the labels node=node-1 since it will be used later in application creation. Cloud service address is provided in test environment. api/iot2/baetyl is used as the prefix. Refer to OpenAPI Node Management/Create Node for detail usage information. In here，address is https://106.12.34.129:30494/api/iot2/baetyl/v1/nodes. Choose POST method and the body to send is shown as below

{
    "name":"node-1",
    "description": "test node-1",
    "labels":{
        "node":"node-1"
    }
}

_images/01-create-node-1.png create node 1

Click Send to view the returned result and confirm that the node has been successfully created.

_images/02-create-node-2.png create node 2

Create Configuration¶

broker configuration

Start by creating the configuration used by application. The configuration data contains multiple key-value pairs. The key is the file name and the value is the file content used when the service is loaded. In here, data key is mosquitto.conf. data value (file content) is shown as below. Refer to mosquitto config for more information. It mainly sets 1883 port to expose, data storage path and so on.

port 1883
autosave_interval 180
autosave_on_changes true
persistence true
persistence_file mosquitto.db
persistence_location /mosquitto/data/
log_type all
connection_messages true
log_dest file /mosquitto/log/mosquitto.log
allow_anonymous true

Set Content-type to application/json in Headers then choose POST method. Body to send is shown as below

{
    "name": "broker-conf-1",
    "description": "broker conf",
    "data": [
                {
                    "key": "mosquitto.conf",
                    "value": {
                        "type": "kv",
                        "value": "port 1883\nautosave_interval 180\nautosave_on_changes true\npersistence true\npersistence_file mosquitto.db\npersistence_location /mosquitto/data/\nlog_type all\nconnection_messages true\nlog_dest file /mosquitto/log/mosquitto.log\nallow_anonymous true"
                    }
                }
            ]
}

Address is http://106.12.34.129:30494/api/iot2/baetyl/v1/configs. Refer to OpenAPI Configuration Management/Create Configuration for detail usage information.

_images/03-create-conf-1.png broker config

Click Send to view the returned results and confirm that the configuration has been successfully created. Besides, please record the name of the configuration and the version information returned, which is needed to create the application.

_images/04-create-conf-2.png configuration list

Create Application¶

There are several important parts to creating an application. The first is the information about the application itself, including the application name, the ports involved in the application, boot parameters and other informations. The second is the configuration used by the application, image repository credentials, and so on. The third matching labels. By configuring matching label that are the same as the expected deployment node, the application can be matched with the node, so as to achieve the goal of deploying the application to the expected edge device.

Set Content-type to application/json in Headers and choose POST method, body to send is shown as below. Please note the selector field which is same as the node labels previously.

{
  "name": "broker-1",
  "selector": "node=node-1",
  "description": "mosquitto broker",
  "services": [
    {
      "name":"broker",
      "image":"eclipse-mosquitto:1.6.9",
      "replica":1,
      "volumeMounts": [
        {
          "name": "conf",
          "mountPath": "/mosquitto/config",
          "readOnly": true
        }
      ],
      "ports": [
        {
          "hostPort": 1883,
          "containerPort": 1883,
          "protocol": "TCP"
        }
      ]
    }
  ],
  "volumes": [
    {
      "name": "conf",
      "config": {
        "name": "broker-conf-1",
        "version": "17966929"
      }
    }
  ]
}

The version of the configuration refered by volumes[0].config.version in the body needs to be modified based on the version returned in the previous step. Address is http://106.12.34.129:30494/api/iot2/baetyl/v1/apps. Refer to Application Management/Create Application for details.

_images/05-create-app-1.png create app 1

Click Send to view the returned result to verify that application has been successfully created. _images/06-create-app-2.png create app 2

Node Installation¶

Acquiring installation command is prerequisite for node installation. Set Content-type to applicaiton/json in Headers and choose GET method. The Address is http://106.12.34.129:30494/api/iot2/baetyl/v1/nodes/node-1/init, Refer to Node Management/Node Installation for details.

Click Send to get the result and copy it to your device and execute then.

_images/07-node-installation-1.png node installation 1

Since baetyl is based on k3s/k8s, when initialized, if k3s/k8s not installed on the device, you need to select the relevant components to install. There are k3s+containerd and k3s+docker two modes. After executing the command, you will be prompted to install k3s. You need to enter y to confirm the installation of k3s. Then you need to choose whether to install Containerd or Docker. Containerd will be installed if you type y and the mode of baetyl will be k3s+containerd, if you type n, then docker will be installed thus mode of baetyl is k3s+docker.

_images/08-node-installation-2.png node installation 2

_images/09-node-installation-3.png node installation 3

Check that the system application service is up and running. System application are in baetyl-edge-system namespace，including baetyl-core and baetyl-function two deployments，user applications are in baetyl-edge namespace. Confirming that the broker application in baetyl-edge namespace created previously is in Running status, indicating that the application has started normally.

_images/10-node-installation-4.png node installation 4

To get the device stats, query device stats interface /v1/nodes/:name/stats. Set request address to http://106.12.34.129:30494/api/iot2/baetyl/v1/nodes/node-1/stats and choose GET method. Click Send to get the device stats. Device hardware and resource status are included in returned response. “ready” field means that the edge device is connected to the cloud.

_images/11-query-node-stats-1.png node detail 1

In addition, the return result contains the stats of all applications, and you can see that the status of user application Broker previously deployed is Running.

_images/12-query-node-stats-2.png node detail 2

Connect to edge devices using MQTTBox clients. The exposed port of the deployed MQTT Broker is 1883 and the subscribed topics are not restricted. Subscribe to the test topic and send a message to verify that the message is received, indicating that the MQTT Broker is up and running.

_images/13-application-test.png application test

Installation¶

Preparation¶

Install k8s or k3s. For the introduction of k8s, please refer to kubernetes official website.

Statement¶

The k8s related informations used in this article are as follows:

// kubectl version
Client Version: version.Info{Major:"1", Minor:"17", GitVersion:"v1.17.3", GitCommit:"06ad960bfd03b39c8310aaf92d1e7c12ce618213", GitTreeState:"clean", BuildDate:"2020-02-11T18:14:22Z", GoVersion:"go1.13.6", Compiler:"gc", Platform:"darwin/amd64"}
Server Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.5", GitCommit:"20c265fef0741dd71a66480e35bd69f18351daea", GitTreeState:"clean", BuildDate:"2019-10-15T19:07:57Z", GoVersion:"go1.12.10", Compiler:"gc", Platform:"linux/amd64"}

The baetyl-cloud related informations used in this article are as follows:

// git log
commit 6d96271e24dbd4d5bb5f3e0509c2af7d085676af
Author: chensheng <chensheng06@baidu.com>
Date:   Tue Aug 11 15:54:26 2020 +0800

    fix cert error (#50)

Because the baetyl-cloud code is rapidly iterating, the latest code cannot be adapted in real time. So users need to switch to this version after downloading the baetyl-cloud code:

git reset --hard 6d96271e24dbd4

In addition, this article will be updated regularly to adapt to the latest baetyl-cloud code.

Helm Quick Installation¶

This article supports using helm v2/v3 for installation. The relevant version information during testing is as follows:

// helm v3: helm version
version.BuildInfo{Version:"v3.2.3", GitCommit:"8f832046e258e2cb800894579b1b3b50c2d83492", GitTreeState:"clean", GoVersion:"go1.13.12"}

// helm v2: helm version
Client: &version.Version{SemVer:"v2.16.9", GitCommit:"8ad7037828e5a0fca1009dabe290130da6368e39", GitTreeState:"clean"}
Server: &version.Version{SemVer:"v2.16.9", GitCommit:"8ad7037828e5a0fca1009dabe290130da6368e39", GitTreeState:"clean"}

For the installation of helm, please refer to helm installation link.

1. Install database¶

Before installing baetyl-cloud, we need to install the database first, and execute the following command to install it.

// helm v3
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install mariadb --set rootUser.password=secretpassword,db.name=baetyl_cloud bitnami/mariadb
helm install phpmyadmin bitnami/phpmyadmin 

// helm v2
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install --name mariadb --set rootUser.password=secretpassword,db.name=baetyl_cloud bitnami/mariadb
helm install --name phpmyadmin bitnami/phpmyadmin 

Note: For the convenience of demonstration, we have hardcoded the password, please modify it yourself, and you can replace secretpassword globally.

2. Initialize data¶

Confirm that mariadb and phpmyadmin are in the Running state.

kubectl get pod
# NAME                            READY   STATUS             RESTARTS   AGE
# mariadb-master-0                1/1     Running            0          2m56s
# mariadb-slave-0                 1/1     Running            0          2m56s
# phpmyadmin-55f4f964d7-ctmxj     1/1     Running            0          117s

Then execute the following command to keep the terminal from exiting.

export POD_NAME=$(kubectl get pods --namespace default -l "app=phpmyadmin,release=phpmyadmin" -o jsonpath="{.items[0].metadata.name}")
echo "phpMyAdmin URL: http://127.0.0.1:8080"
kubectl port-forward --namespace default svc/phpmyadmin 8080:80

Then use a browser to open http://127.0.0.1:8080/index.php, Server input: mariadb, Username input: root, Password input: secretpassword. After logging in, select the database baetyl_cloud, click the SQL button, and enter tables.sql and data.sql in the scripts/sql directory under the baetyl-cloud project into the page for execution. If no error is reported during execution, the data initialization is successful. If you have installed before, please pay attention to delete the historical data under the baetyl-cloud database when installing again.

3. Install baetyl-cloud¶

For helm v3, enter the directory where the baetyl-cloud project is located and execute the following commands.

# helm v3
helm install baetyl-cloud ./scripts/charts/baetyl-cloud/

For helm v2, users need to do some additional operations in the above directories:

Modify the apiVersion version in ./scripts/charts/baetyl-cloud/Chart.yaml from v2 to v1 and save it as follows:

apiVersion: v1
name: baetyl-cloud
description: A Helm chart for Kubernetes

...

Import crds manually:

# k8s version is v1.16 or higher 
# k3s version is v1.17.4 or higher
kubectl apply -f ./scripts/charts/baetyl-cloud/apply/
# k8s version less than v1.16
# k3s version less than v1.17.4
kubectl apply -f ./scripts/charts/baetyl-cloud/apply_v1beta1/

use helm v2 to install baetyl-cloud:

# helm v2
helm install --name baetyl-cloud ./scripts/charts/baetyl-cloud/

To make sure that baetyl-cloud is in the Running state, and you can also check the log for errors.

kubectl get pod
# NAME                            READY   STATUS    RESTARTS   AGE
# baetyl-cloud-57cd9597bd-z62kb   1/1     Running   0          97s

kubectl logs -f baetyl-cloud-57cd9597bd-z62kb

4. Install edge node¶

Call the RESTful API to create a node.

curl -d "{\"name\":\"demo-node\"}" -H "Content-Type: application/json" -X POST http://0.0.0.0:30004/v1/nodes
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1931564","createTime":"2020-07-22T06:25:05Z","labels":{"baetyl-node-name":"demo-node"},"ready":false}

Obtain the online installation script of the edge node.

curl http://0.0.0.0:30004/v1/nodes/demo-node/init
# {"cmd":"curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh"}

Execute the installation script on the machine where baetyl-cloud is deployed.

curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh

Note: If you need to install an edge node on a device other than the machine where baetyl-cloud is deployed, please modify the database, change the node-address and active-address in the baetyl_system_config table to real addresses.

Check the status of the edge node. Eventually, two edge services will be in the Running state. You can also call the cloud RESTful API to view the edge node status. You can see that the edge node is online (“ready”:true).

kubectl get pod -A
# NAMESPACE            NAME                                      READY   STATUS    RESTARTS   AGE
# baetyl-edge-system   baetyl-core-8668765797-4kt7r              1/1     Running   0          2m15s
# baetyl-edge-system   baetyl-function-5c5748957-nhn88           1/1     Running   0          114s

curl http://0.0.0.0:30004/v1/nodes/demo-node
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1939112",...,"report":{"time":"2020-07-22T07:25:27.495362661Z","sysapps":...,"node":...,"nodestats":...,"ready":true}

5. Uninstall baetyl-cloud¶

helm delete baetyl-cloud

K8S Installation¶

1. Install database¶

Install mysql database, and initialize the data as follows:

Create ‘baetyl_cloud’ database and tables, see specific sql statements in: scripts/sql/tables.sql

Initialize table data, see specific sql setatements in: scripts/sql/data.sql

# Note: modify the node-address and active-address in baetyl_system_config to real server address：
# For example, if the service is deployed locally, the address can be configured as follows：
# node-address : https://0.0.0.0:30005
# active-address : https://0.0.0.0:30003
# If the service is deployed on a non-local machine, please change IP to real server IP

Modify the database configuration in baetyl-cloud-configmap.yml

2. Install baetyl-cloud¶

cd scripts/k8s
# k8s version is v1.16 or higher 
# k3s version is v1.17.4 or higher
kubectl apply -f ./apply/
# k8s version less than v1.16
# k3s version less than v1.17.4
kubectl apply -f ./apply_v1beta1/

After the execution is successful, you can execute kubectl get pods |grep baetyl-cloud command to check the program running status, and then you can operate the baetyl-cloud API via http://0.0.0.0:30004.

3. Install edge node¶

Call the RESTful API to create a node.

curl -d "{\"name\":\"demo-node\"}" -H "Content-Type: application/json" -X POST http://0.0.0.0:30004/v1/nodes
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1931564","createTime":"2020-07-22T06:25:05Z","labels":{"baetyl-node-name":"demo-node"},"ready":false}

Obtain the online installation script of the edge node.

curl http://0.0.0.0:30004/v1/nodes/demo-node/init
# {"cmd":"curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh"}

Execute the installation script on the machine where baetyl-cloud is deployed.

curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh

Note: If you need to install an edge node on a device other than the machine where baetyl-cloud is deployed, please modify the database, change the node-address and active-address in the baetyl_system_config table to real addresses.

Check the status of the edge node. Eventually, two edge services will be in the Running state. You can also call the cloud RESTful API to view the edge node status. You can see that the edge node is online (“ready”:true).

kubectl get pod -A
# NAMESPACE            NAME                                      READY   STATUS    RESTARTS   AGE
# baetyl-edge-system   baetyl-core-8668765797-4kt7r              1/1     Running   0          2m15s
# baetyl-edge-system   baetyl-function-5c5748957-nhn88           1/1     Running   0          114s

curl http://0.0.0.0:30004/v1/nodes/demo-node
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1939112",...,"report":{"time":"2020-07-22T07:25:27.495362661Z","sysapps":...,"node":...,"nodestats":...,"ready":true}

4. Uninstall baetyl-cloud¶

cd scripts/k8s
# k8s version is v1.16 or higher 
# k3s version is v1.17.4 or higher
kubectl delete -f ./apply/
# k8s version less than v1.16
# k3s version less than v1.17.4
kubectl delete -f ./apply_v1beta1/

Process installation¶

1. Install database¶

Install mysql database, and initialize the data as follows:

Create ‘baetyl_cloud’ database and tables, see specific sql statement in: scripts/sql/tables.sql

Initialize table data, see specific sql statement in : scripts/sql/data.sql

# Note: modify the node-address and active-address in baetyl_system_config to real server address：
# For example, if the service is deployed locally, the address can be configured as follows：
# node-address : https://0.0.0.0:30005
# active-address : https://0.0.0.0:30003
# If the service is deployed on a non-local machine, please change IP to real server IP

Modify the database configuration in conf/cloud.yml

2. Source code compilation¶

Refer Source code compilation

3. Install baetyl-cloud¶

# Import k8s crd resources
cd scripts/native

# k8s version is v1.16 or higher 
# k3s version is v1.17.4 or higher
kubectl apply -f ./apply/
# k8s version less than v1.16
# k3s version less than v1.17.4
kubectl apply -f ./apply_v1beta1/

# Execute the following command, replace example in the conf/kubeconfig.yml file
kubectl config view --raw
# Execute the following command
nohup ../../../output/baetyl-cloud -c ./conf/cloud.yml > /dev/null &
# After successful execution, it will return the successfully established baetyl-cloud process number

After successful execution, you can operate baetyl-cloud API via http://0.0.0.0:9004.

4. Install edge node¶

Call the RESTful API to create a node.

curl -d "{\"name\":\"demo-node\"}" -H "Content-Type: application/json" -X POST http://0.0.0.0:30004/v1/nodes
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1931564","createTime":"2020-07-22T06:25:05Z","labels":{"baetyl-node-name":"demo-node"},"ready":false}

Obtain the online installation script of the edge node.

curl http://0.0.0.0:30004/v1/nodes/demo-node/init
# {"cmd":"curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh"}

Execute the installation script on the machine where baetyl-cloud is deployed.

curl -skfL 'https://0.0.0.0:30003/v1/active/setup.sh?token=f6d21baa9b7b2265223a333630302c226b223a226e6f6465222c226e223a2264656d6f2d6e6f6465222c226e73223a2262616574796c2d636c6f7564222c227473223a313539353430323132367d' -osetup.sh && sh setup.sh

Note: If you need to install an edge node on a device other than the machine where baetyl-cloud is deployed, please modify the database, change the node-address and active-address in the baetyl_system_config table to real addresses.

Check the status of the edge node. Eventually, two edge services will be in the Running state. You can also call the cloud RESTful API to view the edge node status. You can see that the edge node is online (“ready”:true).

kubectl get pod -A
# NAMESPACE            NAME                                      READY   STATUS    RESTARTS   AGE
# baetyl-edge-system   baetyl-core-8668765797-4kt7r              1/1     Running   0          2m15s
# baetyl-edge-system   baetyl-function-5c5748957-nhn88           1/1     Running   0          114s

curl http://0.0.0.0:30004/v1/nodes/demo-node
# {"namespace":"baetyl-cloud","name":"demo-node","version":"1939112",...,"report":{"time":"2020-07-22T07:25:27.495362661Z","sysapps":...,"node":...,"nodestats":...,"ready":true}

5. Uninstall baetyl-cloud¶

# Kill the process according to the process number when the creation is successful:
sudo kill process number

Configuration Interpretation¶

baetyl-cloud configuration¶

The default configuration file is etc/baetyl/service.yml in the working directory, and the configuration definition is as follows:

adminServer:
  port: #The management server port

nodeServer:
  port: #The server port for edge-cloud synchronization
  ca: #The server root ca certificate file
  cert: #The server certificate file
  key: #The Server certificate's key file

activeServer:
  port: #The server port for device activate
  ca: #The server root ca certificate file
  cert: #The server certificate file
  key: #The Server certificate's key file

plugin: #In baetyl-cloud design, auth, lincese, pki, shadow, and model storage are implemented in the form of plug-ins, supporting customization
  auth: #Authentication plugin, defaultauth is used by default, no authentication
  license: #license plugin, defaultlicense is used by default, no license check.
  pki: #Certificate management plugin, defaultpki is used by default, self-signed certificate.
  shadow: #Shadow storage plugin, database is used by default.
  modelStorage: #CRD storage plugin, kubernetes  is used by default.
  databaseStorage: #Database configuration, database  is used by default.

logger:
  filename: #Log file 
  level: #Log level

kubernetes:
  inCluster: #Whether to use k8s cluster configuration, true is used, false is not used
  configPath: #When inCluster is false, configure the k8s configuration file

database:
  type: #Which Database to be chosed, such as mysql, sqlite3, etc.
  url: #The database connection url

defaultpki:
  rootCAFile: #Root certificate path, used to issue the root certificate of the connection certificate between the node and the cloud,
  rootCAKeyFile: #Root certificate key file path, used to sign the key file of the connection certificate between the node and the cloud
  persistent:
    kind: #Storage type Default database: database
    database:
      type: #Which Database to be used, like mysql, sqlite3, etc.
      url: #The database connection url
      
defaultauth:
  namespace: #The namespace for baetyl-cloud, default is baetyl-cloud
  keyFile: # The secret key file, sign the token for the node installation script

Open API¶

See Open API

Install from source¶

quick installation of baetyl-cloud, you can build baetyl-cloud from source to get the latest features.

Prerequisites¶

The Go tools and modules

The minimum required go version is 1.13. Refer to golang.org or golang.google.cn to download and install the Go tools. Now we use Go Modules to manage packages，you can refer goproxy.baidu.com to set GOPROXY if needs.

The Docker Engine and Buildx

The minimum required Docker version is 19.03, because the Docker Buildx feature is introduced to build multi-platform images. Refer to docker.com/installto install the Docker Engine and refer to github.com/docker/buildx to enable the Docker Buildx.

Download source code¶

Download the code from Baetyl Github and execute the following command:

git clone https://github.com/baetyl/baetyl-cloud.git

Build baetyl-cloud¶

Go into the baetyl-cloud project directory and execute make to build the baetyl-cloud main program.

make

After the make command is completed, the baetyl-cloud main program will be generated in the project’s output directory.

Make image¶

If you use container mode to run baetyl-cloud, we recommend using officially released official images. If you want to make your own image, you can use the commands provided below, but only if the Buildx function mentioned in the first preparation is turned on.

Go into the baetyl-cloud project directory and execute make image to generate baetyl-cloud image.

make image

After the command is completed, you can execute docker images to view the generated image.

docker images

REPOSITORY    TAG          IMAGE ID         CREATED SIZE
cloud       git-be2c5a9   d70a7faf5443    About an hour ago 40.7MB

Modify the image configuration in scripts/demo/charts/baetyl-cloud/values.yaml, and use helm install command to deploy baetyl-cloud.

FAQ¶

None