diff --git a/sig-architecture/concepts-and-designs/access-control-zh.md b/sig-architecture/concepts-and-designs/access-control-zh.md new file mode 100644 index 00000000..007d057b --- /dev/null +++ b/sig-architecture/concepts-and-designs/access-control-zh.md @@ -0,0 +1,137 @@ +## 权限控制 + +### RBAC + +https://kubernetes.io/docs/reference/access-authn-authz/rbac/ + +![](../images/rbac-example.png) + + +### KS中的租户与资源层级 + +![](../images/resource-hierarchy.png) + + +Platform: users、workspaces、clusters + +Cluster: nodes、workloads、namespaces + +Workspace: namespaces、apps + +Namesapce: workloads + +### API Pattern + +https://kubernetes.io/docs/reference/using-api/api-concepts/ + +``` +# KS API +/kapis/{apiGroup}/{apiVersion}/{resourcePlural}/{resourceName}/{subResource} + +# K8s 原生 API +/apis/{apiGroup}/{apiVersion}/{resourcePlural}/{resourceName}/{subResource} +/api/{apiGroup}/{apiVersion}/{resourcePlural}/{resourceName}/{subResource} + +# 多集群分发 +/apis/clusters/{cluster}/{apiGroup}/{apiVersion}/{resourcePlural}/{resourceName}/{subResource} +/kapis/clusters/{cluster}/{apiGroup}/{apiVersion}/{resourcePlural}/{resourceName}/{subResource} +``` + +**API 示例** + +Platform Scope + +特殊的 CRD，这类资源被 host 集群管理，受到 GlobalRole 的限制 + +``` +/kapis/iam.kubesphere.io/v1alpha2/users +/kapis/resources.kubesphere.io/v1alpha3/clusters +/kapis/tenant.kubesphere.io/v1alpha2/workspaces +``` + +Workspace Scope + +KS 中的资源层级，受到 WorkspaceRole 的限制 + +``` +/kapis/openpitrix.kubesphere.io/v1/workspaces/{workspace}/apps +/kapis/tenant.kubesphere.io/v1alpha2/workspaces/{workspace}/namespaces +``` + +Cluster Scope + +K8s 中的资源层级，收到 ClusterRole 的限制 + +``` +/api/v1/nodes +/apis/apps/v1/deployments +``` + +Namespace Scope + +``` +/apis/apps/v1/namespaces/{namespace}/deployments +``` + +### 插件的权限控制 + +KubeSphere 2.x + +![](../images/rbac-2.x.png) + + +KubeSphere 3.x + +![](./../images/rbac-3.x.png) + +KubeSphere 4.x + +在 3.x 的基础之上进一步细化 + +通过授权项对强相关的资源授权规则进行聚合，这是粗粒度 +授权粒度分为创建(create)、查看(list、get、watch)、编辑(update、patch)、删除(delete)、管理(\*) 五个部分，这个是细粒度 +授权项、功能模块可以在不通的插件中进行声明，动态拓展 + +** RoleTemplate ** + +```yaml +apiVersion: iam.kubesphere.io/v1 +kind: RoleTemplate +metadata: + annotations: + iam.kubesphere.io/scope: Platform + iam.kubesphere.io/module: Access Control + iam.kubesphere.io/rules: '{"users": "view"}' + name: role-template-view-users + +rules: +- apiGroups: + - '*' + resources: + - users + verbs: + - get + - list + - watch +``` + +```yaml +apiVersion: iam.kubesphere.io/v1 +kind: RoleTemplate +metadata: + annotations: + iam.kubesphere.io/scope: Namespaced + iam.kubesphere.io/module: Pipelines + iam.kubesphere.io/rules: '{"pipelines": "view"}' + name: role-template-view-pipelines + +rules: +- apiGroups: + - 'devops.kubesphere.io' + resources: + - 'pipelines' + verbs: + - get + - list + - watch +``` \ No newline at end of file diff --git a/sig-architecture/concepts-and-designs/demo-plugin-zh.md b/sig-architecture/concepts-and-designs/demo-plugin-zh.md new file mode 100644 index 00000000..593f083f --- /dev/null +++ b/sig-architecture/concepts-and-designs/demo-plugin-zh.md @@ -0,0 +1,204 @@ +# 插件开发示例 + +## 1. 部署 kubesphere v3.2.1 + +最小化[安装 KubeSphere v3.2.1](https://kubesphere.com.cn/docs/quick-start/all-in-one-on-linux/) + +## 2. 更新 ks-apiserver 与 ks-controller-manager 的镜像 + +镜像 `docker.io/wansir/ks-apiserver:experimental`、`docker.io/wansir/ks-controller-manager:experimental` 用于验证可插拔部分的架构设计 + +代码分支 [https://github.com/wansir/kubesphere/tree/feat-pluggable](https://github.com/wansir/kubesphere/tree/feat-pluggable) + +``` +kubectl -n kubesphere-system set image deploy/ks-apiserver ks-apiserver=docker.io/wansir/ks-apiserver:experimental +kubectl -n kubesphere-system set image deploy/ks-controller-manager ks-controller-manager=docker.io/wansir/ks-controller-manager:experimental +``` + +## 3. 对外暴露 ks-apiserver + +在前端本地开发的过程中，依赖 ks-apiserver 提供的 API，需要将 ks-apiserver.kubesphere-system.svc 暴露给开发环境。 + + +## 4. clone 前端代码到本地 + +代码分支 [https://github.com/chenz24/console/tree/plugin-marketplace](https://github.com/chenz24/console/tree/plugin-marketplace) 用与验证可插拔部分的架构设计 + +``` +git clone https://github.com/chenz24/console.git +cd console && git checkout plugin-marketplace +``` + +## 5. 插件开发示例 + +前端项目开发依赖 yarn、 node12 + +### 5.1 目录结构 + +`plugins/demo` 目录下是一个简单的插件示例 + +``` +├── plugins # 插件目录：可包含多个插件 +│ ├── Dockerfile # 将插件打包为 Helm Repo 通过 Docker Image 进行分发 +│ ├── demo # demo 插件目录 +│ │ ├── Chart.yaml # 定义插件的基础信息 +│ │ ├── Dockerfile # 打包插件所涉及的工作负载，用于提供 API 或静态资源 +│ │ ├── README.md +│ │ ├── charts +│ │ ├── dist +│ │ │ └── index.js # 通过 webpack 打包后的 js 文件 +│ │ ├── package-lock.json +│ │ ├── package.json +│ │ ├── server +│ │ │ └── app.js +│ │ ├── src # 插件源代码 +│ │ │ ├── App.jsx +│ │ │ ├── index.js +│ │ │ └── routes +│ │ ├── templates # 定义如何部署插件 +│ │ │ ├── NOTES.txt +│ │ │ ├── _helpers.tpl +│ │ │ ├── deployment.yaml # 插件部署文件 +│ │ │ ├── extensions.yaml # API注册、JSBundle注册 +│ │ │ ├── service.yaml +│ │ │ └── tests +│ │ └── values.yaml +│ └── entry.ts +``` + +插件中(`plugins/demo/src/routes/index.js`)注册了路径为 `/demo` 的页面路由 + +```javascript +import React from 'react'; +import App from '../App'; + +export default [ + { + path: '/demo', + element: , + }, +]; +``` + +一个简单的插件页面(`plugins/demo/src/App.jsx`) + +```javascript +import React from 'react'; + +export default function App() { + return

This is demo plugin

; +} +``` + + + +### 5.2 本地预览 + +插件在开发时可以通过本地文件的方式进行加载，无需通过 ks-apiserver 进行远程加载。 + +``` +yarn dev +``` + +访问 `http://localhost:8000/demo` 可以正常打开插件页面 + +![demo](../images/demo.png) + +### 5.3 插件打包 + +在本地验证插件可以正常显示之后，通过 Helm 对插件进行打包。 + +``` +cd plugins/demo +yarn build +``` + +插件打包完成会在 `dist` 目录下生成 `index.js` + +此时需要提供一个后端服务，提供打包之后 `index.js` 文件的下载路径，可以使用 nginx 或者 node 等提供一个静态资源访问地址。 + +示例中通过一个简单的 node server 提供了 `index.js` 的访问地址：`/dist/demo.kubesphere.io/v1alpha2/index.js` + +将 `server/app.js` 与 `dist/index.js` 一起打包到一个镜像中，并创建出关联的 K8s 资源模板 `plugins/demo/templates/deployments.yaml`、`plugins/demo/templates/services.yaml`，部署该工作负载之后可以通 service 地址获取到 `index.js` + +```bash +cd plugins/demo +docker build -t : . +docker push : . +``` + +`plugins/demo/templates/extensions.yaml` 文件中 `JSBundle` 声明了该插件以及 `index.js` 加载的路径 + +```yaml +apiVersion: extensions.kubesphere.io/v1alpha1 +kind: JSBundle +metadata: + name: demo.kubesphere.io +spec: + rawFrom: + url: http://{{ include "demo.fullname" . }}.{{ .Release.Namespace }}.svc # 部署之后的静态资源服务访问地址 +status: + enabled: true + link: /dist/demo.kubesphere.io/v1alpha2/index.js # 通过 ks-apiserver 代理之后 index.js 的加载地址（验证过程中需要手动指定，插件机制完善之后该地址会自动生成） +``` + +### 5.4 插件部署 + +在完成对插件的 Helm 打包之后，可以通过以下命令在远程环境中部署该插件 + +```bash +helm upgrade demo demo --create-namespace -n kubesphere-plugins --install --set image.repository= --set image.tag= +``` + +完成安装之后可以通过一下命令来验证是否安装正确 + +```bash +$ kubectl get jsbundle +NAME AGE +demo.kubesphere.io 7m36s +$ kubectl -n kubesphere-plugins get all +NAME READY STATUS RESTARTS AGE +pod/demo-5cf6d76fc7-7594t 1/1 Running 0 3m54s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/demo ClusterIP 10.233.18.102 80/TCP 8m2s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/demo 1/1 1 1 8m2s + +NAME DESIRED CURRENT READY AGE +replicaset.apps/demo-5cf6d76fc7 1 1 1 3m54s +``` + +可以观察到 jsbundle 资源和 demo 插件依赖的 workloads 及 service 都已经正常创建 + +### 5.5 加载远程插件 + +在完成插件的部署之后， ks-console 便可以通过 ks-apiserver 提供的 API 发现需要加载的插件 + +通过一下方式可以在本地开发过程中加载远程环境中部署好的插件。 + +创建本地配置文件 `cp config/config.yaml config/local_config.yaml` 并替换 `apiServer.url` 地址为开发环境中 ks-apiserver 的地址 + +通过以下命令启动 ks-console + +```bash +yarn build:dll +yarn build +yarn start +``` + +访问 demo 插件注册的路由地址 `http://localhost:8000/demo` 可以正常加载插件页面 + +以下日志可以追踪插件的加载过程 + +```bash +Dashboard app running at port 8000 + <-- GET /demo 2022/03/11T18:50:57.833 + --> GET /demo 200 471ms 16.88kb 2022/03/11T18:50:58.303 + <-- GET /pstatic/dist/demo.kubesphere.io/v1alpha2/index.js 2022/03/11T18:50:58.729 +GET /pstatic/dist/demo.kubesphere.io/v1alpha2/index.js -> http://139.198.13.78:30881/dist/demo.kubesphere.io/v1alpha2/index.js +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 +``` + + diff --git a/sig-architecture/concepts-and-designs/pluggable-architecture-zh.md b/sig-architecture/concepts-and-designs/pluggable-architecture-zh.md index 30481d18..4ba87d85 100644 --- a/sig-architecture/concepts-and-designs/pluggable-architecture-zh.md +++ b/sig-architecture/concepts-and-designs/pluggable-architecture-zh.md @@ -27,7 +27,7 @@ TBD 后端的插件化主要包含 API 的注册、静态资源的代理两个部分，可以把 ks-apiserver 看作一个可拓展的 API 网关，由 ks-apiserver 提供统一的 API 认证鉴权能力，支持动态的 API 拓展。 -![backend](../images/backend.svg) +![backend](../images/pluggable-backend.svg) ### Plugin Model @@ -83,7 +83,7 @@ status: #### ReverseProxy -提供非资源型 API 的方向代理，可以用来代理一些静态的资源文件，支持路径的 Rewrite，支持请求头的注入。 +提供非资源型 API 的反向代理，可以用来代理一些静态的资源文件，支持路径的 Rewrite，支持请求头的注入等网关功能。 API 的路径会在解析插件的时候就进行检查，避免冲突。 diff --git a/sig-architecture/concepts-and-designs/plugin-development-guide-zh.md b/sig-architecture/concepts-and-designs/plugin-development-guide-zh.md index d202e2c3..29585d2c 100644 --- a/sig-architecture/concepts-and-designs/plugin-development-guide-zh.md +++ b/sig-architecture/concepts-and-designs/plugin-development-guide-zh.md @@ -27,7 +27,7 @@ TBD 插件开发完成之后，需要与依赖组件一起打包为 Helm Chart。 1. 一个插件打包为一个 Helm Chart -2. 一组插件打包为 Docker Iamge 之后可以进行发布 +2. 一组插件打包为 Docker Image 之后可以进行发布 ### Helm Chart 的目录结构 @@ -95,7 +95,7 @@ annotations: extensions.kubesphere.io/foo: bar # 额外的注释信息 ``` -### 打包为 Docker Iamge 对插件进行分发 +### 打包为 Docker Image 对插件进行分发 ```dockerfile FROM baseimage # Framwork 提供的 baseimage diff --git a/sig-architecture/images/backend.svg b/sig-architecture/images/backend.svg deleted file mode 100644 index c48d1663..00000000 --- a/sig-architecture/images/backend.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
plugin-controller
plugin-controller
ks-apiserver
ks-apiserver
filters
filters
RequestInfo
RequestInfo
Authentication
Authentication
Authorization
Authorization

RequestInfo

+ API Group
+ API Version

+ Resources

+ Resource Name

+ Path

+ Scope

RequestInfo...

UserInfo

+ Username
+ User Group

+ Extras


UserInfo...
Authenticators
Authenticators
Password Authenticator
Password Authenticator
OAuth Authenticator
OAuth Authenticator
RBAC Authorizer
RBAC Authorizer
User/Group
User/Group
Role
Role
Dispatch
Dispatch
Dispatchers
Dispatchers
APIServiceDispatcher
APIServiceDispatcher
MultiClusterDispatcher
MultiClusterDispatcher
StaticResourceDispatcher
StaticResourceDispatcher
/kapis/clusters/{cluster}
/kapis/clusters/{cluster}
/kapis/group.klubesphere.io/v1alpha2
/kapis/group.klubesphere.io/v1alpha2

Plugin

apiVersion: extensions.kubesphere.io/v1alpha1
kind: Plugin
...
Plugin...

APIService

apiVersion: extensions.kubesphere.io/v1alpha1
kind: APIService
...
APIService...

JSBundle

apiVersion: extensions.kubesphere.io/v1alpha1
kind: JSBundle
...
JSBundle...
...
...
/dist/group.kubesphere.io/v1alpha2/index.js
/dist/group.kubesphere.io/v1alpha2/index.js

ReverseProxy

apiVersion: extensions.kubesphere.io/v1alpha1
kind: ReverseProxy
...
ReverseProxy...Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/sig-architecture/images/demo.png b/sig-architecture/images/demo.png new file mode 100644 index 00000000..3e8638fc Binary files /dev/null and b/sig-architecture/images/demo.png differ diff --git a/sig-architecture/images/pluggable-backend.svg b/sig-architecture/images/pluggable-backend.svg new file mode 100644 index 00000000..1ae3abb3 --- /dev/null +++ b/sig-architecture/images/pluggable-backend.svg @@ -0,0 +1,3 @@ + + +
Plugin A
Plugin A
Proxy
Proxy
API Gateway
API Gateway
APIService
APIService
JSBundle
JSBundle
Register
Register
Reconcile
Reconcile
ReverseProxy
ReverseProxy
Backend
Backend
Frontend
Frontend
Resource
Resource
Plugin Controller Manager
Plugin Controller Manager
Pluggable Frontend Framwork
Pluggable Frontend Framwork
CR
CR
CR
CR
CR
CRViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/sig-architecture/images/rbac-2.x.png b/sig-architecture/images/rbac-2.x.png new file mode 100644 index 00000000..c965d015 Binary files /dev/null and b/sig-architecture/images/rbac-2.x.png differ diff --git a/sig-architecture/images/rbac-3.x.png b/sig-architecture/images/rbac-3.x.png new file mode 100644 index 00000000..4e32c394 Binary files /dev/null and b/sig-architecture/images/rbac-3.x.png differ diff --git a/sig-architecture/images/rbac-example.png b/sig-architecture/images/rbac-example.png new file mode 100644 index 00000000..5ac16ef8 Binary files /dev/null and b/sig-architecture/images/rbac-example.png differ diff --git a/sig-architecture/images/resource-hierarchy.png b/sig-architecture/images/resource-hierarchy.png new file mode 100644 index 00000000..a608f9c5 Binary files /dev/null and b/sig-architecture/images/resource-hierarchy.png differ