Chore: Add the guide for the plugin developer (#780)

Signed-off-by: barnettZQG <barnett.zqg@gmail.com>
kubevela · Apr 18, 2023 · cff8c89 · cff8c89
1 parent 47f2313
commit cff8c89
Show file tree

Hide file tree

Showing 9 changed files with 337 additions and 4 deletions.
diff --git a/addon/metadata.yaml b/addon/metadata.yaml
@@ -1,5 +1,5 @@
 name: velaux
-version: v1.8.0-rc.1
+version: v1.8.0-rc.3
 description: KubeVela User Experience (UX). An extensible, application-oriented delivery and management Platform.
 icon: https://static.kubevela.net/images/logos/KubeVela%20-03.png
 url: https://kubevela.io

diff --git a/addon/resources/server.cue b/addon/resources/server.cue
@@ -52,7 +52,7 @@ _httpsTrait: *[ if parameter["secretName"] != _|_ && parameter["domain"] != _|_
 	}}] | []
 
 server: {
-	name: "server"
+	name: "velaux-server"
 	type: "webservice"
 	properties: {
 		if parameter["repo"] == _|_ {
@@ -71,7 +71,7 @@ server: {
 			exposeType: parameter["serviceType"]
 		}
 
-		cmd: ["server", "--datastore-type=" + parameter["dbType"]] + database + dbURL + enableImpersonation
+		cmd: ["server", "--datastore-type=" + parameter["dbType"], "--feature-gates=EnableCacheJSFile=true"] + database + dbURL + enableImpersonation
 		ports: [
 			{
 				port:     8000

diff --git a/docs/contributing/how-to-build-plugin.md b/docs/contributing/how-to-build-plugin.md
@@ -0,0 +1,107 @@
+# How to build a plugin
+
+VelUX plugin could help you customs any page applications. Most default and extensional runtime APIs make you develop the application easies.
+
+## 1. Build the local server environment.
+
+Refer [contributing](./docs/contributing/velaux.md) guide.
+
+## 2. Initialize the plugin project.
+
+```bash
+mkdir custom-plugins
+$pluginName=<your_plugin_name>
+git clone https://github.com/kubevela-contrib/velaux-plugin-template custom-plugins/$pluginName
+
+cd custom-plugins/$pluginName
+```
+
+## 3. Edit the plugin metadata.
+
+* src/plugin.json: Plugin metadata, you should change it.
+* package.json: Project metadata, you should change the project name, version, and description etc.
+
+Plugin metadata spec:
+
+```cue
+{
+  "type": "page-app",
+  "name": string,
+  "id": string,
+  "info": {
+    "keywords": []string,
+    "description": string,
+    "author": {
+      "name": string
+    },
+    "logos": {
+      "small": string,
+      "large": string
+    },
+    "screenshots": [],
+    "version": string,
+    "updated": string
+  },
+  "backend"?: bool,
+  "proxy"?: bool,
+  "backendType?": "kube-api" | "kube-service",
+  "routes"?: [
+    {
+      "path": string,
+      "permission": {
+        "resource": string,
+        "action": string
+      }
+    }
+  ],
+  "backendService"?: {
+    "name": string
+    "namespace"?: string
+  },
+  "kubePermissions"?: [
+    {
+      "apiGroups": string[],
+      "resources": string[],
+      "verbs": string[],
+    }
+  ]
+}
+```
+
+There are some example plugin configs. https://github.com/kubevela/velaux/tree/main/docs/plugins
+
+## 4. Develop the plugin
+
+```bash
+yarn install
+yarn dev
+```
+
+### Request the backend API
+
+```js
+import { getBackendSrv } from '@velaux/ui';
+
+// Request the core APIs
+getBackendSrv().get('/api/v1/clusters').then(res=>{console.log(res)})
+
+// Request the plugin proxy APIs
+getBackendSrv().get(`/proxy/plugins/${pluginID}/${realPath}`).then(res=>{console.log(res)})
+
+```
+
+Core API Reference: https://kubevela.net/docs/platform-engineers/openapi/overview
+
+### UI Components
+
+```js
+import { Table, Form } from '@velaux/ui';
+```
+
+UI Component Reference: https://fusion.design/pc/component/box?themeid=2
+
+## 5. Start the server to debug the plugin
+
+```bash
+go run ./cmd/server/main.go --plugin-path <custom-plugins-path>
+```
diff --git a/docs/contributing/velaux.md b/docs/contributing/velaux.md
@@ -111,7 +111,11 @@ Add following config in `settings.json`
 }
 ```
 
+## Develop the plugin
+
+Reference: [How to build a plugin](./how-to-build-plugin)
+
 ## References
 
 * UI framework: [@alifd/next](https://fusion.design/)
-* Icons: [react-icons](https://react-icons.github.io/react-icons)
+* Icons: [react-icons](https://react-icons.github.io/react-icons)
diff --git a/docs/plugins/backend-kube-api-allow-route/plugin.json b/docs/plugins/backend-kube-api-allow-route/plugin.json
@@ -0,0 +1,52 @@
+{
+  "type": "page-app",
+  "name": "Backend Kube API Allow Route",
+  "id": "backend-kube-api-allow-route",
+  "info": {
+    "keywords": [
+      "app"
+    ],
+    "description": "The app demo plugin",
+    "author": {
+      "name": "KubeVela"
+    },
+    "logos": {
+      "small": "img/logo.svg",
+      "large": "img/logo.svg"
+    },
+    "screenshots": [],
+    "version": "0.0.1",
+    "updated": "2023-03-30"
+  },
+  "backend": true,
+  "proxy": true,
+  "backendType": "kube-api",
+  "kubePermissions": [
+    {
+      "apiGroups": [
+        ""
+      ],
+      "resources": [
+        "nodes",
+        "nodes/status"
+      ],
+      "verbs": [
+        "get",
+        "list"
+      ]
+    }
+  ],
+  "routes": [
+    {
+      "path": "/api/v1/nodes",
+      "permission": {
+        "resource": "node",
+        "action": "detail"
+      }
+    }
+  ],
+  "dependencies": {
+    "velauxDependency": ">=1.8.0",
+    "plugins": []
+  }
+}
diff --git a/docs/plugins/backend-kube-api-node/plugin.json b/docs/plugins/backend-kube-api-node/plugin.json
@@ -0,0 +1,55 @@
+{
+  "type": "page-app",
+  "name": "Backend Kube API",
+  "id": "backend-kube-api-node",
+  "info": {
+    "keywords": [
+      "app"
+    ],
+    "description": "The app demo plugin",
+    "author": {
+      "name": "KubeVela"
+    },
+    "logos": {
+      "small": "img/logo.svg",
+      "large": "img/logo.svg"
+    },
+    "screenshots": [],
+    "version": "0.0.1",
+    "updated": "2023-03-30"
+  },
+  "backend": true,
+  "proxy": true,
+  "backendType": "kube-api",
+  "routes": [
+    {
+      "path": "/nodes/:node",
+      "method": "GET",
+      "proxyHeaders": [
+        {
+          "name": "Authorization",
+          "value": "Bearer test"
+        }
+      ]
+    }
+  ],
+  "kubePermissions": [
+    {
+      "apiGroups": [
+        ""
+      ],
+      "resources": [
+        "nodes",
+        "nodes/status"
+      ],
+      "verbs": [
+        "get",
+        "list"
+      ]
+    }
+  ],
+  "dependencies": {
+    "velauxDependency": ">=1.8.0",
+    "plugins": []
+  }
+}
diff --git a/docs/plugins/backend-kube-api/plugin.json b/docs/plugins/backend-kube-api/plugin.json
@@ -0,0 +1,43 @@
+{
+  "type": "page-app",
+  "name": "Backend Kube API",
+  "id": "backend-kube-api",
+  "info": {
+    "keywords": [
+      "app"
+    ],
+    "description": "The app demo plugin",
+    "author": {
+      "name": "KubeVela"
+    },
+    "logos": {
+      "small": "img/logo.svg",
+      "large": "img/logo.svg"
+    },
+    "screenshots": [],
+    "version": "0.0.1",
+    "updated": "2023-03-30"
+  },
+  "backend": true,
+  "proxy": true,
+  "backendType": "kube-api",
+  "kubePermissions": [
+    {
+      "apiGroups": [
+        ""
+      ],
+      "resources": [
+        "nodes",
+        "nodes/status"
+      ],
+      "verbs": [
+        "get",
+        "list"
+      ]
+    }
+  ],
+  "dependencies": {
+    "velauxDependency": ">=1.8.0",
+    "plugins": []
+  }
+}
diff --git a/docs/plugins/backend-kube-service/plugin.json b/docs/plugins/backend-kube-service/plugin.json
@@ -0,0 +1,31 @@
+{
+  "type": "page-app",
+  "name": "Backend Kube Service",
+  "id": "backend-kube-service",
+  "info": {
+    "keywords": [
+      "app"
+    ],
+    "description": "The app demo plugin",
+    "author": {
+      "name": "KubeVela"
+    },
+    "logos": {
+      "small": "img/logo.svg",
+      "large": "img/logo.svg"
+    },
+    "screenshots": [],
+    "version": "0.0.1",
+    "updated": "2023-03-30"
+  },
+  "backend": true,
+  "proxy": true,
+  "backendType": "kube-service",
+  "backendService": {
+    "name": "test"
+  },
+  "dependencies": {
+    "velauxDependency": ">=1.8.0",
+    "plugins": []
+  }
+}
diff --git a/docs/plugins/frontend/plugin.json b/docs/plugins/frontend/plugin.json
@@ -0,0 +1,41 @@
+{
+  "type": "page-app",
+  "name": "Frontend",
+  "id": "frontend",
+  "info": {
+    "keywords": [
+      "app"
+    ],
+    "description": "The app demo plugin",
+    "author": {
+      "name": "KubeVela"
+    },
+    "logos": {
+      "small": "img/logo.svg",
+      "large": "img/logo.svg"
+    },
+    "screenshots": [],
+    "version": "0.0.1",
+    "updated": "2023-03-30"
+  },
+  "includes": [
+    {
+      "workspace": {
+        "name": "continuous-delivery"
+      },
+      "type": "Workspace",
+      "label": "Custom App",
+      "name": "custom-app",
+      "to": "/plugins/frontend",
+      "relatedRoute": [
+        "/plugins/frontend"
+      ],
+      "icon": "",
+      "catalog": "Continuous Delivery"
+    }
+  ],
+  "dependencies": {
+    "velauxDependency": ">=1.8.0",
+    "plugins": []
+  }
+}