Iac on 维克的博客

Kubespray 部署和维护 K8s 集群指南

Fri, 09 Oct 2026 11:34:13 +0800

1. 简介

Kubespray 是 Kubernetes SIGs 官方维护的部署项目，本质是一套经过大量生产环境验证的 Ansible Playbook、Inventory 模板和角色集合。它不发明新的集群模型，而是把 kubeadm 引导、etcd 集群组建、CNI 安装、证书轮换、节点扩缩容与升级这些容易出错的步骤固化为可重复执行的代码。

1.1 Kubespray 解决了什么问题

手动搭一个生产集群的工作量并不仅仅只是简单把 K8s 集群跑起来，而在于：

etcd 节点集群的证书、成员管理、快照备份；
多控制平面节点下 apiserver 的负载均衡与前端证书 SAN；
kubelet 配置（cgroup 驱动、预留资源、镜像垃圾回收、最大 Pod 数）；
CNI 插件与内核网络参数、iptables/nftables 后端的匹配；
证书到期轮换、跨小版本顺序升级、节点下线清理。

这些工作做一次可以靠文档，做十次就得靠自动化。Kubespray 的价值就在于它把这些工程细节沉淀成了一套符合生产环境最佳实践的可重复执行代码，你只需要在默认值的基础上少量改动，而不是自己编写和维护大量的脚本。

1.2 和其他工具对比

工具	Kubespray	kubeadm	Rancher	OpenShift(OKD)	kops	KubeKey(kk)	k3s
核心定位	Ansible驱动，生产级离线部署K8s集群	K8s官方最小化集群引导工具	企业级K8s全生命周期管理平台	红帽出品，基于K8s的企业容器平台	AWS专用K8s集群部署工具	KubeSphere社区开源部署工具，中文友好	Rancher出品轻量K8s发行版
底层引擎	Ansible	Go原生二进制	容器+WebUI	容器/Operator	Go，调用AWS API	Go二进制，封装kubeadm	裁剪K8s单二进制
适用环境	裸金属、VMware、私有云、离线环境	裸金属/虚拟机/云主机，在线为主	公有云、私有云、边缘，多集群统一管理	企业私有/混合云，偏向生产企业	仅限AWS公有云	裸机/虚拟机，私有化离线场景	低配服务器、边缘、开发/小生产
离线部署	✅ 完美支持，可打包离线介质	⚠️ 支持但麻烦，需要手动下载镜像/二进制	✅ 支持离线airgap安装	✅ 官方提供离线方案	❌ 依赖AWS云API，不适合离线	✅原生支持打包离线包	✅离线包
集群维护	Ansible playbook升级、扩容、替换节点；版本升级稳定	仅引导集群，不负责后续集群运维，升级操作繁琐	Web界面一键升级、扩缩容，多集群统一监控告警	Operator管理集群，自动化运维能力强	集群升级、节点替换由kops命令管理	一键HA、扩容升级，可配套KubeSphere控制台	一行命令运维，嵌入式etcd HA
高可用	✅ 内置etcd三副本、控制面HA方案	需要手动搭建HA（负载均衡+多master）	✅ 自动支持HA，内置负载均衡方案	✅ 默认HA架构	✅ AWS上自动搭建控制面HA	✅一键HA，内置负载均衡	✅内置HA（嵌入式etcd）
网络插件	内置Calico/Flannel/Cilium等多种CNI可选	仅提供基础CNI对接，需自行部署CNI	内置多种CNI，UI可视化配置	默认OVN-Kubernetes，也可Calico	默认Calico，可自定义CNI	Calico等CNI可选	Flannel默认，支持替换CNI
存储支持	对接本地卷、Ceph、Longhorn等，ansible角色集成	仅提供CSI标准，存储需要自己部署	内置存储管理，支持Longhorn等	内置CSI+本地存储方案	对接AWS EBS等云存储	对接Longhorn、Ceph、本地存储	支持本地存储、CSI
版本适配	紧跟K8s社区版本，滞后一小段时间	K8s官方同步发布	支持多K8s版本，统一纳管不同版本集群	OKD版本独立，和上游K8s有差异	紧跟AWS支持的K8s版本	跟随上游kubeadm	Rancher维护稳定版本
学习成本	中等，需要懂Ansible	低，上手简单，适合测试集群	低，WebUI友好，运维门槛低	高，体系庞大，有专属概念	中等，熟悉AWS即可快速上手	中等，中文文档友好	很低，上手极快
典型场景	裸金属机房、私有化项目、需要批量部署大量集群、等保离线环境	实验室、POC测试、小规模简单集群	多集群管理、混合云、需要统一权限/审计的企业	大型企业生产环境，需要完整容器安全、合规能力	AWS云上快速搭建销毁K8s集群	中小企业裸机/VM离线部署，可选KubeSphere控制台	资源有限、边缘、小生产集群
缺点	Ansible串行执行，大规模集群部署慢；无WebUI；故障排查需要Ansible基础	没有集群生命周期管理，生产HA搭建工作量大；缺少监控日志等附加组件	资源开销大；底层K8s被封装，深度定制复杂；商业版收费	闭源企业版昂贵；架构重，资源消耗高；学习曲线陡峭	只能跑在AWS，无法裸金属/其他云使用	依赖kubeadm；底层封装，深度排障需要kubeadm知识；KubeSphere额外耗资源	裁剪部分组件，重型大规模生产不推荐；和标准K8s有细微差异
国内中小企业热度	⭐⭐⭐ 更多集成商使用，中小企业自用偏少	⭐⭐⭐⭐⭐ 最高，几乎所有运维都学这个	⭐⭐⭐⭐ 多集群场景热门	⭐⭐ 大型企业为主，中小企业很少用	⭐ 国内几乎不用	⭐⭐⭐⭐ 私有化中小企业热门	⭐⭐⭐⭐ 小集群/边缘场景热门

2. 底层架构和设计

关键核心设计：

Terraform 状态文件管理

Fri, 04 Sep 2026 16:08:53 +0800

1. 为什么要把 State 搬到「云上」

State 文件是 Terraform 的「账本」：它记录云上到底有哪些资源、各自的属性。本地存放 State 有三个硬伤：

绑定机器：State 在 A 电脑上，B 电脑 apply 就会"失忆"，容易把资源重建一遍。
无法协作：两个人同时改同一个环境，互相覆盖，状态文件乱套。
安全隐患：本地文件易丢，而且里面可能含有明文密码等敏感信息，因此也不建议上传到 gitlab 等代码托管平台。

解决办法就是 Terraform 的 Backend 机制：用阿里云 OSS 存 State（集中、加密、可回滚），用 Tablestore 提供加锁（防止多人并发操作冲突）。

2. 工作原理

每次执行 Terraform 命令，OSS Backend 都会走「加锁 → 干活 → 放锁」三步：

flowchart LR
A[terraform apply] --> B{从 Tablestore 拿 LockID}
B -- 已存在 --> C[报错：有人在操作]
B -- 不存在 --> D[生成并存入 LockID]
D --> E[读写 OSS 里的 State 文件]
E --> F[释放 LockID]

有锁 → 说明有人正在操作，或上次操作异常退出，直接报错
无锁 → 自动生成 LockID 存入 Tablestore，操作完成后更新 OSS 中的 State，再释放锁

3. 第一步：创建「存储 + 锁」资源

在正式使用前，要先准备一个 OSS Bucket 和一个 Tablestore 实例/表。它们本身也是云资源，所以也可以用 Terraform 自己建。

Terraform 云上存量资源导入

Thu, 03 Sep 2026 16:24:03 +0800

1. 为什么要"导入"云上资源？

很多团队都有这样的经历：最开始用控制台点几下、或者用 CLI 脚本把资源建好了，等资源越攒越多、想标准化管理时，发现这些资源"游离"在 Terraform 之外。

Terraform 的管理逻辑很简单：它只认自己 state 文件里记录的资源。你在控制台创建的资源，Terraform 根本"看不见"，也不会去动它们。所以要把存量资源管起来，第一步就是"导入"（import）——把云上已有的资源登记进 Terraform 的 state，再补上对应的配置代码。

导入成功后，这些资源和 Terraform 新建的资源享受完全一样的待遇：能 plan、能 apply、能 diff、能进 CI/CD。

2. 先搞清楚两个概念：config 和 state

这是最容易绕晕的地方，务必先分清：

概念	是什么	谁来写
`.tf` 配置（config）	声明"想要什么"，是给人看的声明式代码	手写，或工具自动生成
`terraform.tfstate`（state）	记录"现在实际是什么"，含真实属性（可能有敏感信息）	由 apply / import 自动生成

关键点：

导入只会写 state，不会自动写 config（除非你用 -generate-config-out 或 Terraformer）。
所以完整流程 = 导入进 state + 补齐 config + plan 核对一致，三步缺一不可。
state 含敏感信息，永远不要提交到 git（后面最佳实践会讲远程存储）。

整体流程可以先看这张图：

flowchart TD
A[盘点存量资源: 类型 / ID / 地域] --> B[环境准备: Terraform + provider + RAM 凭证]
B --> C{资源量多少?}
C -->|少| D[import block / terraform import]
C -->|多| E[aliterraformer 批量导入]
D --> F[生成 config + state]
E --> F
F --> G[terraform plan 核对无漂移]
G --> H[清理只读属性 + 纳入 git + OSS 远程 state]

3. 三种导入方式怎么选

阿里云官方文档提供了三种方式，直接放对比表：

Terraform 内置函数

Thu, 03 Sep 2026 16:06:29 +0800

写 Terraform 配置的时候，你肯定遇到过这些场景：

想把几个字符串拼起来
想从一个列表里取第一个元素
想根据条件选不同的值
想读取一个 JSON 配置文件

Terraform 内置了 100+ 个函数，覆盖了字符串处理、集合操作、类型转换、编码解码等各种需求。掌握它们，你的 HCL 代码会从"能跑"变成"优雅"。

本文挑出最常用的 20 个函数，每个都配上可直接运行的 demo，最后附上最佳实践。

1. 字符串函数

1.1. `format()` — 格式化字符串

类似其他语言的 sprintf，用占位符拼接字符串。

locals {
 env = "prod"
 region = "cn-hangzhou"
 # 输出: "prod-cn-hangzhou-01"
 name = format("%s-%s-01", local.env, local.region)
}

1.2. `join()` — 用分隔符拼接列表

locals {
 tags = ["web", "nginx", "frontend"]
 # 输出: "web,nginx,frontend"
 csv = join(",", local.tags)
}

1.3. `split()` — 按分隔符拆分字符串

locals {
 str = "10.0.0.1,10.0.0.2,10.0.0.3"
 # 输出: ["10.0.0.1", "10.0.0.2", "10.0.0.3"]
 ips = split(",", local.str)
}

1.4. `replace()` — 替换子串

locals {
 name = "my-project-dev"
 # 输出: "my-project-prod"
 new = replace(local.name, "dev", "prod")
}

1.5. `trimprefix()` / `trimsuffix()` — 去掉前缀/后缀

locals {
 domain = "www.example.com"
 # 输出: "example.com"
 base = trimprefix(local.domain, "www.")
}

1.6. `upper()` / `lower()` / `title()` — 大小写转换

locals {
 env = "production"
 # 输出: "PRODUCTION"
 tag = upper(local.env)
}

2. 集合函数（列表 / 映射 / 集合）

2.1. `length()` — 获取长度

locals {
 zones = ["cn-hangzhou-a", "cn-hangzhou-b", "cn-hangzhou-c"]
 count = length(local.zones) # 输出: 3
}

2.2. `element()` — 按索引取值（会循环）

locals {
 zones = ["a", "b"]
 # 索引 2 超出长度，自动取模 → 回到索引 0
 # 输出: "a"
 zone = element(local.zones, 2)
}

💡 和直接 local.zones[2] 不同，element() 不会报错，适合循环创建资源时分配可用区。

Terrafrom 基础知识

Thu, 03 Sep 2026 12:37:52 +0800

1. 简介

Terraform 是一款开源的“基础设施即代码（Infrastructure as Code，IaC）”工具，由 HashiCorp 公司开发（创始人为 Mitchell Hashimoto）。它的核心作用是用人类可读的配置文件来安全、高效地构建、变更和版本化管理云上和本地的各类基础设施。

它的主要特点包括：

基础设施即代码：用高阶配置语法描述基础设施，便于版本控制、复用和共享。
声明式语言：用户只需描述期望的基础设施最终状态，工具自动处理依赖关系和部署顺序；配置语言使用 HCL（也支持 JSON）。
执行计划：在真正执行前会生成操作计划，避免意外变更。
资源图：构建资源依赖图并并行处理相互独立的资源。
多云支持：可与 AWS、Azure、Google Cloud、阿里云等主流云平台集成。

典型的工作流程包括初始化（terraform init）、生成计划（terraform plan）和应用（terraform apply）三个阶段。Terraform 侧重于定义和管理基础设施结构，常与 Ansible 等侧重于配置管理的工具搭配使用。

2. 核心概念

2.1. 基础架构即代码 (IaC)

Terraform 允许使用配置文件（而非手动操作或脚本）来定义和管理基础设施。这使基础设施可以像应用程序代码一样进行版本控制、测试和协作。

2.2 HCL

HCL 全称 HashiCorp Configuration Language，是 Terraform 使用的一种特定于域的专用语言，专为基础设施管理设计：

语法简单易学，比 JSON 和 ARM 模板更直观
支持变量、条件表达式和函数
提供类型安全和 IntelliSense 支持（在 VS Code 等编辑器中）

2.3. Providers

Provider 是云厂商提供并维护的一个能与云厂商 API 进行交互的插件，其中包含相关资源和数据源对象。Terraform 可以通过 Provider 来管理基础设施。常用的 Providers 有：

AzureRM：管理 Azure 资源
AWS：管理 AWS 服务
Kind：使用 Kind 管理 kubernetes 集群
Docker：管理容器资源
其他支持的云平台和 SaaS 服务

2.4. 状态文件 (State File)

Terraform 会跟踪基础设施的当前状态，包括，组件配置，资源之间的依赖关系等，通过比对配置文件与状态文件，确定需要实施哪些变更。

Iac on 维克的博客

Kubespray 部署和维护 K8s 集群指南

1. 简介

1.1 Kubespray 解决了什么问题

1.2 和其他工具对比

2. 底层架构和设计

Terraform 状态文件管理

1. 为什么要把 State 搬到「云上」

2. 工作原理

3. 第一步：创建「存储 + 锁」资源

Terraform 云上存量资源导入

1. 为什么要"导入"云上资源？

2. 先搞清楚两个概念：config 和 state

3. 三种导入方式怎么选

Terraform 内置函数

1. 字符串函数

1.1. format() — 格式化字符串

1.2. join() — 用分隔符拼接列表

1.3. split() — 按分隔符拆分字符串

1.4. replace() — 替换子串

1.5. trimprefix() / trimsuffix() — 去掉前缀/后缀

1.6. upper() / lower() / title() — 大小写转换

2. 集合函数（列表 / 映射 / 集合）

2.1. length() — 获取长度

2.2. element() — 按索引取值（会循环）

Terrafrom 基础知识

1. 简介

2. 核心概念

2.1. 基础架构即代码 (IaC)

2.2 HCL

2.3. Providers

2.4. 状态文件 (State File)

1.1. `format()` — 格式化字符串

1.2. `join()` — 用分隔符拼接列表

1.3. `split()` — 按分隔符拆分字符串

1.4. `replace()` — 替换子串

1.5. `trimprefix()` / `trimsuffix()` — 去掉前缀/后缀

1.6. `upper()` / `lower()` / `title()` — 大小写转换

2.1. `length()` — 获取长度

2.2. `element()` — 按索引取值（会循环）