文档

• 1: 概述
• 2: 快速开始
• 2.1: 部署 AIO
• 2.2: 使用 Kubeclipper 离线创建 kubernetes 集群
• 2.3: 制作 K8S 组件离线安装包
• 3: 部署文档
• 3.1: 部署高可用 KubeClipper
• 4: 使用手册
• 4.1: 创建集群
• 4.2: 集群托管
• 4.3: 集群管理
• 4.4: 节点管理
• 4.5: 访问控制
• 5: 常见问题
• 5.1: 通过 kcctl 命令创建集群错误
• 6: 贡献指南

1 - 概述

KubeClipper 是什么？

KubeClipper 旨在提供易使用、易运维、极轻量、生产级的 Kubernetes 多集群全生命周期管理服务，让运维工程师从繁复的配置和晦涩的命令行中解放出来，实现一站式管理跨区域、跨基础设施的多 kubernetes 集群。

为什么需要 KubeClipper？

云原生时代，Kubernetes 已毋庸置疑地成为容器编排的事实标准。虽然有诸多辅助 kubernetes 集群安装和管理的工具，但搭建和运维一套生产级别的 kubernetes 集群仍然十分复杂。九州云在大量的服务和实践过程中，沉淀出一个极轻量、易使用的图形化界面 Kubernetes 多集群管理工具—— KubeClipper。

KubeClipper 在完全兼容原生 Kubernetes 的前提下，基于社区广泛使用的 kubeadm 工具进行二次封装，提供在企业自有基础设施中快速部署 kubernetes 集群和持续化全生命周期管理（安装、卸载、升级、扩缩容、远程访问等）能力，支持在线、代理、离线等多种部署方式，还提供了丰富可扩展的 CRI、CNI、CSI、以及各类 CRD 组件的管理服务。

与现有的 Sealos、KubeKey、Kubeasz、KubeOperator、K0S 等 kubernetes 生命周期管理工具相比，KubeClipper 更贴近开放原生、轻量便捷、稳定易用。

• 快速开始: Learn how to get started with Kubeclipper
• 用户手册: Check out some example code!

KubeClipper 架构设计

核心架构

KubeClipper 分为三个部分：

• kc-server：原则上部署在独立节点，负责收集节点上报信息，分发前端操作任务至指定 kc-agent 并汇总执行结果等，是 KubeClipper 控制核心。
• kc-agent: 部署在纳管节点，通过消息队列（内置 nats）与 kc-server 通信，负责上报节点信息以及处理下发任务并执行，是 KubeClipper 节点代理工具。
• kcctl: KubeClipper 的终端命令行工具，可快捷高效的部署、管理 KubeClipper 集群，能够替代大多数页面操作。

节点纳管

部署网络模型

KubeClipper 支持可以通过参数配置来部署分层网络模型，以下是不同网络的概要：

运维管理网络(Management Network):
在 kcctl deploy 部署 KubeClipper 集群时，可通过 --ip-detect 参数指定网卡接口，默认为 first-found。 该网卡接口对应的 IP 地址即是 kc-server 与 kc-agent 的路由地址。

K8S 主机网络(K8S Host Network):
在 kcctl deploy 部署 KubeClipper 集群时，可通过 --node-ip-detct 参数指定网卡接口，默认继承 --ip-detect 参数值，亦可独立设置。 该网卡接口对应的 IP 地址即是 K8S 的节点路由地址。

K8S Pod 网络(SDN Pod Network):
在安装 K8S 集群时，可通过填入 CNI 的 POD 网路底层 指定网卡接口，默认为 first-found。 该网卡接口对应的 IP 地址即是 K8S POD 网路底层的路由地址。

2 - 快速开始

对于初次接触 KubeClipper 并想快速上手的用户，建议使用 All-in-One 安装模式，它能够帮助您零配置快速部署 KubeClipper。

准备工作

KubeClipper 本身并不会占用太多资源，但是为了后续更好的运行 Kubernetes 建议硬件配置不低于最低要求。

您仅需参考以下对机器硬件和操作系统的要求准备一台主机。

硬件推荐配置

• 确保您的机器满足最低硬件要求：CPU >= 2 核，内存 >= 2GB。
• 操作系统：CentOS 7.x / Ubuntu 18.04 / Ubuntu 20.04。

节点要求

• 节点必须能够通过 SSH 连接。
• 节点上可以使用 sudo / curl / wget / tar 命令。

建议您的操作系统处于干净状态（不安装任何其他软件），否则可能会发生冲突。

部署 KubeClipper

下载 kcctl

KubeClipper 提供了命令行工具🔧 kcctl 以简化运维工作，您可以直接使用以下命令下载最新版 kcctl：

# curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | bash -
# 如果你在中国， 你可以在安装时使用 cn  环境变量, 此时我们会使用 registry.aliyuncs.com/google_containers 代替 k8s.gcr.io
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -

您也可以在 GitHub Release Page 下载指定版本。

通过以下命令检测是否安装成功:

kcctl version

开始安装

在本快速入门教程中，您只需执行一个命令即可安装 KubeClipper，其模板如下所示：

kcctl deploy

若使用 ssh passwd 方式则命令如下所示:

kcctl deploy --user root --passwd $SSH_PASSWD

私钥方式如下：

kcctl deploy --user root --pk-file $SSH_PRIVATE_KEY

您只需要提供 ssh user 以及 ssh passwd 或者 ssh 私钥即可在本机部署 KubeClipper。

执行该命令后，Kcctl 将检查您的安装环境，若满足条件将会进入安装流程。在打印出如下的 KubeClipper banner 后即表示安装完成。

 _   __      _          _____ _ _
| | / /     | |        /  __ \ (_)
| |/ / _   _| |__   ___| /  \/ |_ _ __  _ __   ___ _ __
|    \| | | | '_ \ / _ \ |   | | | '_ \| '_ \ / _ \ '__|
| |\  \ |_| | |_) |  __/ \__/\ | | |_) | |_) |  __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
                                 | |   | |
                                 |_|   |_|

登录控制台

安装完成后，打开浏览器，访问 http://$IP 即可进入 KubeClipper 控制台。

您可以使用默认帐号密码 admin / Thinkbig1 进行登录。

您可能需要配置端口转发规则并在安全组中开放端口，以便外部用户访问控制台。

创建 kubernetes 集群

部署成功后您可以使用 kcctl 工具或者通过控制台创建 kubernetes 集群。在本快速入门教程中使用 kcctl 工具进行创建。

首先使用默认帐号密码进行登录获取 token，便于后续 kcctl 和 kc-server 进行交互。

kcctl login -H http://localhost -u admin -p Thinkbig1

然后使用以下命令创建 kubernetes 集群:

NODE=$(kcctl get node -o yaml|grep ipv4DefaultIP:|sed 's/ipv4DefaultIP: //')

kcctl create cluster --master $NODE --name demo --untaint-master

大概 3 分钟左右即可完成集群创建,也可以使用以下命令查看集群状态

kcctl get cluster -o yaml|grep status -A5

您也可以进入控制台查看实时日志。

进入 Running 状态即表示集群安装完成,您可以使用 kubectl get cs 命令来查看集群健康状况。

2.1 - 部署 AIO

对于初次接触 KubeClipper 并想快速上手的用户，建议使用 AIO（即 All-in-One，使用单个节点安装 KubeClipper）模式，它能够帮助您零配置快速部署 KubeClipper。

部署 KubeClipper

下载并安装 kcctl

KubeClipper 提供了命令行工具🔧 kcctl 以简化运维工作，您可以直接使用以下命令下载最新版 kcctl：

# 默认安装最新的发行版
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | bash -
# 安装指定版本
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_VERSION=v1.3.1 bash -
# 如果您在中国， 您可以在安装时使用 cn  环境变量, 此时 KubeClipper 会使用 registry.aliyuncs.com/google_containers 代替 k8s.gcr.io
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -

您也可以在 GitHub Release Page 下载指定版本。

可以通过以下命令验证 kcctl 是否安装成功:

# 如果一切顺利，您将看到 kcctl 版本信息
kcctl version

开始安装

您可以使用 kcctl deploy 快速安装部署 KubeClipper。kcctl 使用 SSH 访问最终部署 KubeClipper 的目标节点，因此需要您提供 SSH 访问凭证，传递凭证的方法如下：

Kcctl deploy [--user <username>] [--passwd <password> | --pk-file <private key path>]

示例：

# 使用私钥
kcctl deploy --user root --pk-file /root/.ssh/id_rsa
# 使用密码
kcctl deploy --user root --passwd password

执行 kcctl deploy 命令 kcctl 将会检查您的安装环境，若满足条件将自动进入安装流程。若您看到如下 KubeClipper banner 后即表示安装成功。

 _   __      _          _____ _ _
| | / /     | |        /  __ \ (_)
| |/ / _   _| |__   ___| /  \/ |_ _ __  _ __   ___ _ __
|    \| | | | '_ \ / _ \ |   | | | '_ \| '_ \ / _ \ '__|
| |\  \ |_| | |_) |  __/ \__/\ | | |_) | |_) |  __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
                                 | |   | |
                                 |_|   |_|

您也可以部署 master 版本的 KubeClipper，来体验最新的功能特性（master 版本没有经过严格验证，可能包含影响体验的未知错误）

1. 安装 master 版本 kcctl

curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_VERSION=master bash -

2. 在安装服务器上设置环境变量

export KC_VERSION=master

3. 以 AIO 方式部署 KubeClipper

kcctl deploy

登录控制台

安装完成后，打开浏览器，访问 http://<kc-server ip address> 即可进入 KubeClipper 控制台。(通常 kc-server ip 是您部署 kubeClipper 节点的 ip)

您可以使用默认帐号密码 admin / Thinkbig1 进行登录。

您可能需要配置端口转发规则并在安全组中开放端口，以便外部用户访问控制台。

创建 Kubernetes 集群

部署成功后您可以使用 kcctl 工具或者通过控制台创建 Kubernetes 集群。在本快速入门教程中使用 kcctl 工具进行创建。

首先使用默认帐号密码进行登录获取 token，便于后续 kcctl 和 kc-server 进行交互。

kcctl login -H https://<kc-server ip address>:8080 -u admin -p Thinkbig1

通过以下命令创建 Kubernetes 集群:

NODE=$(kcctl get node -o yaml|grep ipv4DefaultIP:|sed 's/ipv4DefaultIP: //')

kcctl create cluster --master $NODE --name demo --untaint-master

大概 3 分钟左右即可完成集群创建,您可以使用以下命令查看集群状态

kcctl get cluster -o yaml|grep status -A5

您也可以进入控制台查看实时日志。

集群处于 Running 状态即表示集群安装完成,您可以使用 kubectl get cs 命令来查看集群健康状况。

2.2 - 使用 Kubeclipper 离线创建 kubernetes 集群

1. 进入创建界面

登录 Kubeclipper 平台后点击如图所示按钮，进入集群创建界面

2. 配置集群节点

按照文字提示完成输入集群名称、选择节点等步骤

注意: master 节点数量不能为偶数

3. 配置集群

此步骤用于配置集群网络以及数据库、容器运行时等组件

选择离线安装并填写首先搭建好的镜像仓库地址

4. 配置存储

选择 nfs 存储，按照文字提示填写相应内容

5. 安装完成

完成所有配置确认安装

安装成功，集群正常运行

2.3 - 制作 K8S 组件离线安装包

本文档介绍如何制作 K8S 组件离线安装包，对于没有外网的环境，可以通过离线安装包进行安装。

当前 kubeclipper v1.4 版本离线部署包中仅包含以下 K8S 组件：

• k8s: v1.27.4
• containerd: v1.6.4
• calico: v3.26.1

对于有特殊需求的用户，可以通过本文档介绍的方法自行制作离线组件包，然后在 kubeclipper 中使用。

1. 准备工作

按照 文档 部署好 kubeclipper，确保 kcctl 命令可以正常使用。

kcctl version

以下操作均在 kubeclipper 部署节点上执行，使用 kcctl resource 命令进行组件包上传。

2. 确认组件版本

根据以下两个表格信息，确认需要制作的组件包版本，使用推送脚本或者手动上传组件包到 kubeclipper。

k8s 组件包表 记录当前对象存储里已制作好的各类组件包，后续我们将逐步开源更多组件包以及打包脚本。
k8s 版本与组件推荐版本对应关系表 记录了各个 k8s 版本对应的组件版本，可以根据自己的需求选择对应的组件版本。

k8s 版本与组件推荐版本对应关系表

k8s 组件包表

3. 推送离线组件包到 kubeclipper

push_component.sh 脚本：

#!/usr/bin/env bash
# usage: ./push_component.sh [component] [version] [arch]
# usage: ./push_component.sh k8s v1.23.9 amd64

set -e

if type kcctl &>/dev/null; then
  kcctl version
else
  echo "kcctl command not found, please install it first!"
fi

PKG_URL_PREFIX="https://oss.kubeclipper.io/packages"
fileList=()

name=$1
if [[ "${name}" != "k8s" ]] && [[ "${name}" != "calico" ]] && [[ "${name}" != "containerd" ]] && [[ "${name}" != "docker" ]] && [[ "${name}" != "metallb" ]]; then
  echo "only 'k8s', 'calico','containerd','docker','metallb' packages are supported. default: $name"
  exit 1
fi
version=$2
if [[ -z "${version}" ]]; then
  echo "Please specify the package version!"
  exit 1
fi
arch=$3
if [[ "${arch}" != "amd64" ]] && [[ "${arch}" != "arm64" ]]; then
  echo "only 'amd64', 'arm64' architectures are supported. default: $arch"
  exit 1
fi
``
build_dir=${name}/${version}/${arch}
pkg_name=${name}-${version}-${arch}.tar.gz
pkg_type="k8s"

packaging() {
  case $name in
  k8s)
    fileList=(
      images.tar.gz
      configs.tar.gz
      manifest.json
    )
    pkg_type="k8s"
    ;;
  calico)
    fileList=(
      images.tar.gz
      manifest.json
    )
    if [[ "$(echo -e "3.26\n${version}" | sort -V | tail -n 1)" == "${version}" ]]; then
      fileList=(
        images.tar.gz
        charts.tgz
        manifest.json
      )
    fi
    pkg_type="cni"
    ;;
  containerd,docker)
    fileList=(
      configs.tar.gz
      manifest.json
    )
    pkg_type="cri"
    ;;
  metallb)
    fileList=(
      images.tar.gz
      manifest.json
    )
    pkg_type="metallb"
    ;;
  esac

  for file in "${fileList[@]}"; do
    echo "download ${file}..."
    wget ${PKG_URL_PREFIX}/${build_dir}/${file} -P ${build_dir}
  done

  echo "packaging ${pkg_name}..."
  tar -zcvf ${pkg_name} ${build_dir}
  echo "packaging ${pkg_name} done"
  echo "push ${pkg_name} to kc..."
  kcctl resource push --pkg ${pkg_name} --type ${pkg_type}
  echo "push ${pkg_name} to kc done"
}

packaging
echo "clean up..."
rm -rf ${build_dir}
rm -rf ${pkg_name}
echo "clean up done"

使用 push_component.sh 脚本推送组件包到 kubeclipper：

chmod +x push_component.sh

# 推送 k8s 组件包
./push_component.sh k8s v1.23.9 amd64

# 推送 calico 组件包
./push_component.sh calico v3.22.4 amd64

# 推送 containerd 组件包
./push_component.sh containerd v1.6.4 amd64

# 推送 docker 组件包
./push_component.sh docker 20.10.20 amd64

# 推送 metallb 组件包
./push_component.sh metallb v0.13.7 amd64

4. 查看离线组件包

使用 kcctl resource list 命令查看已上传的离线组件包：

kcctl resource list

5. 使用离线组件包

登录 kubeclipper 控制台，点击创建集群，进入集群配置页，镜像类型选择离线，即可选择已上传的离线组件包。

3 - 部署文档

3.1 - 部署高可用 KubeClipper

对于初次接触 KubeClipper，建议部署 AIO 环境，快速上手体验 KubeClipper 提供的功能特性。 对于想将 KubeClipper 应用到生成环境，那么本文档或许对您有所帮助。

概述

根据 KubeClipper 架构设计可知，KubeClipper 有以下 4 个核心组件：

• kc-server：主要包括 APISERVER 、控制器、静态资源服务以及内置消息队列等，kc-server 通过消息队列（支持外置）与 kc-agent 通信；kc-server 之间无主从关系，且相互独立；通常部署在独立的节点，从而对外提供稳定可靠的服务。
• kc-agent：主要包括任务处理器，负责接收 kc-server 投递的任务，并反馈任务处理结果；通常部署在需要安装 kubernetes 的节点，是一个超轻量级的服务进程。
• kc-etcd：kc-server 的后端数据库，跟随 kc-server 部署在同一节点上。
• kc-dashboard：图形化管理界面，跟随 kc-server 部署在同一节点。 综上，我们将部署 kc-server 的节点称为 server，部署 kc-agent 的节点称为 agent。

那么部署高可用 KubeClipper 集群的关键点，就在于如何规划部署 server 节点同时保证 kc-etcd 的高可用。 通常来看，对于部署高可用的分布式应用集群，基本建议节点至少 3 个；同样对于 KubeClipper，3 个节点能保证 kc-server 在其中 2 个节点宕机后依旧可以提供服务，同时能保证 kc-etcd 不会出现脑裂异常。

以上简单介绍了 KubeClipper 架构以及核心组件，是为了更好的理解该如何部署高可用 KubeClipper 集群，从而引出关于对服务器节点规划以及硬件配置要求的思考。

推荐配置

KubeClipper 作为一个极轻量的 Kubernetes 多集群全生命周期管理工具，本身不会占用太多资源

server 节点

• 数量：3 个及以上
• 硬件要求：CPU >= 2 核，内存 >= 2GB，硬盘 >= 20GB
• 系统：CentOS 7.x / Ubuntu 18.04 / Ubuntu 20.04

agent 节点

• 数量：任意
• 硬件要求：依据实际需求而定
• 系统：CentOS 7.x / Ubuntu 18.04 / Ubuntu 20.04

从安装 kcctl 开始

kcctl 是 KubeClipper 提供的命令行工具，它支持快速部署 KubeClipper 集群以及大部分 Kuberneters 集群管理功能，用以简化运维工作。

安装 kcctl：

# 默认安装最新发行版
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | bash -

# 安装指定版本
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_VERSION=v1.3.1 bash -

# 如果您在中国，您可以在安装时指定 KC_REGION 环境变量，此时我们会使用 registry.aliyuncs.com/google_containers 代替 k8s.gcr.io
# 这对于在线安装 k8s 集群非常有用
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -

安装成功后，会输出安装版本以及安装路径等信息。

您也可以在 GitHub Release Page 下载指定的 kcctl 版本

验证安装：

kcctl version -o json

kcctl version:
{
"major": "1",
"minor": "3",
"gitVersion": "v1.3.1",
"gitCommit": "5f19dcf78d3a9dc2d1035a779152fa993e0553df",
"gitTreeState": "clean",
"buildDate": "2022-12-02T10:12:36Z",
"goVersion": "go1.19.2",
"compiler": "gc",
"platform": "linux/amd64"
}

# 查看帮助文档
kcctl -h

了解 kcctl deploy 命令

kcctl deploy 命令是专门用于部署 KubeClipper 集群，更多示例以及参数解释请执行 kcctl deploy -h

常用参数简介

• –server: server 节点 IP，例如 192.168.10.10,192.168.10.11，多个 IP 以逗号隔开。
• –agent: agent 节点 IP，例如 192.168.10.10,192.168.10.11，多个 IP 以逗号隔开。
• –pk-file: ssh 免密登录私钥，推荐在命令行使用免密登录。
• –user: ssh 登录用户名，默认为 root。
• –passwd: ssh 登录密码，不推荐在命令行使用密码登录。
• –pkg: 安装包路径，支持本地路径以及在线链接；获取在线安装包链接规则：https://oss.kubeclipper.io/release/{KC_VERSION}/kc-{GOARCH}.tar.gz 。KC_VERSION 为 Release Version 默认设置当前 kcctl 对应版本，GOARCH 为 amd64 或 arm64，默认设置当前 kcctl 的编译架构。
• –ip-detect: 节点 ip 发现规则，支持多种规则，例如指定网卡名称等，对于多网卡节点非常有用，默认为 “first-found”。

了解完 kcctl deploy 的基础使用，那么接下来就开始部署 KubeClipper 集群吧。

使用 kcctl 部署 KubeClipper

我们推荐在多节点安装场景中，将涉及到的服务器节点都统一设置免密登录，避免密码明文泄露。

私钥方式部署 3 server 节点：

kcctl deploy --pk-file=~/.ssh/id_rsa \
--server SERVER_IPS \
--pkg https://oss.kubeclipper.io/release/{KC_VERSION}/kc-{GOARCH}.tar.gz

私钥方式部署 3 server + 3 agent 节点，指定 pkg：

kcctl deploy --pk-file=~/.ssh/id_rsa \
--server SERVER_IPS \
--agent AGENT_IPS \
--pkg https://oss.kubeclipper.io/release/{KC_VERSION}/kc-{GOARCH}.tar.gz

私钥方式部署 3 server + 3 agent 节点，未指定 pkg，默认与 kcctl 安装版本一致（推荐）：

kcctl deploy --pk-file=~/.ssh/id_rsa \
--server SERVER_IPS \
--agent AGENT_IPS

私钥方式部署 3 server + 3 agent 节点，指定 etcd 端口，默认端口为 client-12379 | peer-12380 | metrics-12381：

kcctl deploy --pk-file=~/.ssh/id_rsa \
--server SERVER_IPS \
--agent AGENT_IPS \
--etcd-port 12379 --etcd-peer-port 12380 --etcd-metric-port 12381

参数输入示例：
SERVER_IPS: 192.168.10.20,192.168.10.21
AGENT_IPS: 192.168.10.30,192.168.10.31
KC_VERSION: KubeClipper 的 release version，查看 GitHub Release Page 获取
GOARCH：系统架构，amd64 （又名 x84_64），arm64（又名 aarch64）

kcctl deploy 支持多种参数，能够满足您对部署 KubeClipper 集群的特定需求，更多功能等您探索。
在执行 kcctl deploy 命令后，命令会检测您的环境是否符合安装要求，会将警告信息、安装进度等同步输出到控制台，最后在安装成功后会打印如下 KubeClipper banner：

 _   __      _          _____ _ _
| | / /     | |        /  __ \ (_)
| |/ / _   _| |__   ___| /  \/ |_ _ __  _ __   ___ _ __
|    \| | | | '_ \ / _ \ |   | | | '_ \| '_ \ / _ \ '__|
| |\  \ |_| | |_) |  __/ \__/\ | | |_) | |_) |  __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
                                 | |   | |
                                 |_|   |_|

系统默认管理账号：admin / Thinkbig1

登录控制台： 打开浏览器，访问 http://SERVER_IP （通过任意一个 Server 节点均可访问）即可进入 KubeClipper 控制台

登录命令行：

kcctl login -H http://SERVER_IP -u admin -p Thinkbig1

大多数 kcctl 命令都依赖登录状态，因此最好在执行 cli 命令时提前登录。

使用 kcctl 添加 agent 节点到 KubeClipper

当前 kcctl join 命令仅支持添加 agent 节点，后续会逐步支持添加 server 节点。 新加入的 agent 节点也应该统一设置免密登录，且私钥相同。

Join agent 节点：

kcctl join --agent=AGENT_IPS

使用 kcctl 从 KubeClipper 中删除 agent 节点

当前 kcctl drain 命令仅支持删除 agent 节点，后续会逐步支持删除 server 节点。

Drain agent 节点：

kcctl drain --agent=AGENT_IPS

# 强制 drain 节点，忽略错误
kcctl drain --agent=AGENT_IPS --force

如果您发现根据本文档无法成功部署 KubeClipper，请移步 KubeClipper Github Issue，提出您的意见或反馈。

4 - 使用手册

4.1 - 创建集群

创建集群准备工作

1. 您需要准备充足的可用节点，如需添加节点，参见“添加节点”教程。
2. 准备好需要部署的 kubernetes、CRI、calico、CSI 和其他插件的镜像或二进制文件，kubeclipper 提供了推荐的版本，您可以根据平台所处网络环境，选择在线 / 离线后，直接在页面上选取使用。您也可以将部署所需的镜像上传至自己的镜像仓库，并在部署时指定。更多安装配置，参考“集群配置”章节。

创建单节点实验集群

1. 点击“集群管理”>“集群”，进入集群列表页面，点击左上角“创建集群”按钮。

2. 进入创建集群向导页面的“节点配置”页面。填写“集群名称”，如 “test”，不需选择“集群模版”。选择一个可用节点，添加为控制节点，并在污点管理列表中，将 master 节点的污点移除。点击“下一步”按钮。

3. 进入创建集群向导页面的“集群配置”页面。选择“离线安装”，“镜像仓库”不需填写，其他配置都可使用默认配置，点击“快速创建”按钮，跳转配置确认页面，点击“确认”按钮。

4. 单节点的实验集群创建完成，您可以在集群详情页查看集群详情，也可以点击“查看日志”按钮，查看集群创建过程中的实时日志。

使用镜像仓库创建集群

如果创建的集群中包含较大的镜像，推荐您将所有镜像上传到特定的镜像仓库，创建集群会更快速更顺畅。

1. 添加镜像仓库。点击“集群管理”>“镜像仓库”，进入镜像仓库列表页面，点击左上角“添加”按钮。在添加镜像仓库的弹窗中输入镜像仓库名称和存放有镜像的仓库地址，点击“确定”按钮。
2. 创建集群。点击“集群管理”>“集群”，进入集群列表页面，点击左上角“创建集群”按钮。按需配置集群节点，在“集群配置”页面的“镜像仓库”中，选择第一步添加的镜像仓库，根据需要完成集群其他配置后创建集群。

使用集群模版创建集群

您可以使用集群模版，简化集群创建流程。

1. 添加模版。保存模版有两种方式，您可以在“集群管理”>“模版管理”页面，添加集群模版，以备创建集群时使用。也可以点击集群操作中的“更多”>“保存为模版”，将已存在的集群配置保存为模版，以便创建出和该集群同等配置的 kubernetes 集群。
2. 创建集群。点击“集群管理”>“集群”，进入集群列表页面，点击左上角“创建集群”按钮，进入创建集群页面，填写“集群名称”，如 “demo”，选择第一步中保存的集群模版，添加所需节点，点击右下角“快速创建”按钮，跳转至“配置确认”页面，核对模版信息无误后，点击“确认”按钮，创建集群。

集群配置指南

节点配置

在节点配置页面，您可以对节点进行以下配置：

• 区域：集群所属区域，添加节点时可为节点指定物理的或逻辑的区域，使用该区域下节点创建的 kubernetes 集群也属于该区域，不支持使用跨区域的多个节点创建集群。
• 控制节点：为集群指定奇数个的控制节点，生产环境一般使用3个控制节点以实现高可用。
• 工作节点：根据业务规模，为新集群添加工作节点。
• 污点管理：您可以为已添加的节点配置污点，kubeclipper 会自动为控制节点添加不允许调度（noschedule）的污点，您也可以根据需要进行更改。
• 节点标签：您可以根据需要为已添加的集群节点配置标签。

您可以按业务需要配置所需节点。如果需要创建非高可用的实验集群，也可以仅添加一个控制节点，并将控制节点自动添加的污点移除，详细操作参见“创建单节点实验集群”。

集群配置

在集群配置页面，您可以对集群进行以下配置：

• 安装方式和镜像仓库：

• kubernetes 版本：指定集群 kubernetes 版本。当您选择离线安装的时候，可以从当前环境中配置包的 kubernetes 版本中选择；当您选择在线安装的时候，可以从 kubeclipper 官方推荐的版本中选择。

• ETCD 数据目录：可指定 ETCD 数据目录，默认为/var/lib/etcd。

• kubelet 数据目录：可指定 kubelet 数据目录，默认为 /var/lib/kubelet。

• CertSANs：kubernetes 集群 ca 证书签名的 ip 或者域名，可填写多个。

• 容器运行时：根据指定 kubernetes 版本，kubernetes 版本在 v1.20.0 之前，容器运行时默认 docker，之后默认 containerd；v1.24.0 之后不支持 docker。

• 容器运行时版本：指定 containerd / docker 版本。与 kubernetes 相同，当您选择离线安装的时候，可以从当前环境中配置包的版本中选择；当您选择在线安装的时候，可以从 kubeclipper 官方推荐的版本中选择。

• Containerd 数据目录：可填写 config.toml 配置中的 root dir，默认为/var/lib/containerd。

• Docker 数据目录：可填写 daemon.json 配置中的 root dir，默认为/var/lib/docker。

• Containerd 镜像仓库：存放 containerd 镜像的仓库地址，config.toml 配置中的 registry.mirrors，可填写多个。

• Docker 镜像仓库：存放 docker 镜像的仓库地址，daemon.json 配置中的 insecure registry,可填写多个。

• DNS 域名：kubernetes 集群的域名，默认为 cluster.local。

• Worker 负载 IP：用于 worker 节点到多 master 的负载均衡，单一 master 不需要设置。

• 外部访问 IP：可以填写一个浮动 IP 给用户访问，可为空。

• 备份空间：集群备份文件存储位置。

CNI 配置

当前版本仅支持 Calico 作为集群 CNI。

Calico 将用户设置的 pod cidr 分为若干个 block (网段)，根据业务需求动态的分配给需要的节点，并在节点中通过 bgp peer 维护集群节点的路由表。

例如：容器的地址池：172.25.0.0/16，动态分配的网段池: 172.25.0.0 - 172.25.255.192 (172.25.0.0/26 即 10 个比特位)，动态分配的网段数: 1023，每个网段的 pod 数量为: 61 (193-254)，总 pod 数量为1023 * 61 = 62403，相对最大节点数(按照200业务 pod 为基准值)：312。

目前不建议大于50个节点的集群，大于50个节点的集群建议手动配置 route reflection，用来优化集群中的节点的路由表维护的稳定性。

使用 Calico 作为集群 CNI，您需要进行以下配置：

• Calico 模式：支持5种网络模式：

  • Overlay-IPIP-All: 使用 IP-in-IP 技术打通不同节点的 pod 的网络,通常这样的方式使用在底层平台是 iaas 的环境之中,当然如果你底层网路环境直接是物理设备的也完全可以使用只不过效率和灵活度都会大打折扣,需要注意的是你需要确认底层网络环境(underlay)是支持 IPIP 协议的.(使用 overlay 的网络方式对网络性能造成一定的影响)。
  • Overlay-Vxlan-All: 使用 IP-in-IP 技术打通不同节点的 pod 的网络,通常这样的方式使用在底层平台是 iaas 的环境之中,当然如果你底层网路环境直接是物理设备的也完全可以使用只不过效率和灵活度都会大打折扣,他理论上可以在任何的网络环境上运行,通常在底层环境不支持 IPIP 协议的时候我们会使用他.(使用 overlay 的网络方式对网络性能造成一定的影响)。
  • BGP: 使用 IP-in-IP 技术打通不同节点的 pod 的网络,通常这样的方式使用在裸机的环境上,当然底 Iaas 平台支持 BGP 的话也是可以使用的,这种模式下 pod 的 ip 通信是通过 集群中的各个节点中互相交换路由表来完成 pod 之间的通信的,如果你需要手动打通多个集群之间的 pod 网络需要注意你分配的地址断不应该有冲突。
  • Overaly-IPIP-Cross-Subnet: 使用 IP-in-IP 技术打通不同节点的 pod 的网络,通常这样的方式使用在底层平台是 iaas 的环境之中,需要注意的是你需要确认底层网络环境(underlay)是支持 IPIP 协议的.和 Overlay-IPIP-All 的不同之处在于,如果 2 个不同节点但在同一个网段中的上 pod 互相通信时是通过路由表,这样可以提高在不同节点但在同一个网段中的上 pod 互相通信时的效率。
  • Overaly-Vxlan-Cross-Subnet: 和 Overaly-IPIP-Cross-Subnet 逻辑相似不再做重复的解释。

• Calico 版本：指定 calico 版本。与 kubernetes 相同，当您选择离线安装的时候，可以从当前环境中配置包的版本中选择；当您选择在线安装的时候，可以从 kubeclipper 官方推荐的版本中选择。

• IP版本：可指定 IP 版本为 IPV4 或 IPV4 IPV6 双栈。

• 服务子网：填写 service 子网 CIDR，v4 默认为：10.96.0.0/16，v6 默认为 fd03::/112，注意 Service 网络不得与任何主机网络重叠。

• Pod CIDR：填写 Pod 子网 CIDR，v4 默认：172.25.0.0/24，v6 默认为 fd05::/120，注意 Pod 网络不得与任何主机网络重叠。

• pod网路的底层：

  • first-found（默认）：程序会根据 ipfamily (v4 或 v6)遍历所有的有效的 ip 地址（local,loop back，docker bridge等会被自动排除）通常如果是多网卡时会排除默认网关以外的网卡的 ip 作为节点之间的路由地址。
  • can-reach：通过检查域名或者 ip 的可达性来设置节点之间的路由地址。
  • interface：根据正则表达式获取所有满足的网卡设备名称并返回第一个满足表达式网卡的地址作为节点之间的路由地址。

• MTU：为 Calico 环境配置最大传输单元(MTU)，建议不大于1440，默认为1440，详情见 https://docs.projectcalico.org/networking/mtu。

存储配置

Kubeclipper当前版本内置了 NFS 作为集群外接存储。

对接 NFS 类型的外接存储，您需要设置以下内容：

设置完外接存储后，下方卡片会显示您已经开启的存储，您可以选择一个存储类作为默认存储，对于未指定特定StorageClass 的 PVC ，会直接使用默认的存储类。

配置确认

您可以在配置确认页面浏览集群的配置信息，确认无误后，点击“确认“按钮。也可以点击卡片右侧的“编辑”按钮，跳回到相应步骤修改集群信息。

安装集群可能需要较长时间，您可以在集群详情页面查看操作日志，跟踪集群安装状态。

设置国内镜像代理（可选）

Q: 设置国内镜像代理有什么作用？

A: 设置了国内镜像代理，使用在线安装功能时，会从指定代理拉取 kubernetes 相关镜像，避免在国内无法访问 gcr 而导致集群安装失败问题。

以下设置方法需在执行 kcctl deploy 部署命令的机器上完成，任选其一即可。

**方式一：**设置 KC_IMAGE_REPO_MIRROR 环境变量（推荐）

# 设置环境变量，推荐使用阿里云镜像代理，您也可以自行设定
export KC_IMAGE_REPO_MIRROR="registry.aliyuncs.com/google_containers"

**方式二：**设置 /etc/kc/kc.env 环境变量文件

# 创建 kc 目录
mkdir -pv /etc/kc

# 创建 kc.env 文件并传入环境变量信息
cat <<EOF > /etc/kc/kc.env
KC_IMAGE_REPO_MIRROR="registry.aliyuncs.com/google_containers"
EOF

4.2 - 集群托管

Kubeadm 集群托管

托管由 kubeadm 创建和管理的 kubernetes 集群，kubeclipper 会通过 kubeconfig 文件，获取集群和节点信息，并导入到 kubeclipper 平台中。

点击“集群管理”>“集群托管”按钮进入集群托管页面，点击左上角“添加”按钮，在添加提供商弹窗中，填写提供商名称（如 kubeadm-demo）和描述后，填写以下信息：

• 区域：提供商下的集群和节点在 kubeclipper 平台中的所属区域。
• 提供商类型：选择 kubeadm。
• 节点连接方式：集群节点的连接方式，可以选择“私钥”或者“密码”，您需要确保可以通过所选方式 ssh 到集群节点。
  • 选择“私钥”，需要输入节点用户名和私钥信息。
  • 选择“密码”，需要输入节点用户名和密码信息。
• 集群名称：作为在本平台的展示名称，不能与其他集群重复。
• KubeConfig：托管集群的 KubeConfig 文件。

填写完成后点击“确定”按钮，将集群和节点导入到平台中。点击提供商名称（kubeadm-demo），进入提供商详情页，您可以查看提供商下的集群，并对提供商执行以下操作：

• 同步：系统将每隔4小时定期同步集群信息，您也可以点击“同步”按钮手动执行。
• 编辑：编辑提供商的名称、描述、访问信息、节点连接方式。
• 移除：移除集群信息，但集群不会被卸载。

托管集群管理

您可以点击“集群管理”>“集群”进入集群列表页面，查看包括托管集群和本地集群在内的所有集群列表，对于不同集群，支持的管理操作如下表所示：

注意：托管的 kubeadm 集群安装插件或外接存储的镜像来源会默认使用 docker.io，如果您处于离线环境，需要在安装插件时填写可访问的离线镜像仓库地址，该离线镜像仓库的地址需要预先添加到 cri 的私有镜像仓库配置，参见 CRI 镜像仓库配置 。

4.3 - 集群管理

集群操作日志查看

在集群详情页面，点击“操作日志”标签页，可以查看集群操作日志列表。点击操作日志右侧“查看日志”按钮，可以在弹窗中查看全部步骤和节点的详细日志。点击左侧步骤名称，可查看执行步骤详细的日志输出。

在集群操作执行过程中，点击查看日志，您可以实时查看到日志更新来跟踪操作执行情况。对于执行失败的任务，您也可以通过查看日志，找到红色圆点标注的执行步骤和节点，快速定位错误，排查操作失败原因。

任务失败后重试

对于任务执行失败，但排查错误原因后不需要修改任务参数的情况，您可以点击操作日志右侧的“从断点处重试”按钮，从断点处重新执行任务。

注意：重试操作并不是万能的，您需要自行判断任务执行失败的原因，处理后如果不需要更改执行任务时填写的参数，就可以点击重试按钮，从错误处重新开始执行。

集群操作（如创建、恢复、升级等）执行失败，可能会导致集群状态显示为“xx失败”并无法正常执行其他操作，如果从断点处重试也无法执行成功，您可以参考运维文档，手动修复集群问题。问题修复后，您可以点击集群右侧“更多”>“集群状态”>“重置状态”按钮，重置集群至正常状态。

访问集群 kubectl

Kubectl 是 Kubernetes 命令行工具，您可以用它在 Kubernetes 集群上运行命令。Kubectl 可用于部署应用、查看和管理集群资源、查看日志等。

您可以访问运行中集群的 kubectl，点击集群操作中的“更多“>”访问 kubectl”，就可以在集群 kuebectl 弹窗中执行 kubectl 命令行操作。

集群设置

编辑

您可以点击集群列表右侧“更多”>“集群设置”>“编辑”按钮，编辑集群描述、备份空间、外部访问 IP、集群标签信息。

保存为模版

您可以点击集群列表右侧“更多”>“集群设置”>“保存为模版”按钮，将集群信息保存为模版，以便再次创建相似配置的集群时使用。

CRI 镜像仓库配置

Docker 和 Containerd 使用 dockerhub 作为默认镜像仓库，如果您需要使用其他镜像仓库（特别是使用自签名 https 仓库或者 http 仓库），您需要配置 CRI 镜像仓库。

点击集群右侧“更多”>“集群设置”>“CRI 镜像仓库”按钮，在 CRI 镜像仓库弹窗中，配置您需要的镜像仓库，您可以选择平台中已存在的镜像仓库，也可以临时填写镜像仓库地址。对于自签名 https 仓库或者 http 仓库，建议您先在“集群管理”>“镜像仓库”页面添加仓库信息，再在此操作中配置。

集群节点管理

在集群详情页的“节点”列表页面，您可以查看当前集群中的节点列表，节点的规格、状态和角色信息。

添加集群节点

当集群负载较高时，您可以通过为集群添加节点来达到主动扩容的目的，添加新的“节点”不会影响现有的业务的运行。

在集群详情页的节点列表标签页下，点击左侧的“添加节点”按钮，在弹窗中选择可用节点，设置节点标签，点击“确认”按钮。当前版本仅支持添加工作节点。

移除集群节点

在集群详情页的节点列表标签页下，您可以点击节点右侧的 “移除”按钮移除节点。当前版本仅支持移除工作节点。

注意：移除集群节点，您需要注意生产中的安全问题，避免应用发生中断。

集群备份和恢复

KubeClipper 对 kubernetes 集群的备份主要为备份 ETCD 数据库数据，以及 kubernetes 的资源对象备份，如 namespace，deployment、configMap。对资源自身产生的文件和数据不做备份，例如对集群中运行的 mysql pod，该 mysql pod 产生的数据和文件，不会为之备份，同理，文件类的 pv 对象下的文件，也不做备份，仅仅备份 pv 这个对象。KubeClipper 提供的备份功能是热备份，备份期间不影响集群的使用。KubeClipper 虽然不反对在集群 “繁忙期” 备份，但也强烈不赞成在集群 “繁忙期” 备份。

创建备份空间

执行备份之前，您需要先为集群设置备份空间，即设置备份文件的存储位置。备份空间的存储类型可以是 FS 存储或 S3 存储，下面以节点本地存储、NFS 存储和 MINIO 存储为例：

• 节点本地存储（仅适用单节点实验集群）：

1. 创建存储目录。连接集群 master 节点终端（可参见连接节点终端），使用 mkdir 命令，在 master 节点中创建“/root/backup”目录。
2. 创建备份空间。点击“集群管理”>“备份空间”，进入备份空间列表页，点击右上角“创建”按钮，在创建备份空间弹窗中，输入“备份空间名称”，如 “local”，选择“存储类型”为 “FS”，填写“备份路径”，如 “/root/backup”。
3. 设置集群备份空间。创建集群时，在“集群配置”页面选择“备份空间”为 “local”，或者编辑已有集群，在编辑集群弹窗中的“备份空间”中选择 “local”。

注意：使用本地节点存储备份文件，不需要引入外部存储，缺点是如果本地节点遭到破坏，备份文件也会丢失，所以强烈不赞成在生产环境中使用。

• NFS：

1. 准备 NFS 存储。准备一台 NFS 服务，并在 NFS 服务器上创建一个用于存放备份文件的目录，如 “/data/kubeclipper/cluster-backups”。

2. 挂载存储目录。连接集群 master 节点终端（可参见连接节点终端），使用 mkdir 命令，在每个 master 节点中创建 “/data/kubeclipper/cluster-backups” 目录，并 mount 到 NFS 服务器的 /data/kubeclipper/cluster-backups 目录即可。

   命令示例：

   mount -t nfs { NFS_IP }:/data/kubeclipper/cluster-backups /opt/kubeclipper/cluster-backups -o proto=tcp -o nolock
   

3. 创建备份空间。点击“集群管理”>“备份空间”，进入备份空间列表页，点击右上角“创建”按钮，在创建备份空间弹窗中，输入“备份空间名称”，如 “nfs”，选择“存储类型”为 “FS”，填写“备份路径”为 “/opt/kubeclipper/cluster-backups”。

4. 设置集群备份空间。创建集群时，在“集群配置”页面选择“备份空间”为 “nfs”，或者编辑已有集群，在编辑集群弹窗中的“备份空间”中选择 “nfs”。

• MINIO：

1. 准备 MINIO 存储。搭建 MINIO 服务，部署过程参考官网 https://docs.min.io/docs/minio-quickstart-guide.html，也可以使用已有 MINIO 服务。
2. 创建备份空间。点击“集群管理”>“备份空间”，进入备份空间列表页，点击右上角“创建”按钮，在创建备份空间弹窗中，输入“备份空间名称”，如 “minio”，选择“存储类型”为 “S3”，填写 “bucket 名称”，如 “kubeclipper-backups”，该 bucket 将由 kubeclipper 自动创建，“Endpoint” 中填写第一步 MINIO 存储服务的 ip 和端口号，填写服务用户名和密码，点击“确定”按钮。
3. 设置集群备份空间。创建集群时，在“集群配置”页面选择“备份空间”为 “minio”，或者编辑已有集群，在编辑集群弹窗中的“备份空间”中选择“minio”。

您可以在“集群管理”的“备份空间”页面查看所有备份空间列表和详细信息，并执行以下操作：

• 编辑：编辑备份空间描述，和 S3 类型备份空间的用户名/密码。

• 删除：删除备份空间，备份空间下存在备份文件的，不允许删除。

集群备份

您可以点击集群操作中的“更多”>“备份和恢复”> “集群备份”按钮，备份集群 ETCD 数据。

您可以在集群详情页面的备份标签页下，查看当前集群的所有备份文件，还可以对备份执行以下操作：

• 编辑：编辑备份描述。

• 恢复：执行集群恢复操作，将集群恢复至指定备份状态。

• 删除：删除指定备份文件。

定时备份

您也可以为集群创建定时备份，点击集群操作中的“更多”>“备份和恢复”> “定时备份”按钮，在定时备份弹窗中，输入定时备份名称、执行类型（重复执行/仅执行一次）和执行时间，并为重复执行的定时备份设置有效备份个数，点击“确认”按钮。

kubeClipper 会在您设置的执行时间为集群执行备份任务，备份文件会自动命名为“集群名称-定时备份名称-随机码”，对于重复执行的定时备份，kubeClipper 会在该定时任务下的备份文件超过有效备份个数时，自动删除超出个数的较早的备份文件。

定时备份添加完成后，可以在集群详情页的“定时备份”标签页查看定时备份信息，也可以在“备份”标签页查看定时备份产生的备份文件。

对于定时备份任务，您还可以执行以下操作：

• 编辑：编辑定时备份任务执行时间，和重复执行的定时备份的有效备份个数。

• 启用/禁用：禁用的定时备份任务将暂时停止执行。

• 删除：删除定时备份任务。

集群备份恢复

如果您在集群正常运行期间执行恢复操作，则 KubeClipper 将对该集群进行覆盖式恢复，就是备份文件里面的 etcd 数据，覆盖现有的数据。

您可以在集群详情页的备份标签页下，点击备份右侧的 “恢复”按钮；或点击集群操作中的“更多”>“备份和恢复”>“恢复集群”按钮，在恢复集群弹窗中选择需要恢复的备份，可以将当前集群恢复至指定备份状态。

注意：集群升级后，将无法再恢复到升级前版本的备份。

集群状态

集群版本升级

如当集群版本不满足需要，您可以为集群升级 kubernetes 版本。与创建集群一样，您需要准备好集群版本所需配置包和目标版本的 kubernetes 镜像并上传至指定位置，详情参见创建集群准备工作。

点击集群操作的“更多”>“集群状态”> “集群升级”按钮，在集群升级弹窗中选择安装方式和镜像仓库，选择升级的目标版本，升级的安装方式和 kubernetes 版本的配置与创建集群相同，详情参见集群配置指南。

集群升级可以跨小版本，但不支持略过次版本的升级，如您可以从 v1.20.2 升级到 v1.20.13，或由 v1.20.x 升级到 v1.21.x，但不支持从 v1.20.x 升级到 v1.22.x。对于 1.23.x 版本，暂不支持升级到 1.24.x 版本。

升级集群操作可能需要较长时间，您可以在集群详情页面查看操作日志，跟踪集群升级状态。

删除集群

您可以点击集群列表右侧“更多”>“集群状态”> “删除”按钮，删除集群。

注意删除后集群不可恢复。请谨慎操作。如果集群对接了外部存储，回收策略为“保留”的存储类中的数据卷会被保留，您可以通过其他方式访问，或手动删除；回收策略为“删除”的存储类中的数据卷，会在删除集群时自动删除。

重置状态

集群操作（如创建、恢复、升级等）执行失败，可能会导致集群状态显示为“xx失败”并无法正常执行其他操作，如果从断点处重试也无法执行成功，您可以参考运维文档，手动修复集群问题。问题修复后，您可以点击集群右侧“更多”>“集群状态”>“重置状态”按钮，重置集群至正常状态。

集群插件管理

除了在创建集群时安装插件，您也可以为运行中的集群安装存储和其他自定义插件。以安装存储插件为例，点击集群操作中的“更多”>“插件管理”>“添加存储项”按钮，进入添加存储项页面，可以为集群安装存储插件，安装配置与创建集群中的配置相同。

对于已安装的插件，您可以在集群详情页查看插件信息，并执行以下操作：

• 保存为模版：将插件信息保存为模版，以便为其他集群使用。

• 移除插件：卸载集群插件。

集群证书管理

更新集群证书

kubernetes 集群证书默认有效期为一年，您可以在集群详情页的基本信息中查看证书过期时间，证书过期前一天，您也可以在集群列表看到证书过期的提醒。更新集群证书，您可以点击集群操作中的“更多”>“集群证书”>“更新集群证书”按钮，更新集群全部证书。

获取 kubeconfig 文件

您可以点击集群操作中的“更多”>“集群证书”>“查看 kubeconfig 文件”按钮，查看集群 kubeconfig 文件，也可以点击弹窗中的“下载”按钮，下载 kubeconfig 文件。

4.4 - 节点管理

区域管理

平台支持多区域管理，即为平台管理的所有节点和集群进行物理或逻辑的区域划分。您可以在“区域管理”页面查看平台内管理的所有区域，点击区域名称，进入区域详情页面，可以查看区域下的所有集群列表和节点列表。

节点管理

您可以在“节点信息”页面查看平台中管理的全部节点列表，和节点规格、状态等信息。点击节点名称进入节点详情页面，可以查看详细的节点基本信息和系统信息。

KubeClipper 中的节点状态表示 kc-agent 对节点的管理状态。正常情况下，节点状态显示为“就绪”，当节点失联4分钟（误差时间 10s 内）后，状态会更新为“未知”，未知状态的节点无法进行任何操作，也无法创建集群或为集群添加/移除节点。

添加节点

在部署 KubeClipper 时，您就可以添加初始的 server 节点和 agent 节点，其中，server 节点用于部署 KubeClipper 自身服务，agent 节点可用于部署 kubernetes 集群。在用于实验或开发的 KubeClipper 环境，您可以将 server 节点同时添加为 agent 节点。但如果用于生产环境，建议不要将 server 节点复用为 agent 节点。

您也可以使用 kcctl join 命令为 KubeClipper 添加 agent 节点。同时，您可以为每个 agent 节点标记一个区域，区域可以是物理的或逻辑的位置，您可以使用同一区域的节点创建 kubernetes 集群，但不可以使用跨区域的节点创建集群。未标记区域的节点默认属于 default 区域。

命令行示例：

kcctl join --agent beijing:1.2.3.4 --agent shanghai:2.3.4.5

移除节点

当您不再需要某些节点，可以使用 kcctl drain 命令将节点从平台中移除。

命令行示例：

kcctl drain --agent 192.168.10.19

连接终端

在节点列表页面，您可以点击目标节点右侧的“连接终端”按钮，在连接终端的弹窗中输入节点端口和用户名密码信息后，访问节点 SSH 控制台并执行命令。

启用/禁用节点

您可以点击节点右侧“禁用”按钮暂时禁用节点，禁用状态下的节点不允许创建或添加到集群。

4.5 - 访问控制

用户管理

安装 KubeClipper 之后，您需要创建所需角色的用户。一开始，系统默认只有一个用户 admin，具有平台管理员角色。

点击“访问控制”>“用户”，进入用户管理页面，点击左上角“创建用户”按钮，在弹窗中填写用户名、密码、手机号码、邮箱等信息，并指定用户角色，点击“确认”按钮。系统内置四个角色如下：

• 平台管理员：拥有集群管理、用户管理、审计管理等全部平台查看和操作权限。

• 集群管理员：拥有所有集群管理权限。

• 用户管理员：拥有所有用户管理权限。

• 平台只读用户：拥有全部平台查看权限。

用户创建完成后，您可以在用户详情页面查看用户详情信息，并执行以下操作：

• 编辑：编辑用户别名、角色、手机号、邮箱信息。

• 编辑密码：编辑用户登录密码。

• 删除：删除用户。

在用户详情页面，您还可以查看当前用户的登录日志列表。

您可以编辑平台 /etc/kubeclipper-server/kubeclipper-server.yaml 文件，根据需要设置用户登录日志的最大保留条数和保留期限，每个用户的登录日志超过最大条数后，超过最大条数和期限的日志会被自动删除，仅超过保留期限但未超过最大条数的日志数据将不会被删除。

自定义角色

除了系统内置角色，您也可以创建自定义角色，以满足业务需要。

点击“访问控制”>“角色”，进入角色管理页面，您可以点击左上角“创建角色”按钮，创建自定义角色。

在创建角色页面，您需要填写角色名称和描述，并勾选自定义角色所需权限，一些权限依赖于其他权限，在选择这些权限时，将自动选中依赖的权限。

创建自定义角色完成后，您可以在角色详情页面查看角色基本信息、角色权限列表、授权用户列表，并对自定义角色执行以下操作：

• 编辑：编辑自定义角色别名。

• 编辑权限：编辑自定义角色下的权限。

• 删除：删除自定义角色，需确保没有用户使用待删除角色。

接入外部用户

KubeClipper 可以通过 OIDC 协议使用外部用户登录。

首先，平台管理员需要登录平台 server 节点，在 kubeclipepr-server.yaml 文件中的 authentication 下插入以下信息：

oauthOptions:
    identityProviders:
    - name: keycloak
      type: OIDC
      mappingMethod: auto
      provider:
        clientID: kc
        clientSecret: EErn729BB1bKawdRtnZgrqj9Bx0]mzUs
        issuer: http://172.20.163.233:7777/auth/realms/kubeclipper
        scopes:
        - openid
        - email
        redirectURL: http://{kc-console-address}/oatuh2/redirect/{IDP-Name}

其中，“provider” 下需要您填写自己的 OAuth2 服务的clientID、clientSecret、issuer信息，以 keycloack 为例，如下图所示。

redirectURL示例：http://172.0.0.90/oauth2/redirect/keycloack

OAuth2 用户可以通过以下步骤访问和使用 KubeClipper 平台：

1. 点击登录页的 “OAuth2 登录”按钮，进入 OAuth2 登录页面，输入用户名密码登录，进入 KubeClipper 平台，首次登录，您会因未被授予权限而无法访问平台。
2. 平台管理员或其他拥有用户管理权限的用户登录 KubeClipper，在用户管理页面，找到目标 OAuth2 用户，通过编辑用户指定用户角色。
3. OAuth2 用户重复第一步，登录 KubeClipper，就可以正常访问平台并执行角色权限内操作。

5 - 常见问题

5.1 - 通过 kcctl 命令创建集群错误

问题复现

安装 v1.2.1 版本的 kcctl

curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_VERSION=v1.2.1 bash -

通过 kcctl deploy 命令部署 KubeClipper 集群

# 安装 AIO 环境
kcctl deploy

通过 kcctl create cluster 命令创建 kubernetes 集群

# 需要先登录
kcctl login --host http://127.0.0.1 --username admin --password Thinkbig1
# 创建集群
kcctl create cluster --name test --master 192.168.10.98 --untaint-master

登录 KubeClipper 管理界面，查看创建集群操作日志，日志显示在安装 cni 过程中发现下载 calico v3.21.2 404 无法找到

问题修复 PR

提交已经合并到了 master，PR：https://github.com/kubeclipper/kubeclipper/commit/7e6eb0ed199ff1cb00fde0c2624c62cdc5ca0b9c

但 v1.2.1 已经发布了，按照发版规范无法在该版本打补丁，需要等到后续 v1.2.2 发布解决，因此我们提供一种临时方案来解决这个问题。

解决方法

制作离线资源包 下载 calico v3.21.2 的安装包，打包为指定格式的离线资源包

# 创建资源目录
mkdir -pv calico/v3.21.2/amd64

# 下载 v3.21.2 版本的 calico
wget -P calico/v3.21.2/amd64 https://oss.kubeclipper.io/packages/calico/v3.21.2/amd64/images.tar.gz
wget -P calico/v3.21.2/amd64 https://oss.kubeclipper.io/packages/calico/v3.21.2/amd64/manifest.json

# 压缩文件为指定命令
tar -zcvf calico-v3.21.2-amd64.tar.gz calico

推送离线资源包

# 推送
kcctl resource push --pkg calico-v3.21.2-amd64.tar.gz --type cni

# 验证
kcctl resource list|grep v3.21.2

如果在执行 kcctl resource push 报了如下错误： 解决方法如下：

1. 编辑 /root/.kc/deploy-config.yaml 文件。
2. 找到 ssh 配置项，添加 pkFile 字段配置，值为当前服务器的 ssh 公钥文件的绝对路径。
   

通过命令行安装 kubernetes 集群，在 KubeClipper 管理后台查看操作日志

kcctl create cluster --name test --master 192.168.10.98 --untaint-master

查看 kubernetes 集群 pods 运行状态

kubectl get pods -A

6 - 贡献指南

请查看 KubeClipper Community