Skip to content

Commit 4f55ec3

Browse files
ErikJiangErikJiang
authored
Merge pull request #299 from tu1h/docs
update & add some docs
2 parents a6c553e + 2b85608 commit 4f55ec3

File tree

7 files changed

+296
-8
lines changed

7 files changed

+296
-8
lines changed

‎README.md

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -37,28 +37,53 @@ kubean is a cluster lifecycle management tool based on [kubespray](https://githu
3737

3838
---
3939

40+
## Awesome features
41+
- Simplicity: Deploying of Kubean and powerful lifecycle management of kubernetes cluster implementing by declarative API.
42+
- Offline Supported: Offline packages(os-pkgs, images, binarys) are released with the release. You won't have to worry about how to gather all the resources you need.
43+
- Compatibility: Multi-arch delivery Supporting. Such as AMD, ARM with common Linux distributions. Also include Kunpeng with Kylin.
44+
- Expandability: Allowing custom actions be added to cluster without any changes for Kubespray.
45+
4046
## Quick Start
4147

42-
#### 1. Deploy Kubean-Operator
48+
#### 1. Ensure that a Kubernetes Cluster exists and Helm installed
49+
50+
#### 2. Deploy Kubean-Operator
4351

4452
``` shell
45-
helm repo add kubean-io https://kubean-io.github.io/kubean-helm-chart/
46-
helm install kubean kubean-io/kubean --create-namespace -n kubean-system
53+
$ helm repo add kubean-io https://kubean-io.github.io/kubean-helm-chart/
54+
$ helm install kubean kubean-io/kubean --create-namespace -n kubean-system
4755
```
4856

49-
Then check kubean-operator status by `kubectl get pods -n kubean-system | grep 'kubean'`.
57+
Then check kubean-operator status by
58+
```shell
59+
$ kubectl get pods -n kubean-system | grep 'kubean'
60+
```
5061

51-
#### 2. Start ClusterOperation for cluster.yml playbook
62+
#### 3. Start ClusterOperation for cluster.yml playbook
5263

5364
We cloud use the example in folder `artifacts/demo` which uses online resources to install k8s cluster.
5465

55-
1. `cd artifacts/`
66+
1. cd resources path
67+
```shell
68+
$ cd artifacts/
69+
```
5670
2. modify `demo/hosts-conf-cm.yml` by replacing `IP1`, `IP2`... with the real ip where we want to install k8s cluster
57-
3. `kubectl apply -f demo/` to start kubeanClusterOps which will start the kubespray job
58-
4. `kubectl get job -n kubean-system` to check the kubespray job status
71+
3. start kubeanClusterOps which will start the kubespray job
72+
```shell
73+
$ kubectl apply -f demo/
74+
```
75+
4. check the kubespray job status
76+
```shell
77+
$ kubectl get job -n kubean-system
78+
```
5979

6080
[![quick_start_image](docs/images/quick_start.gif)](https://asciinema.org/a/511386)
6181

6282
## Offline Usage
6383

6484
[offline](docs/offline.md)
85+
86+
## Documents
87+
- [Architecture](docs/architecture_zh.md)
88+
- [Kubean vs Kubespray](docs/comparisons_zh.md)
89+
- [CRD Outline](docs/crds_zh.md)

‎docs/architecture_zh.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## Kubean 基础架构
2+
3+
Kubean 的整体架构如下所示：
4+
5+
![kubean-architecture](images/kubean-architecture.png)
6+
7+
Kubean 需要运行在一个已存在的 Kubernetes 集群，通过应用 Kubean 提供的标准 CRD 资源和 Kubernetes 内建资源来控制和管理集群的生命周期（安装、卸载、升级、扩容、缩容等）。 Kubean 采用 Kubespray 作为底层技术依赖，一方面简化了集群部署的操作流程，降低了用户的使用门槛。另一方面在 Kubespray 能力基础上增加了集群操作记录、离线版本记录等诸多新特性。
8+
9+
<br/>
10+
11+
![kubean-components](images/kubean-components.png)
12+
13+
Kubean 运行着多个控制器，这些控制器跟踪 Kubean CRD 对象的变化，并且与底层集群的 API 服务器进行通信来创建 Kubernetes原生资源对象。由以下四个组件构成：
14+
15+
1. Cluster Controller: 监视 `Cluster Objects`。唯一标识一个集群，拥有集群节点的访问信息、类型信息、部署参数信息，并且关联所有对此集群的操作（`ClusterOperation Objects`）；
16+
2. ClusterOperation Controller: 监视 `ClusterOperation Objects`。当 `ClusterOperation Object` 被创建时，控制器会组装一个 [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) 去执行 CRD 对象里定义的操作；
17+
3. Manifest Controller: 监视 `Manifest Objects`。用于记录和维护当前版本的 Kubean 使用和兼容的组件、包及版本；
18+
4. LocalArtifactSet Controller：监视 `LocalArtifactSet Objects`。用于记录离线包支持的组件及版本信息。

‎docs/comparisons_zh.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# 优劣对比
2+
3+
## Kubean vs Kubespray
4+
5+
Kubespray 使用 Ansible 作为底层来配置和编排，可以运行在裸金属机、虚拟机、大多数云环境等。它支持众多 Kubernetes 版本和插件，可以完成集群从 0 到 1 的搭建和配置，也包含集群生命周期的维护，使用方式非常灵活。
6+
7+
Kubean 基于 Kubespray，拥有 Kubespray 所有优势。并且 Kubean 引用 Operator 概念以实现完全云原生化，原生以容器方式运行，提供 Helm Chart 包进行快速部署。
8+
9+
Kubespray 仅在参数级别上支持离线，并没有包含一个完成构建离线安装包的过程，所以对于有离线场景需求的使用者来说，直接使用 Kubespray 会变得非常繁琐，这通常会让他们失去耐心。
10+
11+
Kubean 不仅有一套完善的制作离线包的工作流，还适配国产信创环境，简化 Kubespray 的复杂配置，能够对集群生命周期以云原生的方式去管理。

‎docs/crds_zh.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# CRD 概述
2+
3+
## Cluster
4+
5+
Kubean 允许通过 custom resource definitions (CRDs) 来声明（唯一标识）一个 Kubernetes 集群。所有对集群的操作都基于此 CRD 里声明的内容。
6+
7+
下面是一份示例，帮助理解下文的配置项说明：
8+
```yaml
9+
apiVersion: kubean.io/v1alpha1
10+
kind: Cluster
11+
metadata:
12+
name: cluster1-offline-demo
13+
spec:
14+
hostsConfRef:
15+
namespace: kubean-system
16+
name: cluster1-offline-demo-hosts-conf
17+
varsConfRef:
18+
namespace: kubean-system
19+
name: cluster1-offline-demo-vars-conf
20+
```
21+
22+
### 配置项
23+
24+
#### 元数据
25+
26+
- `name`：name 用于声明一个集群，全局唯一
27+
28+
#### 属性关联
29+
30+
- `hostConfRef`：hostConfRef 是一个 ConfigMap 资源，它的内容应满足 ansible inventory 的格式，包含集群节点信息、类型分组信息。内容可参考 [demo](../artifacts/demo/hosts-conf-cm.yml)
31+
- `name`：表示其引用的 ConfigMap 的名称
32+
- `namespace`：表示其引用的 ConfigMap 所在的命名空间
33+
34+
- `varsConfRef`：varsConfRef 是一个 ConfigMap 资源，用作初始化或覆盖 Kubespray 中声明的变量值。如果有离线需求，这将很有用。内容可参考 [demo](../artifacts/demo/vars-conf-cm.yml)
35+
- `name`：表示其引用的 ConfigMap 的名称
36+
- `namespace`：表示其引用的 ConfigMap 所在的命名空间
37+
38+
- `sshAuthRef`：sshAuthRef 是一个 Secret 资源，仅在 SSH 私钥模式时使用
39+
- `name`：表示其引用的 Secret 名称
40+
- `namespace`：表示其引用的 Secret 所在的命名空间
41+
42+
43+
## ClusterOperation
44+
45+
Kubean 允许通过 custom resource definitions (CRDs) 来声明对一个 Kubernetes 集群的操作（部署、升级等），前提是正确关联一个已经定义的 Cluster CRD。完成操作所必要的信息从其关联的 Cluster CRD 中获取。
46+
47+
下面是一份示例，帮助理解下文的配置项说明：
48+
```yaml
49+
apiVersion: kubean.io/v1alpha1
50+
kind: ClusterOperation
51+
metadata:
52+
name: cluster1-demo-ops-1
53+
spec:
54+
cluster: cluster1-demo
55+
image: ghcr.m.daocloud.io/kubean-io/spray-job:latest
56+
backoffLimit: 0
57+
actionType: playbook
58+
action: cluster.yml
59+
preHook:
60+
- actionType: playbook
61+
action: ping.yml
62+
- actionType: playbook
63+
action: disable-firewalld.yml
64+
postHook:
65+
- actionType: playbook
66+
action: kubeconfig.yml
67+
- actionType: playbook
68+
action: cluster-info.yml
69+
```
70+
71+
### 配置项
72+
73+
#### 元数据
74+
75+
- `name`：name 唯一标识一个对所关联集群的操作
76+
77+
#### 操作定义
78+
79+
- `cluster`：与此操作关联的集群名称，其值为 Cluster CRD 中声明的名称
80+
- `image`：kubespray 镜像地址；可以使用 Kubean 仓库构建的镜像，也可使用自行构建镜像
81+
- `actionType`：操作类型，目前支持指定 [`playbook`](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) 或 `shell`
82+
- `action`：意图执行的操作，目前支持指定 playbook 文件的路径或 shell 命令
83+
- `preHook`：前置执行操作，可以指定多个，例如可以测试节点连通性等
84+
- `actionType`：同上
85+
- `action`：同上
86+
- `postHook`：后置执行操作，可以指定多个，例如可以获取集群状态等
87+
- `actionType`：同上
88+
- `action`：同上
89+
- `backoffLimit`：操作执行失败后重试次数
90+
91+
## Manifest
92+
93+
Kubean 允许通过 custom resource definitions (CRDs) 来记录和维护当前版本的 Kubean 使用和兼容的组件、包及版本；使用者不用手动编写此资源，由 Kubean 自行维护。
94+
95+
下面是一份示例，帮助理解下文的 spec 说明：
96+
```yaml
97+
apiVersion: kubean.io/v1alpha1
98+
kind: Manifest
99+
metadata:
100+
name: kubeaninfomanifest-v0-4-0-rc2
101+
spec:
102+
components:
103+
- defaultVersion: v1.1.1
104+
name: cni
105+
versionRange:
106+
- v1.0.1
107+
- v1.1.1
108+
- defaultVersion: 1.6.9
109+
name: containerd
110+
versionRange:
111+
.......
112+
- 1.6.7
113+
- 1.6.8
114+
- 1.6.9
115+
- defaultVersion: ""
116+
name: kube
117+
versionRange:
118+
- v1.25.3
119+
- v1.25.2
120+
- v1.25.1
121+
........
122+
- defaultVersion: v3.23.3
123+
name: calico
124+
versionRange:
125+
- v3.23.3
126+
- v3.22.4
127+
- v3.21.6
128+
- defaultVersion: v1.12.1
129+
name: cilium
130+
versionRange: []
131+
- defaultVersion: "null"
132+
name: etcd
133+
versionRange:
134+
- v3.5.3
135+
- v3.5.4
136+
- v3.5.5
137+
docker:
138+
- defaultVersion: "20.10"
139+
os: redhat-7
140+
versionRange:
141+
- latest
142+
- "18.09"
143+
- "19.03"
144+
- "20.10"
145+
- stable
146+
- edge
147+
- defaultVersion: "20.10"
148+
os: debian
149+
versionRange:
150+
- latest
151+
- "18.09"
152+
- "19.03"
153+
- "20.10"
154+
- stable
155+
- edge
156+
- defaultVersion: "20.10"
157+
os: ubuntu
158+
versionRange:
159+
- latest
160+
- "18.09"
161+
- "19.03"
162+
- "20.10"
163+
- stable
164+
- edge
165+
kubeanVersion: v0.4.0-rc2
166+
kubesprayVersion: c788620
167+
```
168+
### spec 说明
169+
170+
- `components`：镜像或二进制文件的版本声明
171+
- `name`：组件名称
172+
- `defaultVersion`：使用的默认版本
173+
- `versionRange`：受支持的版本列表
174+
- `docker`：Docker 的版本管理
175+
- `os`：受支持的操作系统
176+
- `defaultVersion`：使用的默认版本
177+
- `versionRange`：受支持的版本列表
178+
- `kubeanVersion`：Kubean 版本号
179+
- `kubesprayVersion`：当前 Kubean 依赖的 Kubespray 版本号
180+
181+
## LocalArtifact
182+
183+
Kubean 允许通过 custom resource definitions (CRDs) 来记录离线包支持的组件及版本信息；使用者不用手动编写此资源，由 Kubean 自行维护。
184+
185+
下面是一份示例，帮助理解下文的 spec 说明：
186+
```yaml
187+
apiVersion: kubean.io/v1alpha1
188+
kind: LocalArtifactSet
189+
metadata:
190+
name: offlineversion-20221101
191+
spec:
192+
arch: ["x86_64"]
193+
kubespray: "c788620"
194+
docker:
195+
- os: "redhat-7"
196+
versionRange:
197+
- "18.09"
198+
- "19.03"
199+
- "20.10"
200+
- os: "debian"
201+
versionRange: []
202+
- os: "ubuntu"
203+
versionRange: []
204+
items:
205+
- name: "cni"
206+
versionRange:
207+
- v1.1.1
208+
- name: "containerd"
209+
versionRange:
210+
- 1.6.9
211+
- name: "kube"
212+
versionRange:
213+
- v1.24.7
214+
- name: "calico"
215+
versionRange:
216+
- v3.23.3
217+
- name: "cilium"
218+
versionRange:
219+
- v1.12.1
220+
- name: "etcd"
221+
versionRange:
222+
- v3.5.4
223+
```
224+
225+
### spec 说明
226+
227+
- `arch`：受支持的 CPU 指令集架构列表
228+
- `kubespray`：使用的 Kubespray 版本
229+
- `docker`：Docker 版本管理
230+
- `os`：Docker 受支持的操作系统类型
231+
- `versionRange`：受支持的 Docker 版本列表
232+
- `items`：其他组件版本管理
233+
- `name`：组件名称
234+
- `versionRange`：该组件受支持的版本列表

‎docs/images/kubean-architecture.png

233 KB
Loading

‎docs/images/kubean-components.png

16.8 KB
Loading

‎docs/offline.zh.md renamed to ‎docs/offline_zh.md

File renamed without changes.

0 commit comments

Comments
 (0)