diff --git a/README.md b/README.md index d1f32ab37..7501334cd 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,14 @@ kubean is a cluster lifecycle management tool based on [kubespray](https://githu --- -## Awesome features +## :anchor: 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 +## :surfing_man: Quick Start #### 1. Ensure that a Kubernetes Cluster exists and Helm installed @@ -79,11 +80,9 @@ We cloud use the example in folder `artifacts/demo` which uses online resources [![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) +## :book: Documents +- [Architecture](docs/zh/architecture.md) +- [Kubean vs Kubespray](docs/zh/comparisons.md) +- [CRD Outline](docs/zh/crds.md) +- [Deploy cluster using SSH secret key method](docs/zh/sshkey_deploy_cluster.md) +- [Cluster deployment for air gap environments](docs/offline.md) diff --git a/docs/offline.md b/docs/offline.md index cbbacf23b..a92b55c1f 100644 --- a/docs/offline.md +++ b/docs/offline.md @@ -1,5 +1,7 @@ # Offline Usage +> English | [中文](zh/offline.md) + The `kubean` project can be divided into three functions, `generating offline package` , `importing offline package to minio and registry` and `installing k8s`. diff --git a/docs/airgap_patch_usage.md b/docs/zh/airgap_patch_usage.md similarity index 100% rename from docs/airgap_patch_usage.md rename to docs/zh/airgap_patch_usage.md diff --git a/docs/architecture_zh.md b/docs/zh/architecture.md similarity index 93% rename from docs/architecture_zh.md rename to docs/zh/architecture.md index e59b62a35..bebbff916 100644 --- a/docs/architecture_zh.md +++ b/docs/zh/architecture.md @@ -2,13 +2,13 @@ Kubean 的整体架构如下所示： -![kubean-architecture](images/kubean-architecture.png) +![kubean-architecture](../images/kubean-architecture.png) Kubean 需要运行在一个已存在的 Kubernetes 集群，通过应用 Kubean 提供的标准 CRD 资源和 Kubernetes 内建资源来控制和管理集群的生命周期（安装、卸载、升级、扩容、缩容等）。 Kubean 采用 Kubespray 作为底层技术依赖，一方面简化了集群部署的操作流程，降低了用户的使用门槛。另一方面在 Kubespray 能力基础上增加了集群操作记录、离线版本记录等诸多新特性。
-![kubean-components](images/kubean-components.png) +![kubean-components](../images/kubean-components.png) Kubean 运行着多个控制器，这些控制器跟踪 Kubean CRD 对象的变化，并且与底层集群的 API 服务器进行通信来创建 Kubernetes原生资源对象。由以下四个组件构成： diff --git a/docs/comparisons_zh.md b/docs/zh/comparisons.md similarity index 100% rename from docs/comparisons_zh.md rename to docs/zh/comparisons.md diff --git a/docs/crds_zh.md b/docs/zh/crds.md similarity index 97% rename from docs/crds_zh.md rename to docs/zh/crds.md index 2b8b5dd8b..6c9d383bd 100644 --- a/docs/crds_zh.md +++ b/docs/zh/crds.md @@ -27,11 +27,11 @@ spec: #### 属性关联 -- `hostConfRef`：hostConfRef 是一个 ConfigMap 资源，它的内容应满足 ansible inventory 的格式，包含集群节点信息、类型分组信息。内容可参考 [demo](../artifacts/demo/hosts-conf-cm.yml) +- `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) +- `varsConfRef`：varsConfRef 是一个 ConfigMap 资源，用作初始化或覆盖 Kubespray 中声明的变量值。如果有离线需求，这将很有用。内容可参考 [demo](../../artifacts/demo/vars-conf-cm.yml) - `name`：表示其引用的 ConfigMap 的名称 - `namespace`：表示其引用的 ConfigMap 所在的命名空间 diff --git a/docs/offline_zh.md b/docs/zh/offline.md similarity index 99% rename from docs/offline_zh.md rename to docs/zh/offline.md index 9ca01d1d4..046b0248a 100644 --- a/docs/offline_zh.md +++ b/docs/zh/offline.md @@ -294,4 +294,4 @@ nerdctl_download_url: "{{ files_repo }}/github.com/containerd/nerdctl/releases/d ## 增量离线包的生成和使用 -详细文档见[airgap_patch_usage](airgap_patch_usage.md) +详细文档见: [Air gap patch usage](airgap_patch_usage.md). diff --git a/docs/zh/sshkey_deploy_cluster.md b/docs/zh/sshkey_deploy_cluster.md new file mode 100644 index 000000000..6541f3a12 --- /dev/null +++ b/docs/zh/sshkey_deploy_cluster.md @@ -0,0 +1,199 @@ +# :key: 使用 SSH 秘钥方式部署 K8S 集群 + +## 内容 + +* ✓ [1. SSH 秘钥的生成与分发](#SSH秘钥的生成与分发) +* ✓ [2. 使用私钥制作 Secret](#使用私钥制作Secret) +* ✓ [3. 创建主机清单配置](#创建主机清单配置) +* ✓ [3. 制备部署集群的配置参数](#制备部署集群的配置参数) +* ✓ [4. 准备 KuBean 的自定义资源](#准备KuBean的自定义资源) +* ✓ [5. 开始部署集群](#开始部署集群) + +## SSH秘钥的生成与分发 + +1. 通过 `ssh-keygen` 命令生成公私钥对，比如： +``` bash +$ ssh-keygen +Generating public/private rsa key pair. +Enter file in which to save the key (/root/.ssh/id_rsa): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /root/.ssh/id_rsa. +Your public key has been saved in /root/.ssh/id_rsa.pub. +The key fingerprint is: +SHA256:XBSD2HY1Lp8ZRfTC82cFEXzW/BRgEMd+SWiKzBNSUHN root@localhost.localdomain +The key's randomart image is: ++---[RSA 2048]----+ +| +B=E*XO*O.| +| . =X =o=O.=| +| .oo o oo++o| +| + = + .+| +| S . .| +| | +| | +| | +| | ++----[SHA256]-----+ + +$ ls /root/.ssh/id_rsa* -lh +-rw-------. 1 root root 1.7K Nov 10 03:47 /root/.ssh/id_rsa # 私钥 +-rw-r--r--. 1 root root 408 Nov 10 03:47 /root/.ssh/id_rsa.pub # 公钥 +``` + +2. 分发公钥到集群的各个节点： +``` bash +# 比如指定将公钥分发至 `192.168.10.11` `192.168.10.12` 两个节点 +$ declare -a IPS=(192.168.10.11 192.168.10.12) + +# 遍历节点 IP 分发公钥，假设用户名为: root, 密码为: kubean +$ for ip in ${IPS[@]}; do sshpass -p "kubean" ssh-copy-id -o StrictHostKeyChecking=no root@$ip; done +``` + +## 使用私钥制作Secret + +1. 通过 kubectl 命令可以生成私钥的 Secret: +``` bash +$ kubectl -n kubean-system \ # 指定命名空间 kubean-system + create secret generic sample-ssh-auth \ # 指定 secret 名称为 sample-ssh-auth + --type='kubernetes.io/ssh-auth' \ # 指定 secret 类型为 kubernetes.io/ssh-auth + --from-file=ssh-privatekey=/root/.ssh/id_rsa \ # 指定 ssh 私钥文件路径 + --dry-run=client -o yaml > ssh_auth_sec.yaml # 指定 secret yaml 文件生成路径 +``` + +2. 生成的 Secret YAML 内容大致如下所示： +``` yaml +apiVersion: v1 +kind: Secret +metadata: + creationTimestamp: null + name: sample-ssh-auth + namespace: kubean-system +type: kubernetes.io/ssh-auth +data: + ssh-privatekey: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlKS1FJQkFBS0NBZ0VBdWVDbC8rSng1b0RT... +``` + +## 创建主机清单配置 + +示例：主机清单 hosts_conf_cm.yaml 内容大致如下： +``` yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: sample-hosts-conf + namespace: kubean-system +data: + hosts.yml: | + all: + hosts: + master: + ip: 192.168.10.11 + access_ip: 192.168.10.11 + ansible_host: 192.168.10.11 + worker: + ip: 192.168.10.12 + access_ip: 192.168.10.12 + ansible_host: 192.168.10.12 + children: + kube_control_plane: + hosts: + master: + kube_node: + hosts: + master: + worker: + etcd: + hosts: + master: + k8s_cluster: + children: + kube_control_plane: + kube_node: + calico_rr: + hosts: {} +``` + +> 注： 由于采用私钥登录，所以主机信息中不需要填写用户名密码(即: ansible_user、ansible_password) + +## 制备部署集群的配置参数 + +集群配置参数 vars_conf_cm.yaml 的内容，可以参考: [demo vars conf](../../artifacts/demo/vars-conf-cm.yml). +``` yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: sample-vars-conf + namespace: kubean-system +data: + group_vars.yml: | + container_manager: containerd + kube_network_plugin: calico + kube_network_plugin_multus: false + kube_proxy_mode: iptables + enable_nodelocaldns: false + etcd_deployment_type: kubeadm + ntp_enabled: true + ... +``` + +## 准备KuBean的自定义资源 + +1. Cluster 自定义资源内容示例 +``` yaml +apiVersion: kubean.io/v1alpha1 +kind: Cluster +metadata: + name: sample +spec: + hostsConfRef: + namespace: kubean-system + name: sample-hosts-conf + varsConfRef: + namespace: kubean-system + name: sample-vars-conf + sshAuthRef: # 关键属性，指定集群部署期间的 ssh 私钥 secret + namespace: kubean-system + name: sample-ssh-auth +``` + +2. ClusterOperation 自定义资源内容示例 +``` yaml +apiVersion: kubean.io/v1alpha1 +kind: ClusterOperation +metadata: + name: sample-create-cluster +spec: + cluster: sample + 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 +``` + +## 开始部署集群 + +假设我们的所有 yaml 清单都存放在 create_cluster 目录 +``` bash +$ tree create_cluster/ +create_cluster +├── hosts_conf_cm.yml # 主机清单 +├── ssh_auth_sec.yml # SSH私钥 +├── vars_conf_cm.yml # 集群参数 +├── kubeanCluster.yml # Cluster CR +└── kubeanClusterOps.yml # ClusterOperation CR +``` + +通过 kubectl apply 开始部署集群: +``` bash +$ kubectl apply -f create_cluster/ +```