update docs

docs/00-集群规划和基础参数设定.md

@@ -7,7 +7,7 @@
 + etcd节点------x3 : 注意etcd集群必须是1,3,5,7...奇数个节点
 + master节点----x2 : 根据实际集群规模可以增加节点数，需要额外规划一个master VIP(虚地址)
 + lb节点--------x2 : 负载均衡节点两个，安装 haproxy+keepalived
-+ node节点------x3 : 真正应用负载的节点，根据需要增加机器配置和节点数
++ node节点------x3 : 真正应用负载的节点，根据需要提升机器配置和增加节点数
 
 **请注意对于多节点集群，请确保各节点时区设置一致，并使用ntp服务器同步各节点时间。**
 
@@ -116,14 +116,10 @@ mv bin/* /etc/ansible/bin
 tar zxvf basic_images_kubeasz_0.2.tar.gz -C /etc/ansible/down
 ```
 - 4.3 配置集群参数
+  - 4.3.1 必要配置：`cd /etc/ansible && cp example/hosts.m-masters.example hosts`, 然后实际情况修改此hosts文件
+  - 4.3.2 可选配置，初次使用可以不做修改，详见[配置指南](config_guide.md)
+  - 4.3.3 验证ansible 安装：`ansible all -m ping` 正常能看到节点返回 SUCCESS
 
-``` bash
-cd /etc/ansible
-cp example/hosts.m-masters.example hosts
-vim hosts                       # 根据实际情况修改此hosts文件
-# 验证ansible安装，正常能看到每个节点返回 SUCCESS
-ansible all -m ping
-```
 - 4.4 开始安装
 如果你对集群安装流程不熟悉，请阅读项目首页 **安装步骤** 讲解后分步安装，并对 **每步都进行验证**  
 

docs/config_guide.md

@@ -0,0 +1,27 @@
+# 个性化集群参数配置
+
+简单来说，对于刚接触项目者，如"快速指南"说明，只需要：
+
+- **1** 个配置：`/etc/ansible/hosts`
+- **1** 键安装：`ansible-playbook /etc/ansilbe/90.setup.yml`
+
+具体来讲 `kubeasz`创建集群主要在以下两个地方进行配置：
+
+- ansible hosts 文件（模板在examples目录）：集群主要节点定义和主要参数配置、全局变量
+- roles/xxx/vars/main.yml 文件：其他参数配置或者部分组件附加参数
+
+## ansible hosts
+
+项目在[快速指南](quickStart.md)或者[集群规划与安装概览](00-集群规划和基础参数设定.md)已经介绍过，主要包括集群节点定义和集群范围的主要参数配置；目前提供三种集群部署模板。
+
+- 尽量保持配置简单灵活
+- 尽量保持配置项稳定
+
+## roles/xxx/vars/main.yml
+
+主要包括集群某个具体组件的个性化配置，具体组件的配置项可能会不断增加；项目初始时该配置与默认配置(`roles/xxx/defaults/main.yml`)一致；因 ansilbe 变量优先级关系，后续如果对 roles/xxx/vars/main.yml变量修改，那么它将覆盖默认配置。
+
+- 需要初始化时使用 `ansible-playbook /etc/ansilbe/tools/init_vars.yml` 生成
+- 确保在不做任何配置更改情况下可以使用默认值创建集群
+- 被.gitignore忽略，修改后项目目录能够保持干净(`git status | clean`)
+

docs/guide/helm.md

@@ -33,7 +33,7 @@ Error: cannot connect to Tiller
 上述安装的tiller服务器默认允许匿名访问，那么k8s集群中的任何pod都能访问tiller，风险较大，因此需要在helm客户端和tiller服务器间建立安全的SSL/TLS认证机制；tiller服务器和helm客户端都是使用同一CA签发的`client cert`，然后互相识别对方身份。建议通过本项目提供的`ansible role`安装，符合官网上介绍的安全加固措施，在delpoy节点运行:  
 ``` bash
 # 1.如果已安装非安全模式，使用 helm reset 清理
-# 2.配置默认helm参数 vi /etc/ansible/roles/helm/defaults/main.yml
+# 2.配置默认helm参数 vi /etc/ansible/roles/helm/vars/main.yml
 # 3.执行安装
 $ ansible-playbook /etc/ansible/roles/helm/helm.yml
 ```

docs/op/upgrade.md

@@ -19,11 +19,18 @@ $ ETCDCTL_API=3 etcdctl --write-out=table snapshot status backup.db
 ### 升级步骤
 
 - 1.下载最新项目代码 `git pull origin master`（注意手动更新现有hosts的配置项与example中的实例一致）
+
 - 2.下载新的二进制解压并替换 `/etc/ansible/bin/` 目录下文件
-- 3a.如果可以接受短暂业务中断，执行 `ansible-playbook -t upgrade_k8s,restart_dockerd 22.upgrade.yml` 即可
-- 3b.如果要求零中断升级集群
-  - 首先执行 `ansible-playbook -t upgrade_k8s 22.upgrade.yml` (该步骤不会影响k8s上的业务应用)
-  - 然后逐个升级重启每个node节点的dockerd服务
-    - 待重启节点，先应用`kubectl cordon`和`kubectl drain`命令
+
+- 3a.如果不需要升级 docker版本：执行 `ansible-playbook -t upgrade_k8s 22.upgrade.yml` 即可完成k8s 升级，不会中断业务应用
+  - 注：确实不需要频繁去升级 docker
+
+- 3b.如果可以接受短暂业务中断，执行 `ansible-playbook -t upgrade_k8s,restart_dockerd 22.upgrade.yml` 即可升级 k8s和 docker(如果有新的docker二进制)
+
+- 3c.如果要求零中断升级 k8s和 docker
+  - i 执行 `ansible-playbook -t upgrade_k8s 22.upgrade.yml` (该步骤不会影响k8s上的业务应用)
+  - ii 逐个升级重启每个node节点的dockerd服务
+    - 待重启节点，先应用`kubectl cordon`和`kubectl drain`命令迁移业务pod
     - 待重启节点执行 `systemctl restart docker`
-    - 恢复待重启节点可调度 `kubectl uncordon`
+    - 恢复节点可调度 `kubectl uncordon`
+

docs/quickStart.md

@@ -88,14 +88,10 @@ mv bin/* /etc/ansible/bin
 tar zxvf basic_images_kubeasz_0.2.tar.gz -C /etc/ansible/down
 ```
 - 4.3 配置集群参数
+  - 4.3.1 必要配置：`cd /etc/ansible && cp example/hosts.allinone.example hosts`, 然后实际情况修改此hosts文件
+  - 4.3.2 可选配置，初次使用可以不做修改，详见[配置指南](config_guide.md)
+  - 4.3.3 验证ansible 安装：`ansible all -m ping` 正常能看到节点返回 SUCCESS
 
-``` bash
-cd /etc/ansible
-cp example/hosts.allinone.example hosts
-vim hosts			# 根据实际情况修改此hosts文件，所有节点改成本机IP
-# 验证ansible安装，正常能看到每个节点返回 SUCCESS
-ansible all -m ping
-```
 - 4.4 开始安装
 如果你对集群安装流程不熟悉，请阅读项目首页 **安装步骤** 讲解后分步安装，并对 **每步都进行验证**