Kubernetes集群一键部署：k8s-tew发行版实战指南

1. 项目概述：一个为Kubernetes集群量身定制的轻量级发行版

如果你和我一样，在运维Kubernetes集群时，常常被那些繁琐的、重复性的基础配置工作搞得焦头烂额，那么darxkies/k8s-tew这个项目，绝对值得你花时间深入了解。它不是一个全新的容器编排系统，而是一个基于Kubernetes的“发行版”或者说“发行套件”。你可以把它想象成Linux世界里的Ubuntu或CentOS——它们都基于Linux内核，但提供了开箱即用的软件包、配置工具和最佳实践，让你免去了从零开始编译、配置的痛苦。k8s-tew做的正是类似的事情：它基于上游的、纯净的Kubernetes，但通过一套精心设计的自动化工具链，将网络插件（CNI）、存储方案（CSI）、负载均衡器（MetalLB）、监控栈（Prometheus, Grafana）、日志系统（Loki）等生产环境必需的组件，以及它们之间复杂的依赖和配置，打包成一个可一键部署、易于管理的整体方案。

这个项目的核心价值在于“标准化”和“简化”。它预设了一套经过验证的、适用于中小规模生产或开发测试环境的架构选型。比如，它默认使用Cilium作为CNI，这不仅提供了高性能的网络策略，还集成了服务网格（Service Mesh）的雏形；默认使用Rook/Ceph提供分布式块存储，解决了有状态应用的数据持久化难题。这意味着，你不需要再在Calico、Flannel、Weave Net之间反复纠结，也不需要自己去研究如何让Prometheus自动发现集群内的服务。k8s-tew帮你做出了这些艰难但合理的选择，并确保所有组件能协同工作。对于运维工程师、DevOps从业者或者想要快速搭建一个功能完备的K8s学习环境的开发者来说，这极大地降低了入门和运维的复杂度，让你能更专注于业务应用的部署，而不是底层基础设施的泥潭。

2. 核心架构与设计哲学解析

2.1 基于Bootstrap节点的集中式管理模型

k8s-tew采用了一种非常清晰且易于理解的管理模型：一个独立的“Bootstrap”节点。这个节点并不运行你的业务容器，甚至可以不作为Kubernetes集群的工作节点。它的唯一职责，就是作为整个集群的“指挥中心”和“配置仓库”。所有集群的配置定义、组件清单、证书文件都集中存储在这个节点上。当你需要初始化集群、添加节点、升级组件或调整配置时，所有的操作指令都从这个Bootstrap节点发出。

这种设计带来了几个显著优势。首先是安全性，敏感的证书和配置无需分发到每个工作节点，降低了密钥泄露的风险。其次是配置的一致性，因为所有节点的配置都源于同一个“单一事实来源”（Single Source of Truth），彻底避免了因手动修改不同节点配置文件而导致的环境差异。最后是操作的便捷性，运维人员只需要登录到这一个管理节点，就可以掌控整个集群的生命周期。这非常类似于使用kubeadm时的那台“控制平面”节点，但k8s-tew将其角色和职责定义得更加纯粹和明确。

2.2 声明式配置与GitOps就绪

k8s-tew的整个集群状态是通过一个名为config.yaml的YAML文件来声明的。这个文件是你的“集群蓝图”，里面定义了集群的节点信息（主机名、IP、角色）、网络CIDR、要启用的功能组件（如ingress, monitoring, storage）及其版本。这种声明式的配置方式，是现代基础设施即代码（IaC）理念的完美体现。

它的好处是显而易见的。首先，配置可版本化。你可以将config.yaml纳入Git版本控制，任何对集群的变更都通过提交和拉取请求（PR）来完成，变更历史一目了然，并且可以轻松回滚到任何一个已知的良好状态。其次，它天然支持自动化。你可以结合CI/CD流水线，在修改配置文件后自动触发集群的重新配置。这为实践GitOps——即使用Git作为基础设施和应用的唯一可信源——铺平了道路。虽然k8s-tew本身不强制你使用特定的GitOps工具（如Flux或ArgoCD），但它提供的这种声明式模型，让你可以非常顺畅地将集群管理融入到已有的GitOps工作流中。

2.3 集成的组件选型与权衡

k8s-tew并非简单地将热门项目堆砌在一起，其默认组件选型背后有着深入的考量，旨在平衡功能、性能、复杂度和社区活跃度。

• 网络（CNI）：Cilium。这是k8s-tew一个非常大胆且前瞻的选择。Cilium基于eBPF技术，提供了远超传统CNI的网络性能、可视性和安全性。它不仅能处理基本的Pod网络互通，还能通过eBPF实现高效的网络策略（替代kube-proxy的部分功能）、提供网络流量的可观测性。选择Cilium意味着你的集群在网络上具备了面向未来的能力，但同时也带来了一定的学习曲线，因为它的概念和排错方式与传统CNI有所不同。
• 存储（CSI）：Rook/Ceph。对于需要持久化存储的应用（数据库、消息队列等），k8s-tew默认集成了Rook，这是一个在Kubernetes内部运行分布式存储系统的Operator。Rook又管理着Ceph，一个久经考验的、统一的分布式存储平台。这个组合提供了块存储（RBD）、文件系统（CephFS）和对象存储（RGW），功能极为强大。然而，它的复杂性也最高，对资源（CPU、内存、磁盘）的要求较大，更适合有一定存储运维经验或资源充足的场景。
• 负载均衡（MetalLB）与入口（Ingress NGINX）。对于裸金属或私有云环境，k8s-tew通过MetalLB提供了LoadBalancer类型的服务，将外部IP直接分配给K8s Service，填补了云厂商LB服务的空白。Ingress控制器则选择了最流行、最稳定的NGINX Ingress Controller，负责处理HTTP/HTTPS流量的路由和负载均衡。
• 监控与日志。监控栈采用了Prometheus Operator + Grafana的黄金组合，并预配置了针对Kubernetes核心组件及k8s-tew自身组件的监控仪表盘。日志方案则集成了Grafana Loki，一个轻量级、高索引效率的日志聚合系统，与Prometheus和Grafana形成了完美的可观测性闭环。

注意：k8s-tew的“开箱即用”是建立在它这套默认选型之上的。如果你对Cilium或Rook/Ceph不熟悉，或者你的环境资源非常有限，那么在享受便利的同时，也需要准备接受这些组件带来的复杂性和资源消耗。项目也支持替换部分组件，但这需要你深入理解其架构，并自行承担集成测试的工作。

3. 从零开始：实战部署k8s-tew集群

3.1 环境准备与先决条件

在开始挥舞魔法棒之前，我们必须确保“魔法阵”的基底是稳固的。假设我们要部署一个包含1个Bootstrap节点、1个控制平面节点和2个工作节点的小型集群。

硬件与系统要求：

• 节点：至少4台x86_64架构的服务器或虚拟机。Bootstrap节点资源可以稍小（如2核4GB），控制平面节点建议2核4GB以上，工作节点根据业务需求决定。所有节点需要互联互通。
• 操作系统：推荐使用Ubuntu 20.04/22.04 LTS或CentOS/RHEL 8+。k8s-tew的安装脚本主要针对这些系统进行了优化。
• 网络：确保所有节点有静态IP，主机名解析正确（可通过/etc/hosts或内部DNS）。防火墙需放行Kubernetes常用端口（6443, 2379-2380, 10250, 10259, 10257等）以及节点间通信端口。
• 软件依赖：在所有节点上，需要安装curl,wget,git,tar等基础工具。最关键的是，必须禁用Swap，因为Kubernetes的内存管理依赖于此。

# 在所有节点上执行：禁用Swap sudo swapoff -a # 永久禁用，编辑 /etc/fstab，注释掉包含swap的行 sudo sed -i '/swap/s/^/#/' /etc/fstab

3.2 Bootstrap节点初始化与配置生成

首先，在规划为Bootstrap节点的机器上操作。

1. 下载并安装k8s-tew二进制文件。项目提供了便捷的安装脚本。

   curl -sSL https://raw.githubusercontent.com/darxkies/k8s-tew/main/install.sh | bash

   执行后，k8s-tew命令行工具会被安装到/usr/local/bin下。

2. 生成初始配置文件。这是最核心的一步，我们将基于一个基础模板来创建我们的config.yaml。

   # 创建一个工作目录 mkdir -p ~/k8s-cluster && cd ~/k8s-cluster # 生成基础配置 k8s-tew configure --init

   这会在当前目录生成一个基础的config.yaml。现在，用你喜欢的编辑器（如vim或nano）打开它，开始定制。

3. 深度定制config.yaml。你需要修改以下几个关键部分：

   • cluster.name: 给你的集群起个名字，比如my-prod-cluster。
   • cluster.domain: 设置集群内部域名，如internal.mycompany.com。
   • nodes: 这是节点定义部分。你需要列出所有节点，并指定它们的角色（bootstrap,controller,worker）、IP地址和主机名。

     nodes: bootstrap: host: bootstrap-node ip: 192.168.1.10 internal-ip: 192.168.1.10 controller-1: host: master-node-1 ip: 192.168.1.11 internal-ip: 192.168.1.11 worker-1: host: worker-node-1 ip: 192.168.1.21 internal-ip: 192.168.1.21 worker-2: host: worker-node-2 ip: 192.168.1.22 internal-ip: 192.168.1.22

   • features: 在这里启用或禁用你需要的功能模块。默认情况下，ingress,monitoring,storage等可能都是开启的。如果你资源紧张，可以先关闭storage（Rook/Ceph）。
   • versions: 这里定义了各个核心组件（Kubernetes, Cilium, Rook等）的版本。除非你有特定需求，否则建议使用k8s-tew测试过的默认版本组合，以保证兼容性。

4. 生成最终部署清单。配置修改完成后，让k8s-tew基于此配置生成所有必要的部署文件。

   k8s-tew configure --generate

   这个命令会创建出assets目录，里面包含了所有Kubernetes manifests、systemd服务文件、证书等。

3.3 集群引导与节点加入

配置就绪，现在开始真正的部署。

1. 在Bootstrap节点上启动基础服务。这些服务是后续节点加入和组件部署的基石。

   k8s-tew bootstrap

   这个命令会启动一个本地容器仓库（registry）、文件服务器以及配置服务器。你可以通过k8s-tew status来检查这些服务的状态。

2. 初始化控制平面节点。首先，将Bootstrap节点生成的资产文件分发到控制平面节点。k8s-tew提供了方便的命令：

   # 在Bootstrap节点上执行，将资产打包并复制到controller-1节点 k8s-tew node-setup --target controller-1

   然后，登录到controller-1节点，你会发现资产文件已经就位。执行初始化：

   cd /path/to/assets ./setup.sh

   setup.sh脚本会安装容器运行时（containerd）、kubelet，并拉取所有必要的镜像。最后，启动Kubernetes控制平面服务。

3. 加入工作节点。过程与控制平面节点类似。在Bootstrap节点上，将资产分发到工作节点：

   k8s-tew node-setup --target worker-1 k8s-tew node-setup --target worker-2

   然后分别登录到每个工作节点，运行./setup.sh。脚本会自动将其配置为Kubernetes工作节点，并加入由controller-1建立的集群。

4. 部署集群附加组件。当所有节点都就绪后，回到Bootstrap节点，部署那些让集群变得“完整”的组件，如CNI、Ingress、监控等。

   k8s-tew deploy

   这个命令会读取config.yaml中的features配置，按顺序部署所有启用的组件。这个过程可能会持续几分钟，因为需要从镜像仓库拉取很多容器镜像。

3.4 部署后验证与初体验

部署完成后，让我们验证一下成果。

1. 获取kubeconfig。在Bootstrap节点上，你可以方便地获取到访问集群的凭证。

   k8s-tew kubeconfig > ~/.kube/config export KUBECONFIG=~/.kube/config

2. 检查节点和Pod状态。

   kubectl get nodes # 应该看到controller-1, worker-1, worker-2都是Ready状态 kubectl get pods -A # 查看所有命名空间的Pod，确保kube-system下的核心组件（apiserver, scheduler等）以及你启用的功能组件（cilium, rook-ceph, ingress-nginx等）都处于Running状态。

3. 访问Dashboard和监控界面（如果启用）。k8s-tew默认部署了Kubernetes Dashboard和Grafana。
   • Dashboard: 通常可以通过kubectl proxy访问，或者配置Ingress。
   • Grafana: 部署后，k8s-tew会输出访问信息，通常是一个NodePort服务。你可以用kubectl get svc -n monitoring grafana查看端口，然后用任意节点的IP和该端口访问。初始用户名和密码通常在Grafana的配置Secret中。

至此，一个功能齐全的Kubernetes集群就已经搭建完毕。你可以开始部署你的业务应用了。

4. 日常运维、升级与故障排查实战指南

4.1 集群的日常维护操作

k8s-tew让日常维护变得有章可循。所有操作都应从Bootstrap节点发起。

• 查看集群状态：k8s-tew status命令是你的控制台，可以快速查看Bootstrap服务、集群节点和核心Deployment的健康状态。
• 添加新节点：当需要扩容时，首先在Bootstrap节点的config.yaml的nodes部分添加新节点的定义。然后运行k8s-tew configure --generate重新生成资产，接着使用k8s-tew node-setup --target <新节点名>将资产分发到新节点，最后在新节点上运行./setup.sh即可。
• 备份与恢复：最重要的备份是Bootstrap节点上的整个工作目录（包含config.yaml和assets/）。此外，定期备份/etc/kubernetes（证书）和/var/lib/etcd（如果etcd数据目录在此）也是必要的。恢复时，确保在新Bootstrap节点上恢复这些目录和文件，然后重新运行k8s-tew bootstrap和k8s-tew deploy。

4.2 平滑升级集群版本

升级是运维中最需要谨慎的操作。k8s-tew支持相对平滑的升级，但必须严格遵守顺序。

1. 升级k8s-tew二进制文件本身：首先在Bootstrap节点上，按照官方文档下载并替换新版本的k8s-tew二进制文件。
2. 更新配置文件：新版本的k8s-tew可能会引入配置项的变化。运行k8s-tew configure --upgrade，它会尝试自动将你的config.yaml迁移到新版本格式。务必在升级前备份原配置文件！手动检查合并后的配置文件，确保无误。
3. 升级节点系统组件：在config.yaml中，将versions.kubernetes等字段修改为目标版本。然后运行k8s-tew configure --generate重新生成资产。
4. 滚动升级节点：必须按顺序进行：先升级所有控制平面节点，再升级工作节点。对于每个节点：
   • 使用k8s-tew node-setup --target <节点名>将新资产分发到该节点。
   • 登录该节点，运行./upgrade.sh（如果存在）或再次运行./setup.sh。脚本会安全地排空（drain）节点上的Pod，升级组件，然后恢复节点。
5. 升级集群组件：最后，在Bootstrap节点运行k8s-tew deploy，它会根据新配置，将Cilium、Rook、Monitoring等附加组件升级到新版本。

实操心得：升级前，务必在测试环境完整演练一遍整个流程。重点关注从节点中驱逐（drain）Pod时，是否有有状态应用（如数据库）无法优雅终止。对于生产环境，建议逐个节点升级，并观察监控指标，确保业务稳定后再进行下一个。

4.3 常见故障场景与排查思路

即使有自动化工具，故障依然不可避免。以下是几个典型场景及排查路径。

场景一：节点加入失败，卡在kubelet启动。

• 排查思路：
  1. 检查网络连通性：确保新节点与Bootstrap节点、控制平面节点之间的网络是通的，特别是API Server的端口（6443）。
  2. 检查证书：在新节点的/etc/kubernetes/pki目录下，检查证书文件是否存在且有效。有时证书过期或主机名不匹配会导致加入失败。可以对比Bootstrap节点生成的证书和新节点上的证书。
  3. 查看kubelet日志：journalctl -u kubelet -f是你看清问题的最佳窗口。常见的错误包括镜像拉取失败（网络或仓库问题）、cgroup驱动不匹配（与容器运行时）、证书认证失败等。
• 解决步骤：根据日志错误信息对症下药。如果是证书问题，从Bootstrap节点重新分发资产。如果是镜像问题，检查Bootstrap节点的本地仓库是否正常运行，或者配置正确的镜像拉取策略。

场景二：Pod网络不通，跨节点Pod无法通信。

• 排查思路：这通常是CNI（Cilium）的问题。
  1. 检查Cilium Pod状态：kubectl get pods -n kube-system -l k8s-app=cilium。确保所有节点上的Cilium Pod都是Running状态。
  2. 检查Cilium Agent日志：kubectl logs -n kube-system <cilium-pod-name>。查看是否有eBPF程序加载失败、内核版本不兼容等错误。
  3. 使用Cilium CLI诊断：Cilium提供了强大的诊断工具cilium。可以在任意节点上运行cilium status查看代理状态，cilium connectivity test在命名空间内执行端到端的网络连通性测试。
  4. 检查主机路由和网络策略：确保节点间路由正确，没有防火墙规则阻断Cilium使用的VXLAN或Geneve隧道端口（默认为8472/UDP）。检查是否有过于严格的NetworkPolicy阻止了流量。
• 解决步骤：重启故障节点上的Cilium Pod通常是第一步。如果问题依旧，尝试查看Cilium的Endpoint和Service映射是否正确。复杂情况下，可能需要深入eBPF层面，使用cilium monitor命令观察数据包处理流程。

场景三：存储卷（PVC）无法绑定或挂载。

• 排查思路：这指向CSI驱动（Rook-Ceph）或底层Ceph集群的问题。
  1. 检查Rook-Ceph Operator状态：kubectl get pods -n rook-ceph。确保Operator和所有Ceph守护进程（mon, mgr, osd）都运行正常。
  2. 检查Ceph集群健康度：进入Toolbox Pod执行命令：kubectl exec -it -n rook-ceph deploy/rook-ceph-tools -- ceph status。关注health状态，如果不是HEALTH_OK，根据输出信息排查。
  3. 查看PVC/PV事件：kubectl describe pvc <pvc-name> -n <namespace>。事件列表通常会给出具体原因，例如“等待卷绑定”、“ProvisioningFailed”等。
  4. 检查StorageClass：确认PVC指定的StorageClass是否存在且配置正确。kubectl get storageclass。
• 解决步骤：如果是Ceph集群健康问题，需要根据Ceph日志进行修复，可能涉及OSD重启、数据重平衡等。如果是资源不足（如存储池已满），需要扩容Ceph集群。如果是权限或配置问题，检查StorageClass和Secret的配置。

场景四：监控或日志组件无法访问。

• 排查思路：通常是Ingress配置或Service网络问题。
  1. 检查Ingress Controller：kubectl get pods -n ingress-nginx。确保Ingress控制器Pod运行正常。
  2. 检查Ingress资源：kubectl get ingress -n monitoring(对于Grafana)。确认Ingress规则是否正确配置了主机名和路径。
  3. 检查Service和Endpoint：kubectl get svc,ep -n monitoring grafana。确认Service有正确的Selector指向后端Pod，并且Endpoints列表不为空（表示有健康的Pod）。
  4. 从集群内部测试：临时启动一个busyboxPod，尝试从集群内部curl Grafana的Service ClusterIP，以排除Ingress层的问题。
• 解决步骤：修正Ingress配置，确保DNS或本地hosts文件能将你使用的主机名解析到Ingress Controller的Service IP（或NodePort）。检查Pod的Readiness Probe是否配置正确，导致Endpoint未就绪。

5. 进阶调优与生产环境考量

当你熟悉了k8s-tew的基本操作后，为了将其用于更严肃的生产环境，以下几个方面的考量至关重要。

5.1 高可用性架构设计

默认的单控制平面部署存在单点故障风险。k8s-tew支持部署多控制平面节点以实现高可用（HA）。

1. 配置多个Controller节点：在config.yaml的nodes部分，定义多个角色为controller的节点。
2. 负载均衡器：你需要一个外部的负载均衡器（可以是硬件F5、软件HAProxy，或者云厂商的LB），将流量分发到所有控制平面节点的6443端口。这是关键，kubelet和kubectl都通过这个VIP访问API Server。
3. 高可用etcd：k8s-tew默认在每个控制平面节点上部署一个etcd实例，并组成集群。确保这些etcd节点之间的网络延迟低且稳定。
4. 部署与验证：按照添加节点的流程，将所有控制平面节点加入集群。之后，你可以通过kubectl get endpoints kubernetes来验证API Server的端点是否包含了所有控制平面节点的IP。

5.2 安全加固实践

安全永远不是可选项。除了k8s-tew默认提供的证书和基础配置，你还需要主动加固。

• Pod安全策略/PSP替代方案：由于Kubernetes已弃用PSP，应使用Pod安全准入控制器（PSA）。在config.yaml中，确保相关特性被启用，并为不同的命名空间设置合适的Pod安全标准（Privileged, Baseline, Restricted）。
• 网络策略：充分利用Cilium提供的网络策略。默认拒绝所有跨Pod流量，然后根据需要显式地允许特定通信。这能有效实现微服务间的网络隔离。
• 镜像安全：配置containerd只从受信任的镜像仓库拉取镜像。可以考虑集成镜像扫描工具（如Trivy、Clair），在CI/CD流水线中阻断含有高危漏洞的镜像。
• 审计日志：启用Kubernetes API Server的审计日志，并集中收集到安全信息与事件管理（SIEM）系统中，用于事后追溯和分析。
• 最小权限原则：为ServiceAccount绑定最小必要的RBAC角色，避免使用cluster-admin等过高权限。

5.3 性能监控与容量规划

一个健康的集群需要持续的关注。

• 利用内置的Prometheus/Grafana：k8s-tew部署的监控栈已经包含了丰富的仪表盘。你需要重点关注：
  • 节点资源：CPU/内存/磁盘使用率、负载。
  • Pod资源：各个业务Pod的CPU/内存限制与使用情况，及时发现内存泄漏或CPU瓶颈。
  • 存储：Ceph集群的OSD使用率、IOPS、延迟。设置告警，在存储池容量超过80%时提前扩容。
  • 网络：Cilium提供的网络丢包、延迟、吞吐量指标。
• 设置告警规则：在Prometheus中配置Alertmanager规则，当关键指标异常（如节点NotReady、Pod持续重启、磁盘空间不足）时，能通过邮件、钉钉、Slack等渠道及时通知。
• 容量规划：定期回顾资源使用趋势。根据业务增长预测，提前规划节点扩容。对于有状态应用，更要关注持久卷的容量增长。

5.4 与现有基础设施的集成

k8s-tew集群很少是孤岛，它需要与外部世界对接。

• 外部DNS与证书：集群内部的Ingress通常使用自签名证书或像cert-manager这样的工具从Let‘s Encrypt自动申请。你需要将Ingress中定义的域名（如grafana.internal.mycompany.com）解析到MetalLB分配的负载均衡器IP，或者Ingress Controller的NodePort。
• 私有镜像仓库：如果公司有内部的Harbor或Nexus仓库，需要修改containerd和k8s-tew的配置，使其优先从私有仓库拉取镜像。这通常涉及在config.yaml中配置镜像仓库镜像（registry-mirrors）或直接修改生成的containerd配置。
• CI/CD流水线：将你的CI/CD工具（如Jenkins、GitLab CI、GitHub Actions）与k8s-tew集群集成。在流水线中配置kubeconfig，使其能够直接kubectl apply部署应用到集群，或者更优雅地，采用GitOps模式，由ArgoCD等工具自动同步Git仓库中的配置。

k8s-tew项目为快速搭建一个功能丰富的Kubernetes集群提供了强大的助力，它将许多复杂的集成工作标准化、自动化。然而，它并没有消除对Kubernetes及其生态组件本身的理解需求。相反，它要求运维者对这些底层组件有更深入的把握，才能在出现问题时游刃有余地进行排查和调优。把它看作一个优秀的“脚手架”和“最佳实践合集”，在这个坚实的基础上，去构建和运维你的云原生应用，才是发挥其最大价值的方式。