安装步骤文档更新

README.md

@@ -30,15 +30,14 @@
 
 ## 安装步骤
 
-- [集群规划和基础参数设定](docs/00-集群规划和基础参数设定.md)
-- [创建CA证书和环境配置](docs/01-创建CA证书和环境配置.md)
+- [规划集群和安装概览](docs/00-集群规划和基础参数设定.md)
+- [创建证书和安装准备](docs/01-创建CA证书和环境配置.md)
 - [安装etcd集群](docs/02-安装etcd集群.md)
-- [配置kubectl命令行工具](docs/03-配置kubectl命令行工具.md)
 - [安装docker服务](docs/04-安装docker服务.md)
 - [安装kube-master节点](docs/05-安装kube-master节点.md)
 - [安装kube-node节点](docs/06-安装kube-node节点.md)
-- [安装calico网络组件](docs/07-安装calico网络组件.md)
-- [安装flannel网络组件](docs/07-安装flannel网络组件.md)
+- [安装calico网络](docs/07-安装calico网络组件.md)
+- [安装flannel网络](docs/07-安装flannel网络组件.md)
 
 ## 使用指南
 

docs/01-创建CA证书和环境配置.md

@@ -1,26 +1,37 @@
-# 01-创建CA证书和环境配置.md
+# 01-创建证书和环境配置.md
 
-本步骤[01.prepare.yml](../01.prepare.yml)主要完成CA证书创建、分发、环境变量、负载均衡配置等。
+本步骤[01.prepare.yml](../01.prepare.yml)主要完成:
+
+- 创建CA证书、kubeconfig、bootstrap.kubeconfig、kube-proxy.kubeconfig和kubedns配置
+- 分发CA证书、kubectl客户端安装、环境配置
+- 安装负载均衡
+
+## deploy 角色
+
+请在另外窗口打开[roles/deploy/tasks/main.yml](../roles/deploy/tasks/main.yml) 文件，对照看以下讲解内容。
 
 ### 创建 CA 证书和秘钥 
 ``` bash
-roles/deploy
+roles/deploy/
 ├── tasks
 │   └── main.yml
 └── templates
-    ├── ca-config.json.j2
-    └── ca-csr.json.j2
+    ├── admin-csr.json.j2	# kubectl客户端使用的证书请求模板
+    ├── ca-config.json.j2	# ca 配置文件模板
+    ├── ca-csr.json.j2		# ca 证书签名请求模板
+    ├── kubedns.yaml.j2
+    └── kube-proxy-csr.json.j2	# kube-proxy使用的证书请求模板
 ```
-kubernetes 系统各组件需要使用 TLS 证书对通信进行加密，使用 CloudFlare 的 PKI 工具集生成自签名的CA证书，用来签名后续创建的其它 TLS 证书。[参考阅读](https://coreos.com/os/docs/latest/generate-self-signed-certificates.html)
+kubernetes 系统各组件需要使用 TLS 证书对通信进行加密，使用 CloudFlare 的 PKI 工具集生成自签名的 CA 证书，用来签名后续创建的其它 TLS 证书。[参考阅读](https://coreos.com/os/docs/latest/generate-self-signed-certificates.html)
 
-根据认证对象可以将证书分成三类：服务器证书，客户端证书，对等证书 `peer cert`(表示既是`server cert`又是`client cert`)，在kubernetes 集群中需要的证书种类如下：
+根据认证对象可以将证书分成三类：服务器证书`server cert`，客户端证书`client cert`，对等证书`peer cert`(表示既是`server cert`又是`client cert`)，在kubernetes 集群中需要的证书种类如下：
 
-+ `etcd` 节点需要标识自己监听服务的server cert，也需要client cert与`etcd`集群其他节点交互，当然可以分别指定2个证书，这里为简化使用一个peer 证书
-+ `kube-apiserver` 需要标识apiserver服务的server cert，也需要client cert 从而操作`etcd`集群，这里为简化使用一个peer 证书
-+ `kubectl` `calico` `kube-proxy` 只需要 client cert，因此证书请求中 hosts 字段可以为空
-+ `kubelet` 证书比较特殊，不是手动生成，它由node节点`TLS BootStrap` 向`apiserver`请求，由master节点的`controller-manager` 自动签发，包含一个client cert 和一个server cert
++ `etcd` 节点需要标识自己服务的`server cert`，也需要`client cert`与`etcd`集群其他节点交互，当然可以分别指定2个证书，也可以使用一个对等证书
++ `master` 节点需要标识 apiserver服务的`server cert`，也需要`client cert`连接`etcd`集群，这里也使用一个对等证书
++ `kubectl` `calico` `kube-proxy` 只需要`client cert`，因此证书请求中 `hosts` 字段可以为空
++ `kubelet` 证书比较特殊，不是手动生成，它由node节点`TLS BootStrap` 向`apiserver`请求，由`master`节点的`controller-manager` 自动签发，包含一个`client cert` 和一个`server cert`
 
-请在另外窗口打开[roles/deploy/tasks/main.yml](../roles/deploy/tasks/main.yml) 文件，对照看以下讲解内容。
+整个集群要使用统一的CA 证书，只需要在 deploy 节点创建，然后分发给其他节点；为了保证安装的幂等性，如果已经存在CA 证书，就跳过创建CA 步骤
 
 #### 创建 CA 配置文件 [ca-config.json.j2](../roles/deploy/templates/ca-config.json.j2)
 ``` bash
@@ -43,10 +54,10 @@ kubernetes 系统各组件需要使用 TLS 证书对通信进行加密，使用
   }
 }
 ```
-+ `ca-config.json`：可以定义多个 profiles，分别指定不同的过期时间、使用场景等参数；这里为了方便使用 `kubernetes` 这个profile 签发三种不同类型证书
 + `signing`：表示该证书可用于签名其它证书；生成的 ca.pem 证书中 `CA=TRUE`；
-+ `server auth`：表示 client 可以用该 CA 对 server 提供的证书进行验证；
-+ `client auth`：表示 server 可以用该 CA 对 client 提供的证书进行验证；
++ `server auth`：表示可以用该 CA 对 server 提供的证书进行验证；
++ `client auth`：表示可以用该 CA 对 client 提供的证书进行验证；
++ `profile `kubernetes` 包含了`server auth`和`client auth`，所以可以签发三种不同类型证书；
 
 #### 创建 CA 证书签名请求 [ca-csr.json.j2](../roles/deploy/templates/ca-csr.json.j2)
 ``` bash
@@ -72,59 +83,132 @@ kubernetes 系统各组件需要使用 TLS 证书对通信进行加密，使用
 ``` bash
 cfssl gencert -initca ca-csr.json | cfssljson -bare ca
 ```
-+ 注意整个集群只能有一个CA证书和配置文件，所以下一步要分发给每一个节点，包括calico/node也需要使用，`ansible` 角色(role) `prepare` 会完成CA 证书分发，所以把ca 证书相关先复制到 `roles/prepare/files/`
 
-#### 准备分发 CA证书
+### 生成 kubeconfig 配置文件
+
+kubectl使用~/.kube/config 配置文件与kube-apiserver进行交互，且拥有管理 K8S集群的完全权限，
+
+准备kubectl使用的admin 证书签名请求 [admin-csr.json.j2](../roles/deploy/templates/admin-csr.json.j2)
+
+``` bash
+{
+  "CN": "admin",
+  "hosts": [],
+  "key": {
+    "algo": "rsa",
+    "size": 2048
+  },
+  "names": [
+    {
+      "C": "CN",
+      "ST": "HangZhou",
+      "L": "XS",
+      "O": "system:masters",
+      "OU": "System"
+    }
+  ]
+}
+
+```
++ kubectl 使用客户端证书可以不指定hosts 字段
++ 证书请求中 `O` 指定该证书的 Group 为 `system:masters`，而 `RBAC` 预定义的 `ClusterRoleBinding` 将 Group `system:masters` 与 ClusterRole `cluster-admin` 绑定，这就赋予了kubectl**所有集群权限
+**
+
+``` bash
+$ kubectl describe clusterrolebinding cluster-admin
+Name:         cluster-admin
+Labels:       kubernetes.io/bootstrapping=rbac-defaults
+Annotations:  rbac.authorization.kubernetes.io/autoupdate=true
+Role:
+  Kind:  ClusterRole
+  Name:  cluster-admin
+Subjects:
+  Kind   Name            Namespace
+  ----   ----            ---------
+  Group  system:masters  
+```
+
+使用`kubectl config` 生成kubeconfig 自动保存到 ~/.kube/config，生成后 `cat ~/.kube/config`可以验证配置文件包含 kube-apiserver 地址、证书、用户名等信息。
+
+### 生成 bootstrap.kubeconfig 配置文件
+
++ 注意 kubelet bootstrapping认证时是靠 token的，后续批准节点后 (kubectl certificate approve)，由 `master`为其生成证书和私钥
+
+### 生成 kube-proxy.kubeconfig 配置文件
+
+创建 kube-proxy 证书请求
+
+``` bash
+{
+  "CN": "system:kube-proxy",
+  "hosts": [],
+  "key": {
+    "algo": "rsa",
+    "size": 2048
+  },
+  "names": [
+    {
+      "C": "CN",
+      "ST": "HangZhou",
+      "L": "XS",
+      "O": "k8s",
+      "OU": "System"
+    }
+  ]
+}
+```
++ kube-proxy 使用客户端证书可以不指定hosts 字段
++ CN 指定该证书的 User 为 system:kube-proxy，预定义的 ClusterRoleBinding system:node-proxier 将User system:kube-proxy 与 Role system:node-proxier 绑定，授予了调用 kube-apiserver Proxy 相关 API 的权限；
 
 ``` bash
-- name: 准备分发 CA证书
-  copy: src={{ ca_dir }}/{{ item }} dest={{ base_dir }}/roles/prepare/files/{{ item }} force=no
-  with_items:
-  - ca.pem
-  - ca-key.pem
-  - ca.csr
-  - ca-config.json
+$ kubectl describe clusterrolebinding system:node-proxier
+Name:         system:node-proxier
+Labels:       kubernetes.io/bootstrapping=rbac-defaults
+Annotations:  rbac.authorization.kubernetes.io/autoupdate=true
+Role:
+  Kind:  ClusterRole
+  Name:  system:node-proxier
+Subjects:
+  Kind  Name               Namespace
+  ----  ----               ---------
+  User  system:kube-proxy  
 ```
-+ force=no 保证整个安装的幂等性，如果已经生成过CA证书，就使用已经存在的CA，可以多次运行 `ansible-playbook 90.setup.yml` 
-+ 如果确实需要更新CA 证书，删除/roles/prepare/files/ca* 可以使用新CA 证书
 
 ### kubedns.yaml 配置生成
 
 + kubedns.yaml文件中部分参数(CLUSTER_DNS_SVC_IP, CLUSTER_DNS_DOMAIN)根据hosts文件设置而定，因此需要用template模块替换参数
 + 运行本步骤后，在 manifests/kubedns目录下生成 kubedns.yaml 文件，以供后续部署时使用
 
+## prepare 角色
+
 ``` bash
 roles/prepare/
 ├── files
 │   ├── 95-k8s-sysctl.conf
-│   ├── ca-config.json
-│   ├── ca.csr
-│   ├── ca-csr.json
-│   ├── ca-key.pem
-│   └── ca.pem
 └── tasks
     └── main.yml
 ```
 请在另外窗口打开[roles/prepare/tasks/main.yml](../roles/prepare/tasks/main.yml) 文件，比较简单直观
 
 1. 首先创建一些基础文件目录
 1. 修改环境变量，把{{ bin_dir }} 添加到$PATH，需要重新登陆 shell生效
-1. 把证书工具 CFSSL下发到指定节点
+1. 把证书工具 CFSSL 和 kubectl 下发到指定节点，并下发kubeconfig配置文件
 1. 把CA 证书相关下发到指定节点的 {{ ca_dir }} 目录
 1. 最后设置基础操作系统软件和系统参数，请阅读脚本中的注释内容
 
-### LB 负载均衡部署
+## LB 角色-负载均衡部署
 ``` bash
 roles/lb
 ├── tasks
 │   └── main.yml
 └── templates
     ├── haproxy.cfg.j2
+    ├── haproxy.service.j2
     ├── keepalived-backup.conf.j2
     └── keepalived-master.conf.j2
 ```
 
-Haproxy支持四层和七层负载，稳定性好，根据官方文档，HAProxy可以跑满10Gbps-New benchmark of HAProxy at 10 Gbps using Myricom's 10GbE NICs (Myri-10G PCI-Express)，这个作为软件级负载均衡，也是比较惊人的；另外，openstack高可用也有用haproxy的。
+Haproxy支持四层和七层负载，稳定性好，根据官方文档，HAProxy可以跑满10Gbps-New benchmark of HAProxy at 10 Gbps using Myricom's 10GbE NICs (Myri-10G PCI-Express)；另外，openstack高可用也有用haproxy的。
 
 keepalived观其名可知，保持存活，它是基于VRRP协议保证所谓的高可用或热备的，这里用来预防haproxy的单点故障。
 

docs/02-安装etcd集群.md

@@ -16,6 +16,8 @@ kuberntes 系统使用 etcd 存储所有数据，是最重要的组件之一，
 
 ### 创建etcd证书请求 [etcd-csr.json.j2](../roles/etcd/templates/etcd-csr.json.j2)
 
+首先判断下是否etcd 证书已经存在，如果已经存在就跳过证书生成步骤
+
 ``` bash
 {
   "CN": "etcd",
@@ -38,7 +40,7 @@ kuberntes 系统使用 etcd 存储所有数据，是最重要的组件之一，
   ]
 }
 ```
-+ hosts 字段指定授权使用该证书的 etcd 节点 IP
++ etcd使用对等证书，hosts 字段必须指定授权使用该证书的 etcd 节点 IP
 
 ### 创建证书和私钥
 
@@ -126,4 +128,4 @@ https://192.168.1.3:2379 is healthy: successfully committed proposal: took = 3.2
 三台 etcd 的输出均为 healthy 时表示集群服务正常。
 
 
-[前一篇](01-创建CA证书和环境配置.md) -- [后一篇](03-配置kubectl命令行工具.md)
+[前一篇](01-创建CA证书和环境配置.md) -- [后一篇](04-安装docker服务.md)