docs update

2019-06-23 07:45:30 +08:00 · 2019-06-23 07:45:30 +08:00 · a3aff4a88d
parent a4215438fe
commit a3aff4a88d
4 changed files with 67 additions and 52 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 # ![kubeasz](pics/kubeasz.png)

-`kubeasz`致力于提供快速部署高可用`k8s`集群的工具, 同时也努力成为`k8s`实践、使用的参考书；基于二进制方式部署和利用`ansible-playbook`实现自动化；既提供一键安装脚本, 也可以根据[指南](docs/setup/00-planning_and_overall_intro.md)分步执行安装各个组件。
+项目致力于提供快速部署高可用`k8s`集群的工具, 同时也努力成为`k8s`实践、使用的参考书；基于二进制方式部署和利用`ansible-playbook`实现自动化；既提供一键安装脚本, 也可以根据`安装指南`分步执行安装各个组件。

 - **集群特性** `TLS`双向认证、`RBAC`授权、[多Master高可用](docs/setup/00-planning_and_overall_intro.md#ha-architecture)、支持`Network Policy`、备份恢复
 - **集群版本** kubernetes v1.8, v1.9, v1.10, v1.11, v1.12, v1.13, v1.14
@ -8,17 +8,17 @@
 - **运行时** docker 17.03.x-ce, 18.06.x-ce, 18.09.x, [containerd](docs/guide/containerd.md) 1.2.6
 - **网络** [calico](docs/setup/network-plugin/calico.md), [cilium](docs/setup/network-plugin/cilium.md), [flannel](docs/setup/network-plugin/flannel.md), [kube-ovn](docs/setup/network-plugin/kube-ovn.md), [kube-router](docs/setup/network-plugin/kube-router.md)

+请阅读[项目分支说明](docs/mixes/branch.md), 欢迎提[Issues](https://github.com/easzlab/kubeasz/issues)和[PRs](docs/mixes/HowToContribute.md)参与维护项目！感谢您的关注与支持！
+
 ## 快速指南

 单机快速体验k8s集群的测试、开发环境--[AllinOne部署](docs/setup/quickStart.md)

- 注：集群用到的所有二进制文件已打包好供下载 [https://pan.baidu.com/s/1c4RFaA](https://pan.baidu.com/s/1c4RFaA)
-
 ## 安装指南

 <table border="0">
    <tr>
-        <td><a href="docs/setup/00-planning_and_overall_intro.md">00-规划集群和安装概览</a></td>
+        <td><a href="docs/setup/00-planning_and_overall_intro.md">00-规划集群和配置介绍</a></td>
        <td><a href="docs/setup/02-install_etcd.md">02-安装etcd集群</a></td>
        <td><a href="docs/setup/04-install_kube_master.md">04-安装master节点</a></td>
        <td><a href="docs/setup/06-install_network_plugin.md">06-安装集群网络</a></td>
@ -33,7 +33,6 @@

 - 命令行工具 [easzctl介绍](docs/setup/easzctl_cmd.md)
 - 公有云自建集群 [部署指南](docs/setup/kubeasz_on_public_cloud.md)
- 容器部署集群 [使用kubeasz容器创建k8s集群（测试）](docs/setup/docker_kubeasz.md)

 ## 使用指南

@ -92,8 +91,6 @@

 ## 贡献&致谢

-请阅读[项目分支说明](docs/mixes/branch.md), 欢迎提[Issues](https://github.com/easzlab/kubeasz/issues)和[PRs](docs/mixes/HowToContribute.md)参与维护项目！感谢您的关注与支持！
-
 - [如何 PR](docs/mixes/HowToContribute.md)
 - [如何捐赠](docs/mixes/donate.md)

--- a/docs/mixes/branch.md
+++ b/docs/mixes/branch.md
@ -1,18 +1,29 @@
 # 项目分支说明

- 为减小维护压力，避免产生混淆，精简项目分支为：`master`, `dev`, `closed`, `release-0`; 原分支`v1.9`取消（可以直接更新至master分支），原分支`v1.8`更名为 `closed`并停止更新。
- 更新：
-  - kubeasz 0.6 及之前的版本已合并至 release-0 分支，后续停止更新，只做 bug 修复
-  - kubeasz 1.x 版本将在 master 分支更新发布
+为减小维护压力，避免产生混淆，精简项目分支为：`master`, `dev2`, `dev1`, `dev0`, `closed`; 分别对应发布版本如下：

-## 项目分支与百度网盘离线包关系
-
- `master` 分支目前支持k8s v1.8/v1.9/v1.10/v1.11/v1.12/v1.13 的集群安装，请使用 `k8s.1-x-x.tar.gz` 的安装包
- `dev` 分支同 `master`的离线安装包
- `closed` 分支请使用分享链接目录`old/`下的 `k8s.18x.tar.gz` 的安装包（已停止更新）
+- master 最新版本稳定分支（目前对应dev2）
+- dev2 对应 kubeasz 2.x 版本的开发分支
+- dev1 对应 kubeasz 1.x 版本的开发分支
+- dev0 对应 kubeasz 0.x 版本的开发分支（已停止更新）
+- closed 对应更老的版本分支（仅留档保存）

 ## 更新频率和内容 

 - `master` 为最新稳定分支，更新相对频繁：**相关文档**，**功能特性**，BUG修复，组件更新
 - `dev` 为开发测试分支，不一定稳定，更新频繁：**相关文档**，**功能特性**，BUG修复，组件更新
- `closed` 分支已停止更新：仅重要BUG修复，留档保存使用
+- `closed` 分支已停止更新：留档保存使用
+
+## 安装架构变化
+
+项目 0.x 1.x 与 2.x 版本的主要区别在于安装集群高可用架构不同；
+
+- ha-1x 架构是之前k8s社区推荐的高可用方式，也是最早实践的稳定方案
+
+![ha-1x](../../pics/ha-1x.gif)
+
+- ha-2x 架构是更方便、兼容性（云上云下）更好，是目前项目推荐的方案
+
+![ha-2x](../../pics/ha-2x.gif)
+
+因基础架构差异，用户对于已有集群，**切勿更新 kubeasz 不同版本**（不能从0.x 升级 1.x，或者 1.x 升级 2.x）；可以根据当时安装集群时所用的 kubeasz 版本进行 k8s 版本的升级；比如：使用版本 kubeasz 1.2.0 安装了 k8s v1.11.5 集群，可以按照文档把 k8s 升级到 v1.13.6，但是建议不要去升级 kubeasz 版本，特别不能升级 kubeasz 1.2.0 至 kubeasz 2.0.0。
--- a/docs/setup/docker_kubeasz.md
+++ b/docs/setup/docker_kubeasz.md
@ -2,66 +2,74 @@

 ## TL;DR;

- 1.本机安装 docker (略) 
+- 1.准备一台全新虚机作为管理节点（ansible控制端）
+```
+$ wget https://github.com/easzlab/kubeasz/releases/download/1.3.0/easzup
+$ chmod +x ./easzup
+$ ./easzup -D
+``` 
 - 2.配置 ssh 密钥登陆集群节点
-
 ``` bash
 ssh-keygen -t rsa -b 2048 回车 回车 回车
 ssh-copy-id $IP  # $IP 为所有节点地址包括自身，按照提示输入 yes 和 root 密码
 ```
-
- 3.下载 kubeasz docker 镜像并运行 (可能需较长时间下载镜像jmgao1983/kubeasz)
+- 3.容器化运行 kubeasz，然后执行安装 k8s 集群（举例aio集群）

 ``` bash
-curl -sfL https://github.com/easzlab/kubeasz/releases/download/1.0.0/kubeasz-docker-1.0.0 | bash -
-```
-
- 4.在 kubeasz 容器中创建 k8s 集群，步骤与非容器方式创建类似，快速创建单节点集群如下
-
-``` bash
-docker exec -it kubeasz easzctl start-aio
+$ ./easzup -S
+$ docker exec -it kubeasz easzctl start-aio
+# 若需要自定义集群创建，如下进入容器，然后配置/etc/ansible/hosts，执行创建即可
+# docker exec -it kubeasz sh
 ```

 ## 验证

 使用容器化安装成功后，可以在 **容器内** 或者 **宿主机** 上执行 kubectl 命令验证集群状态。

-## kubeasz 镜像介绍
+## easzup 工具介绍

-镜像描述文件 dockerfiles/kubeasz/Dockerfile，它基于 ansible 镜像（dockerfiles/ansible/Dockerfile），主要包含 kubeasz 项目代码和 k8s 集群安装所需二进制文件。
+初始化工具 tools/easzup 主要用于：

- 在本地创建 kubeasz 镜像，由于镜像较大，可以按以下步骤在本地创建
+- 下载 kubeasz 项目代码/k8s 二进制文件/其他所需二进制文件/离线docker镜像等
+- 【可选】容器化运行 kubeasz
+
+详见脚本内容
+
+### 容器化运行 kubeasz
+
+容器启动脚本详见文件 tools/easzup 中函数`start_kubeasz_docker`

 ``` bash
-cd /etc/ansible/dockerfiles/kubeasz
-# 克隆代码
-git clone --depth=1 https://github.com/easzlab/kubeasz.git
-# 手动下载二进制文件放入上述 git clone 完成目录 kubeasz/bin 
-docker build -t kubeasz:$TAG .
-```
-
-## 容器运行讲解
-
-容器启动脚本详见文件 tools/kubeasz_docker
-
-``` bash
-docker run --detach \
+  docker run --detach \
      --name kubeasz \
      --restart always \
-      --env HOST_IP=$host_ip \
+      --env HOST_IP="$host_ip" \
      --volume /etc/ansible:/etc/ansible \
      --volume /root/.kube:/root/.kube \
      --volume /root/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
      --volume /root/.ssh/id_rsa.pub:/root/.ssh/id_rsa.pub:ro \
      --volume /root/.ssh/known_hosts:/root/.ssh/known_hosts:ro \
-      $KUBEASZ_DOCKER_VER
+      easzlab/kubeasz:${KUBEASZ_VER}
 ```

- --env HOST_IP=$host_ip 传递这个参数是为了快速在本机安装aio集群
+- --env HOST_IP="$host_ip" 传递这个参数是为了快速在本机安装aio集群
 - --volume /etc/ansible:/etc/ansible 挂载本地目录，这样可以在宿主机上修改集群配置，然后在容器内执行 ansible 安装
 - --volume /root/.kube:/root/.kube 容器内与主机共享 kubeconfig，这样都可以执行 kubectl 命令
 - --volume /root/.ssh/id_rsa:/root/.ssh/id_rsa:ro 等三个 volume 挂载保证：如果宿主机配置了免密码登陆所有集群节点，那么容器内也可以免密码登陆所有节点

-## 参考
+## 清理

- ansible 容器镜像制作: https://github.com/William-Yeh/docker-ansible
+登陆管理节点，按照如下步骤清理（清理后可以重新安装测试）
+
+- 1.清理集群 `$ docker exec -it kubeasz easzctl destroy`
+- 2.清理管理节点
+  - 清理运行的容器 `$ easzup -C`
+  - 清理容器镜像 `$ docker system prune -a`
+  - 停止docker服务 `$ systemctl stop docker`
+  - 删除下载文件 `$ rm -rf /etc/ansible /etc/docker /opt/kube`
+  - 删除docker文件 
+```
+$ umount /var/run/docker/netns/default
+$ umount /var/lib/docker/overlay
+$ rm -rf /var/lib/docker /var/run/docker
+```
--- a/down/download.sh
+++ b/down/download.sh
@ -1,6 +1,6 @@
 #!/bin/bash
 # This script describes where to download the official released binaries needed
-# It's suggested to download the entire *.tar.gz at https://pan.baidu.com/s/1c4RFaA
+# It's suggested to download using 'tools/easzup -D', everything needed will be ready in '/etc/ansible'

 # example releases
 K8S_VER=v1.13.7
@ -11,8 +11,7 @@ DOCKER_COMPOSE_VER=1.23.2
 HARBOR_VER=v1.5.4
 CONTAINERD_VER=1.2.6

-echo -e "\nNote1: Before this script, please finish downloading binaries manually from following urls."
-echo -e "\nNote2：If binaries are not ready, use `Ctrl + C` to stop this script."
+echo -e "\nNote: It's suggested to download using 'tools/easzup -D', everything needed will be ready in '/etc/ansible'."

 echo -e "\n----download k8s binary at:"
 echo -e https://dl.k8s.io/${K8S_VER}/kubernetes-server-linux-amd64.tar.gz