Skip to content

Commit 2c0cfed

Browse files
wansirwansir
committed
Add demo plugin development docs
1 parent 789adc9 commit 2c0cfed

File tree

6 files changed

+211
-8
lines changed

6 files changed

+211
-8
lines changed

‎sig-architecture/concepts-and-designs/demo-plugin-zh.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# 插件开发示例
2+
3+
## 1. 部署 kubesphere v3.2.1
4+
5+
最小化[安装 KubeSphere v3.2.1](https://kubesphere.com.cn/docs/quick-start/all-in-one-on-linux/)
6+
7+
## 2. 更新 ks-apiserver 与 ks-controller-manager 的镜像
8+
9+
镜像 `docker.io/wansir/ks-apiserver:experimental`、`docker.io/wansir/ks-controller-manager:experimental` 用于验证可插拔部分的架构设计
10+
11+
代码分支 [https://github.com/wansir/kubesphere/tree/feat-pluggable](https://github.com/wansir/kubesphere/tree/feat-pluggable)
12+
13+
```
14+
kubectl -n kubesphere-system set image deploy/ks-apiserver ks-apiserver=docker.io/wansir/ks-apiserver:experimental
15+
kubectl -n kubesphere-system set image deploy/ks-controller-manager ks-controller-manager=docker.io/wansir/ks-controller-manager:experimental
16+
```
17+
18+
## 3. 对外暴露 ks-apiserver
19+
20+
在前端本地开发的过程中，依赖 ks-apiserver 提供的 API，需要将 ks-apiserver.kubesphere-system.svc 暴露给开发环境。
21+
22+
23+
## 4. clone 前端代码到本地
24+
25+
代码分支 [https://github.com/chenz24/console/tree/plugin-marketplace](https://github.com/chenz24/console/tree/plugin-marketplace) 用与验证可插拔部分的架构设计
26+
27+
```
28+
git clone https://github.com/chenz24/console.git
29+
cd console && git checkout plugin-marketplace
30+
```
31+
32+
## 5. 插件开发示例
33+
34+
前端项目开发依赖 yarn、 node12
35+
36+
### 5.1 目录结构
37+
38+
`plugins/demo` 目录下是一个简单的插件示例
39+
40+
```
41+
├── plugins # 插件目录：可包含多个插件
42+
│ ├── Dockerfile # 将插件打包为 Helm Repo 通过 Docker Image 进行分发
43+
│ ├── demo # demo 插件目录
44+
│ │ ├── Chart.yaml # 定义插件的基础信息
45+
│ │ ├── Dockerfile # 打包插件所涉及的工作负载，用于提供 API 或静态资源
46+
│ │ ├── README.md
47+
│ │ ├── charts
48+
│ │ ├── dist
49+
│ │ │ └── index.js # 通过 webpack 打包后的 js 文件
50+
│ │ ├── package-lock.json
51+
│ │ ├── package.json
52+
│ │ ├── server
53+
│ │ │ └── app.js
54+
│ │ ├── src # 插件源代码
55+
│ │ │ ├── App.jsx
56+
│ │ │ ├── index.js
57+
│ │ │ └── routes
58+
│ │ ├── templates # 定义如何部署插件
59+
│ │ │ ├── NOTES.txt
60+
│ │ │ ├── _helpers.tpl
61+
│ │ │ ├── deployment.yaml # 插件部署文件
62+
│ │ │ ├── extensions.yaml # API注册、JSBundle注册
63+
│ │ │ ├── service.yaml
64+
│ │ │ └── tests
65+
│ │ └── values.yaml
66+
│ └── entry.ts
67+
```
68+
69+
插件中(`plugins/demo/src/routes/index.js`)注册了路径为 `/demo` 的页面路由
70+
71+
```javascript
72+
import React from 'react';
73+
import App from '../App';
74+
75+
export default [
76+
{
77+
path: '/demo',
78+
element: <App />,
79+
},
80+
];
81+
```
82+
83+
一个简单的插件页面(`plugins/demo/src/App.jsx`)
84+
85+
```javascript
86+
import React from 'react';
87+
88+
export default function App() {
89+
return <h3 style={{ margin: '8rem auto', textAlign: 'center' }}>This is demo plugin</h3>;
90+
}
91+
```
92+
93+
94+
95+
### 5.2 本地预览
96+
97+
插件在开发时可以通过本地文件的方式进行加载，无需通过 ks-apiserver 进行远程加载。
98+
99+
```
100+
yarn dev
101+
```
102+
103+
访问 `http://localhost:8000/demo` 可以正常打开插件页面
104+
105+
![demo](../images/demo.png)
106+
107+
### 5.3 插件打包
108+
109+
在本地验证插件可以正常显示之后，通过 Helm 对插件进行打包。
110+
111+
```
112+
cd plugins/demo
113+
yarn build
114+
```
115+
116+
插件打包完成会在 `dist` 目录下生成 `index.js`
117+
118+
此时需要提供一个后端服务，提供打包之后 `index.js` 文件的下载路径，可以使用 nginx 或者 node 等提供一个静态资源访问地址。
119+
120+
示例中通过一个简单的 node server 提供了 `index.js` 的访问地址：`/dist/demo.kubesphere.io/v1alpha2/index.js`
121+
122+
将 `server/app.js` 与 `dist/index.js` 一起打包到一个镜像中，并创建出关联的 K8s 资源模板 `plugins/demo/templates/deployments.yaml`、`plugins/demo/templates/services.yaml`，部署该工作负载之后可以通 service 地址获取到 `index.js`
123+
124+
```bash
125+
cd plugins/demo
126+
docker build -t <REPO>:<TAG> .
127+
docker push <REPO>:<TAG> .
128+
```
129+
130+
`plugins/demo/templates/extensions.yaml` 文件中 `JSBundle` 声明了该插件以及 `index.js` 加载的路径
131+
132+
```yaml
133+
apiVersion: extensions.kubesphere.io/v1alpha1
134+
kind: JSBundle
135+
metadata:
136+
name: demo.kubesphere.io
137+
spec:
138+
rawFrom:
139+
url: http://{{ include "demo.fullname" . }}.{{ .Release.Namespace }}.svc # 部署之后的静态资源服务访问地址
140+
status:
141+
enabled: true
142+
link: /dist/demo.kubesphere.io/v1alpha2/index.js # 通过 ks-apiserver 代理之后 index.js 的加载地址（验证过程中需要手动指定，插件机制完善之后该地址会自动生成）
143+
```
144+
145+
### 5.4 插件部署
146+
147+
在完成对插件的 Helm 打包之后，可以通过以下命令在远程环境中部署该插件
148+
149+
```bash
150+
helm upgrade demo demo --create-namespace -n kubesphere-plugins --install --set image.repository=<REPO> --set image.tag=<TAG>
151+
```
152+
153+
完成安装之后可以通过一下命令来验证是否安装正确
154+
155+
```bash
156+
$ kubectl get jsbundle
157+
NAME AGE
158+
demo.kubesphere.io 7m36s
159+
$ kubectl -n kubesphere-plugins get all
160+
NAME READY STATUS RESTARTS AGE
161+
pod/demo-5cf6d76fc7-7594t 1/1 Running 0 3m54s
162+
163+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
164+
service/demo ClusterIP 10.233.18.102 <none> 80/TCP 8m2s
165+
166+
NAME READY UP-TO-DATE AVAILABLE AGE
167+
deployment.apps/demo 1/1 1 1 8m2s
168+
169+
NAME DESIRED CURRENT READY AGE
170+
replicaset.apps/demo-5cf6d76fc7 1 1 1 3m54s
171+
```
172+
173+
可以观察到 jsbundle 资源和 demo 插件依赖的 workloads 及 service 都已经正常创建
174+
175+
### 5.5 加载远程插件
176+
177+
在完成插件的部署之后， ks-console 便可以通过 ks-apiserver 提供的 API 发现需要加载的插件
178+
179+
通过一下方式可以在本地开发过程中加载远程环境中部署好的插件。
180+
181+
创建本地配置文件 `cp config/config.yaml config/local_config.yaml` 并替换 `apiServer.url` 地址为开发环境中 ks-apiserver 的地址
182+
183+
通过以下命令启动 ks-console
184+
185+
```bash
186+
yarn build:dll
187+
yarn build
188+
yarn start
189+
```
190+
191+
访问 demo 插件注册的路由地址 `http://localhost:8000/demo` 可以正常加载插件页面
192+
193+
以下日志可以追踪插件的加载过程
194+
195+
```bash
196+
Dashboard app running at port 8000
197+
<-- GET /demo 2022/03/11T18:50:57.833
198+
--> GET /demo 200 471ms 16.88kb 2022/03/11T18:50:58.303
199+
<-- GET /pstatic/dist/demo.kubesphere.io/v1alpha2/index.js 2022/03/11T18:50:58.729
200+
GET /pstatic/dist/demo.kubesphere.io/v1alpha2/index.js -> http://139.198.13.78:30881/dist/demo.kubesphere.io/v1alpha2/index.js
201+
success: GET /pstatic/dist/demo.kubesphere.io/v1alpha2/index.js -> http://139.198.13.78:30881/dist/demo.kubesphere.io/v1alpha2/index.js 200 103
202+
```
203+
204+

‎sig-architecture/concepts-and-designs/pluggable-architecture-zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ TBD
2727

2828
后端的插件化主要包含 API 的注册、静态资源的代理两个部分，可以把 ks-apiserver 看作一个可拓展的 API 网关，由 ks-apiserver 提供统一的 API 认证鉴权能力，支持动态的 API 拓展。
2929

30-
![backend](../images/backend.svg)
30+
![backend](../images/pluggable-backend.svg)
3131

3232
### Plugin Model
3333

@@ -83,7 +83,7 @@ status:
8383
8484
#### ReverseProxy
8585
86-
提供非资源型 API 的方向代理，可以用来代理一些静态的资源文件，支持路径的 Rewrite，支持请求头的注入。
86+
提供非资源型 API 的反向代理，可以用来代理一些静态的资源文件，支持路径的 Rewrite，支持请求头的注入等网关功能。
8787
8888
API 的路径会在解析插件的时候就进行检查，避免冲突。
8989

‎sig-architecture/concepts-and-designs/plugin-development-guide-zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ TBD
2727
插件开发完成之后，需要与依赖组件一起打包为 Helm Chart。
2828

2929
1. 一个插件打包为一个 Helm Chart
30-
2. 一组插件打包为 Docker Iamge 之后可以进行发布
30+
2. 一组插件打包为 Docker Image 之后可以进行发布
3131

3232
### Helm Chart 的目录结构
3333

@@ -95,7 +95,7 @@ annotations:
9595
extensions.kubesphere.io/foo: bar # 额外的注释信息
9696
```
9797
98-
### 打包为 Docker Iamge 对插件进行分发
98+
### 打包为 Docker Image 对插件进行分发
9999
100100
```dockerfile
101101
FROM baseimage # Framwork 提供的 baseimage

‎sig-architecture/images/backend.svg‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎sig-architecture/images/demo.png‎

38.2 KB
Loading

‎sig-architecture/images/pluggable-backend.svg‎

Lines changed: 3 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)