update & add some docs

README.md

@@ -37,28 +37,53 @@ kubean is a cluster lifecycle management tool based on [kubespray](https://githu
 
 ---
 
+## Awesome features
+- Simplicity: Deploying of Kubean and powerful lifecycle management of kubernetes cluster implementing by declarative API.
+- 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.
+- Compatibility: Multi-arch delivery Supporting. Such as AMD, ARM with common Linux distributions. Also include Kunpeng with Kylin.
+- Expandability: Allowing custom actions be added to cluster without any changes for Kubespray. 
+
 ## Quick Start
 
-#### 1. Deploy Kubean-Operator
+#### 1. Ensure that a Kubernetes Cluster exists and Helm installed
+
+#### 2. Deploy Kubean-Operator
 
 ``` shell
-helm repo add kubean-io https://kubean-io.github.io/kubean-helm-chart/
-helm install kubean kubean-io/kubean --create-namespace -n kubean-system
+$ helm repo add kubean-io https://kubean-io.github.io/kubean-helm-chart/
+$ helm install kubean kubean-io/kubean --create-namespace -n kubean-system
 ```
 
-Then check kubean-operator status by `kubectl get pods -n kubean-system | grep 'kubean'`.
+Then check kubean-operator status by 
+```shell 
+$ kubectl get pods -n kubean-system | grep 'kubean'
+```
 
-#### 2. Start ClusterOperation for cluster.yml playbook
+#### 3. Start ClusterOperation for cluster.yml playbook
 
 We cloud use the example in folder `artifacts/demo` which uses online resources to install k8s cluster.
 
-  1. `cd artifacts/`
+  1. cd resources path
+     ```shell
+     $ cd artifacts/
+     ```
   2. modify `demo/hosts-conf-cm.yml` by replacing `IP1`, `IP2`... with the real ip where we want to install k8s cluster
-  3. `kubectl apply -f demo/` to start kubeanClusterOps which will start the kubespray job
-  4. `kubectl get job -n kubean-system` to check the kubespray job status
+  3. start kubeanClusterOps which will start the kubespray job
+     ```shell
+     $ kubectl apply -f demo/
+     ```
+  4. check the kubespray job status
+     ```shell
+     $ kubectl get job -n kubean-system
+     ```
 
 [![quick_start_image](docs/images/quick_start.gif)](https://asciinema.org/a/511386)
 
 ## Offline Usage
 
 [offline](docs/offline.md)
+
+## Documents
+- [Architecture](docs/architecture_zh.md)
+- [Kubean vs Kubespray](docs/comparisons_zh.md)
+- [CRD Outline](docs/crds_zh.md)

docs/architecture_zh.md

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

docs/comparisons_zh.md

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

docs/crds_zh.md

@@ -0,0 +1,234 @@
+# CRD 概述
+
+## Cluster
+
+Kubean 允许通过 custom resource definitions (CRDs) 来声明（唯一标识）一个 Kubernetes 集群。所有对集群的操作都基于此 CRD 里声明的内容。
+
+下面是一份示例，帮助理解下文的配置项说明：
+```yaml
+apiVersion: kubean.io/v1alpha1
+kind: Cluster
+metadata:
+  name: cluster1-offline-demo
+spec:
+  hostsConfRef:
+    namespace: kubean-system
+    name: cluster1-offline-demo-hosts-conf
+  varsConfRef:
+    namespace: kubean-system
+    name: cluster1-offline-demo-vars-conf
+```
+
+### 配置项
+
+#### 元数据
+
+- `name`：name 用于声明一个集群，全局唯一
+
+#### 属性关联
+
+- `hostConfRef`：hostConfRef 是一个 ConfigMap 资源，它的内容应满足 ansible inventory 的格式，包含集群节点信息、类型分组信息。内容可参考 [demo](../artifacts/demo/hosts-conf-cm.yml)
+  - `name`：表示其引用的 ConfigMap 的名称
+  - `namespace`：表示其引用的 ConfigMap 所在的命名空间
+
+- `varsConfRef`：varsConfRef 是一个 ConfigMap 资源，用作初始化或覆盖 Kubespray 中声明的变量值。如果有离线需求，这将很有用。内容可参考 [demo](../artifacts/demo/vars-conf-cm.yml)
+  - `name`：表示其引用的 ConfigMap 的名称
+  - `namespace`：表示其引用的 ConfigMap 所在的命名空间
+
+- `sshAuthRef`：sshAuthRef 是一个 Secret 资源，仅在 SSH 私钥模式时使用
+  - `name`：表示其引用的 Secret 名称
+  - `namespace`：表示其引用的 Secret 所在的命名空间
+
+
+## ClusterOperation
+
+Kubean 允许通过 custom resource definitions (CRDs) 来声明对一个 Kubernetes 集群的操作（部署、升级等），前提是正确关联一个已经定义的 Cluster CRD。完成操作所必要的信息从其关联的 Cluster CRD 中获取。
+
+下面是一份示例，帮助理解下文的配置项说明：
+```yaml
+apiVersion: kubean.io/v1alpha1
+kind: ClusterOperation
+metadata:
+  name: cluster1-demo-ops-1
+spec:
+  cluster: cluster1-demo
+  image: ghcr.m.daocloud.io/kubean-io/spray-job:latest
+  backoffLimit: 0
+  actionType: playbook
+  action: cluster.yml
+  preHook:
+    - actionType: playbook
+      action: ping.yml
+    - actionType: playbook
+      action: disable-firewalld.yml
+  postHook:
+    - actionType: playbook
+      action: kubeconfig.yml
+    - actionType: playbook
+      action: cluster-info.yml
+```
+
+### 配置项
+
+#### 元数据
+
+- `name`：name 唯一标识一个对所关联集群的操作
+
+#### 操作定义
+
+- `cluster`：与此操作关联的集群名称，其值为 Cluster CRD 中声明的名称
+- `image`：kubespray 镜像地址；可以使用 Kubean 仓库构建的镜像，也可使用自行构建镜像
+- `actionType`：操作类型，目前支持指定 [`playbook`](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) 或 `shell`
+- `action`：意图执行的操作，目前支持指定 playbook 文件的路径或 shell 命令
+- `preHook`：前置执行操作，可以指定多个，例如可以测试节点连通性等
+  - `actionType`：同上
+  - `action`：同上
+- `postHook`：后置执行操作，可以指定多个，例如可以获取集群状态等
+  - `actionType`：同上
+  - `action`：同上
+- `backoffLimit`：操作执行失败后重试次数
+
+## Manifest
+
+Kubean 允许通过 custom resource definitions (CRDs) 来记录和维护当前版本的 Kubean 使用和兼容的组件、包及版本；使用者不用手动编写此资源，由 Kubean 自行维护。
+
+下面是一份示例，帮助理解下文的 spec 说明：
+```yaml
+apiVersion: kubean.io/v1alpha1
+kind: Manifest
+metadata:
+  name: kubeaninfomanifest-v0-4-0-rc2
+spec:
+  components:
+  - defaultVersion: v1.1.1
+    name: cni
+    versionRange:
+    - v1.0.1
+    - v1.1.1
+  - defaultVersion: 1.6.9
+    name: containerd
+    versionRange:
+    .......
+    - 1.6.7
+    - 1.6.8
+    - 1.6.9
+  - defaultVersion: ""
+    name: kube
+    versionRange:
+    - v1.25.3
+    - v1.25.2
+    - v1.25.1
+    ........
+  - defaultVersion: v3.23.3
+    name: calico
+    versionRange:
+    - v3.23.3
+    - v3.22.4
+    - v3.21.6
+  - defaultVersion: v1.12.1
+    name: cilium
+    versionRange: []
+  - defaultVersion: "null"
+    name: etcd
+    versionRange:
+    - v3.5.3
+    - v3.5.4
+    - v3.5.5
+  docker:
+  - defaultVersion: "20.10"
+    os: redhat-7
+    versionRange:
+    - latest
+    - "18.09"
+    - "19.03"
+    - "20.10"
+    - stable
+    - edge
+  - defaultVersion: "20.10"
+    os: debian
+    versionRange:
+    - latest
+    - "18.09"
+    - "19.03"
+    - "20.10"
+    - stable
+    - edge
+  - defaultVersion: "20.10"
+    os: ubuntu
+    versionRange:
+    - latest
+    - "18.09"
+    - "19.03"
+    - "20.10"
+    - stable
+    - edge
+  kubeanVersion: v0.4.0-rc2
+  kubesprayVersion: c788620
+```
+### spec 说明
+
+- `components`：镜像或二进制文件的版本声明
+  - `name`：组件名称
+  - `defaultVersion`：使用的默认版本
+  - `versionRange`：受支持的版本列表
+- `docker`：Docker 的版本管理
+  - `os`：受支持的操作系统
+  - `defaultVersion`：使用的默认版本
+  - `versionRange`：受支持的版本列表
+- `kubeanVersion`：Kubean 版本号
+- `kubesprayVersion`：当前 Kubean 依赖的 Kubespray 版本号
+
+## LocalArtifact
+
+Kubean 允许通过 custom resource definitions (CRDs) 来记录离线包支持的组件及版本信息；使用者不用手动编写此资源，由 Kubean 自行维护。
+
+下面是一份示例，帮助理解下文的 spec 说明：
+```yaml
+apiVersion: kubean.io/v1alpha1
+kind: LocalArtifactSet
+metadata:
+  name: offlineversion-20221101
+spec:
+  arch: ["x86_64"]
+  kubespray: "c788620"
+  docker:
+    - os: "redhat-7"
+      versionRange:
+        - "18.09"
+        - "19.03"
+        - "20.10"
+    - os: "debian"
+      versionRange: []
+    - os: "ubuntu"
+      versionRange: []
+  items:
+    - name: "cni"
+      versionRange:
+        - v1.1.1
+    - name: "containerd"
+      versionRange:
+        - 1.6.9
+    - name: "kube"
+      versionRange:
+        - v1.24.7
+    - name: "calico"
+      versionRange:
+        - v3.23.3
+    - name: "cilium"
+      versionRange:
+        - v1.12.1
+    - name: "etcd"
+      versionRange:
+        - v3.5.4
+```
+
+### spec 说明
+
+- `arch`：受支持的 CPU 指令集架构列表
+- `kubespray`：使用的 Kubespray 版本
+- `docker`：Docker 版本管理
+  - `os`：Docker 受支持的操作系统类型
+  - `versionRange`：受支持的 Docker 版本列表
+- `items`：其他组件版本管理
+  - `name`：组件名称
+  - `versionRange`：该组件受支持的版本列表