docs: builtin docs (#2626)

Signed-off-by: joyceliu <joyceliu@yunify.com>
2025-12-25 17:12:50 +00:00 · 2025-06-18 17:29:32 +08:00 · 2025-06-18 17:29:32 +08:00 · 03c6ce1fe7
parent e3f2372ee0
commit 03c6ce1fe7
5 changed files with 2538 additions and 5 deletions
--- a/README.md
+++ b/README.md
@ -10,19 +10,20 @@
 ```shell
 helm upgrade --install --create-namespace -n kubekey-system kubekey kubekey-1.0.0.tgz
 ```
-然后通过创建Inventory, Config, 和Playbook资源来执行命令  
+然后通过创建 `Inventory` 和 `Playbook` 资源来执行命令  
 **Inventory**: 任务执行的host清单. 用于定义与host相关, 与任务模板无关的变量. 详见[参数定义](docs/zh/201-variable.md)  
-**Config**: 给任务模板设置全局变量. 用于定义与host无关, 与任务模板相关的变量. 详见[参数定义](docs/zh/201-variable.md)  
-**Playbook**: 指定执行的playbook文件  
+**Playbook**: playbook的配置信息，在哪些host中执行，执行哪个playbook文件， 执行时参数等等。

 ## 二进制执行
 可直接用二进制在命令行中执行命令
 ```shell
 kk run -i inventory.yaml -c config.yaml playbook.yaml
 ```
-运行命令后, 会在工作目录的runtime下生成对应的Inventory, Config和Playbook资源
+运行命令后, 会在工作目录的runtime下生成对应的 `Inventory` 和 `Playbook` 资源

 # 文档
 **[项目模版编写规范](docs/zh/001-project.md)**  
 **[模板语法](docs/zh/101-syntax.md)**  
-**[参数定义](docs/zh/201-variable.md)**
+**[参数定义](docs/zh/201-variable.md)**    
+**[集群管理](docs/zh/core/README.md)**    
+
--- a/docs/images/architecture.excalidraw
+++ b/docs/images/architecture.excalidraw
--- a/docs/images/architecture.png
+++ b/docs/images/architecture.png
--- a/docs/zh/core/README.md
+++ b/docs/zh/core/README.md
@ -0,0 +1,85 @@
+# kubernetes cluster manager
+
+内建的playbook实现了kubernetes的一整套生命周期管理，包含创建集群，删除集群，添加节点，删除节点，升级集群等。
+
+## requirement
+
+- 一台或多台运行兼容 deb/rpm 的 Linux 操作系统的计算机；例如：Ubuntu 或 CentOS。
+- 每台机器 2 GB 以上的内存，内存不足时应用会受限制。
+- 用作控制平面节点的计算机上至少有 2 个 CPU。
+- 集群中所有计算机之间具有完全的网络连接。你可以使用公共网络或专用网络
+
+## 构建inventory
+默认的inventory配置如下：
+```yaml
+apiVersion: kubekey.kubesphere.io/v1
+kind: Inventory
+metadata:
+  name: default
+spec:
+  hosts: # your can set all nodes here. or set nodes on special groups.
+#    node1:
+#      connector:
+#        type: ssh
+#        host: node1
+#        port: 22
+#        user: root
+#        password: 123456
+  groups:
+    # all kubernetes nodes.
+    k8s_cluster:
+      groups:
+        - kube_control_plane
+        - kube_worker
+    # control_plane nodes
+    kube_control_plane:
+      hosts:
+        - localhost
+    # worker nodes
+    kube_worker:
+      hosts:
+        - localhost
+    # etcd nodes when etcd_deployment_type is external
+    etcd:
+      hosts:
+        - localhost
+#    image_registry:
+#      hosts:
+#        - localhost
+    # nfs nodes for registry storage. and kubernetes nfs storage
+#    nfs:
+#      hosts:
+#        - localhost
+
+```
+inventory包含如下几个内置的group:
+1. k8s_cluster: kubernetes集群。包含两个子group: kube_control_plane, kube_worker
+2. kube_control_plane: kubernetes集群中的control_plane节点组
+3. kube_worker: kubernetes集群中的worker节点组。
+4. etcd: 安装etcd集群的节点组。
+5. image_registry: 安装镜像仓库的节点组。（包含harbor，registry）
+6. nfs: 安装nfs的节点组。
+
+## 构建config
+默认的 config 配置如下：
+
+
+针对不同的kubernetes版本，给出了不同默认config配置作为参考:
+- [安装 v1.23.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.23.yaml)
+- [安装 v1.24.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.24.yaml)  
+- [安装 v1.25.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.25.yaml)
+- [安装 v1.26.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.26.yaml)
+- [安装 v1.27.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.27.yaml)
+- [安装 v1.28.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.28.yaml)
+- [安装 v1.29.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.29.yaml)
+- [安装 v1.30.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.30.yaml)
+- [安装 v1.31.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.31.yaml)
+- [安装 v1.32.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.32.yaml)
+- [安装 v1.33.x 版本的kubernetes 配置](../../../builtin/core/defaults/config/v1.33.yaml)
+
+## 安装集群
+```shell
+kk create cluster -i inventory.yaml -c config.yaml
+```
+`-i inventory.yaml`不传时，使用默认的inventory.yaml. 只会在执行的机器上安装kubernetes.
+`-c config.yaml`不传时，使用默认的config.yaml. 安装 v1.33.1 版本的kubernetes
--- a/docs/zh/core/architecture.md
+++ b/docs/zh/core/architecture.md
@ -0,0 +1,83 @@
+# architecture
+
+![architecture](../../images/architecture.png)
+
+## pre_hook
+
+pre_hook 允许用户在创建集群之前，在对应的节点上执行脚本。
+
+执行流程：
+1. 复制本地目录的脚本文件到远程节点的 `/etc/kubekey/scripts/pre_install_{{ .inventory_hostname }}.sh`
+2. 设置脚本文件权限为 0755
+3. 遍历每个远程节点上 `/etc/kubekey/scripts/` 目录下所有 `pre_install_*.sh` 文件，并执行该脚本文件
+ 
+ > work_dir: 工作目录，默认当前命令执行目录。     
+ > inventory_hostname: Inventory.yaml 文件中定义的host对应的名称。
+
+ ## precheck
+
+precheck 集群安装前，对集群节点进行检查是否满足集群安装条件。
+
+**os_precheck**: 操作系统检查，包括：
+- **主机名检查**: 验证主机名格式是否符合规范（仅包含小写字母数字字符、'.'或'-'，且必须以字母数字字符开头和结尾）
+- **操作系统版本检查**: 验证当前操作系统是否在支持的操作系统发行版列表中，除非允许不支持的发行版设置
+- **架构检查**: 验证系统架构是否为支持的架构（amd64或arm64）
+- **内存检查**: 
+  - 对于主节点：验证内存是否满足最小主节点内存要求
+  - 对于工作节点：验证内存是否满足最小工作节点内存要求
+- **内核版本检查**: 验证内核版本是否满足最低版本要求
+**kubernetes_precheck**: Kubernetes 相关检查，包括：
+- **IP地址检查**: 验证节点是否定义了 internal_ipv4 或 internal_ipv6，两者不能同时为空
+- **KubeVIP检查**: 当使用 kube_vip 类型的控制平面端点时，验证 kube_vip 地址是否有效且未被使用
+- **Kubernetes版本检查**: 验证 Kubernetes 版本是否满足最低版本要求
+- **已安装Kubernetes检查**: 验证节点上是否已安装 Kubernetes，如果已安装则检查版本是否与配置的 kube_version 匹配
+**network_precheck**: 网络连通性检查，包括：
+- **网络接口检查**: 验证节点上是否存在配置的 IPv4 或 IPv6 网络接口
+- **CIDR 配置检查**: 验证 Pod CIDR 和 Service CIDR 配置格式是否正确（支持双栈格式：ipv4_cidr/ipv6_cidr 或 ipv4_cidr,ipv6_cidr）
+- **双栈网络支持检查**: 当配置双栈网络时，验证 Kubernetes 版本是否支持（v1.20.0+）
+- **网络插件检查**: 验证配置的网络插件是否在支持列表中
+- **网络地址空间检查**: 确保节点上可用的网络地址空间足够容纳配置的最大 Pod 数量
+- **Hybridnet 版本检查**: 当使用 Hybridnet 网络插件时，验证 Kubernetes 版本是否满足要求（v1.16.0+）
+**etcd_precheck**: etcd 集群检查，包括：
+- **部署类型校验**：校验 etcd 的部署类型（internal 或 external），并在 external 模式下确保 etcd 组不为空且节点数量为奇数
+- **磁盘 IO 性能检查**：通过 fio 工具对 etcd 数据盘进行写入延迟测试，确保磁盘同步延迟（如 WAL fsync）满足集群要求
+- **已安装 etcd 检查**：检测当前主机是否已安装 etcd 服务
+**cri_precheck**: 容器运行时检查，包括：
+- **容器管理器检查**: 验证配置的容器管理器是否在支持的列表中（docker 或 containerd）
+- **containerd 版本检查**: 当使用 containerd 作为容器管理器时，验证 containerd 版本是否满足最低版本要求
+**nfs_precheck**: NFS 存储检查，包括：
+- **NFS 服务器数量检查**: 验证集群中只能有一个 NFS 服务器节点，确保 NFS 服务部署的唯一性
+
+## init
+
+init 阶段负责准备和构建集群安装所需的所有资源，包括：
+- **软件包下载**: 下载 Kubernetes、容器运行时、网络插件等核心组件的二进制文件，确保所有必需的软件包都已准备就绪
+- **Helm Chart 准备**: 获取和验证所需的 Helm Chart 包，为后续的应用程序部署做准备
+- **容器镜像拉取**: 下载集群组件所需的 Docker 镜像，包括核心组件镜像和依赖镜像
+- **离线包构建**: 当配置离线安装时，将所有依赖资源（二进制文件、镜像、Chart 包等）打包成完整的离线安装包
+- **证书管理**: 生成集群安装和组件间通信所需的各种证书，包括 CA 证书、服务证书等
+
+## install
+
+install 阶段是 KubeKey 的核心安装阶段，负责在集群节点上实际部署和配置 Kubernetes 集群，包括：
+
+**install nfs**: 为 `nfs` 组中的节点安装nfs服务。
+**install image_registry**: 为 `image_registry` 组中的节点安装镜像仓库。目前支持两种类型的镜像仓库：harbor，registry。
+**install etcd**: 为 `etcd` 组中的节点安装etcd。
+**install cri**: 为 `k8s_cluster` 组中的节点安装cri。目前支持两种CRI：docker，containerd。
+**kubernetes_install**: 为 `k8s_cluster` 组中的节点安装kubernetes。
+**install helm**: 为已安装好的kubernetes集群安装额外的helm 应用。包含：CNI（calico，cilium，flannel，hybridnet，kubeovn，multus）
+
+
+## post_hook
+
+post_hook 阶段在集群安装完成后执行，负责集群的最终配置和验证：
+
+执行流程：
+1. 复制本地目录的脚本文件到远程节点的 `/etc/kubekey/scripts/post_install_{{ .inventory_hostname }}.sh`
+2. 设置脚本文件权限为 0755
+3. 遍历每个远程节点上 `/etc/kubekey/scripts/` 目录下所有 `post_install_*.sh` 文件，并执行该脚本文件
+ 
+ > work_dir: 工作目录，默认当前命令执行目录。     
+ > inventory_hostname: Inventory.yaml 文件中定义的host对应的名称。
+