做平台工程这几年接触了不少 Kubernetes 部署方案Tanzu Kubernetes Grid简称 TKG算是我在 vSphere 环境里用得最顺的一套。它不是简单地在虚拟机上装一个 Kubernetes而是一套基于 Cluster API 的集群生命周期管理平台可以让你通过声明式方式创建、扩缩容、升级和销毁多个独立 Kubernetes 集群。这篇文章就是一份完整的安装实录从准备 vSphere 环境、下载 CLI 开始到部署管理集群并创建出第一个可用的工作负载集群为止每一步都给出配置、命令和验证方法。如果你正在现有 vSphere 底座上规划一套可控的多集群 Kubernetes 环境这篇内容可以直接照着做。为了不让文章变成“命令复制粘贴”我会把很多配置文件里的字段含义、为什么这么设、以及我实际踩过的坑一并写出来。TKG 的安装过程对网络、时钟、资源规划的要求比较细有些问题在文档里不会写但部署时一卡就是半天。这篇会尽量把这些隐藏细节都摊开讲。1. 安装前的全局视图先搞懂最终要装出什么1.1 TKG 的核心产物管理集群和工作负载集群先说结论TKG 并不是“在一台服务器上跑一个安装脚本”就完事它的安装产物分两层。第一层是管理集群Management Cluster它的职责是“管集群的集群”。管理集群内部运行着 Cluster API 的控制器和各种 provider以后你执行tanzu cluster create创建新集群时真正干活的是它它会去调用 vCenter API、申请虚拟机、初始化控制面、加入工作节点。第二层是工作负载集群Workload Cluster这才是跑业务 Pod 的普通 Kubernetes 集群。你可以通过 TKG 同时管理多个工作负载集群彼此之间网络隔离、版本独立想升级哪个就升级哪个。打个比方管理集群是火车站调度中心工作负载集群是真正在铁轨上跑的车厢。日常运维中你很少直接碰调度中心绝大多数操作都是针对车厢的。这里要特别强调一点TKG 的安装过程中还会有一个临时的 bootstrap 集群。执行安装命令的机器上如果装了 DockerTKG 会先用 Docker 起一个临时 K8s 集群再由它去 vCenter 里把管理集群的虚拟机建起来等管理集群正常运行后再把本地临时集群清掉。所以你的安装机器不需要一直在线但中途不能关机。1.2 两种部署模式按团队情况选TKG 在实际交付中有两种模式我在文章里用的是“独立管理集群Standalone”模式。这种模式下管理集群由 TKG 自己通过 Cluster API 在 vSphere 上创建和 vSphere 原生功能没有强绑定。它适合大多数已有 vCenter 但没启用 vSphere with Tanzu 的存量环境也是最能理解 TKG 原理的部署方式。另一种是“vSphere 集成模式”管理集群的控制面由 vSphere Supervisor Cluster 提供TKG 作为上层工具去创建工作负载集群。这种模式对已经深度使用 vSphere with Tanzu 的运维团队更友好但对 vCenter 版本、许可证、网络配置的要求更高入门门槛也更大。如果你只是想在一个标准 vSphere 环境里快速获得可控的多集群 Kubernetes独立管理集群基本是唯一选择。下面所有步骤都基于这种模式。2. 动手前的环境准备把地基打牢2.1 基础设施资源规划建议安装 TKG 之前先要对资源有一个整体盘算。根据我的经验最少需要准备这些角色建议配置说明bootstrap 安装机2 vCPU / 4GB 内存 / 40GB 磁盘一台 Linux 虚拟机装 Docker 和 CLI可在安装完成后关机管理集群控制面节点每台 4 vCPU / 8GB 内存生产环境建议 3 台形成 HA开发环境可 1 台工作负载集群节点按业务需求定控制面建议 1-3 台Worker 按负载规划负载均衡 VIP管理网络空闲 IP 若干用于暴露 Kubernetes API Server 和 Ingress要提前预留这里最容易被忽略的是存储。TKG 创建虚拟机时每个节点都会从内容库里的模板克隆出来所以数据存储上要有足够的空间同时考虑 IOPS。我之前在一个配置较低的测试环境里部署管理集群三个控制面节点同时启动数据存储 IO 直接被打满导致 etcd 无响应集群一直处于初始化失败状态。2.2 vSphere 侧的准备账号、资源池、内容库vCenter 账号必须要有创建虚拟机、分配网络、挂载存储的权限。实践中最稳的做法是单独建一个服务账号角色权限限定在 TKG 要用到的资源池、文件夹和网络范围内不要直接给 vCenter 管理员权限。一是安全二是出了问题容易排查。要提前在 vCenter 里创建几个逻辑资源专门给 TKG 使用的资源池避免它和存量虚拟机抢 CPU 内存一个虚拟机文件夹让 TKG 创建的机器集中存放一个内容库Content Library把节点操作系统模板 OVA 导入进去。内容库这一步很多人会偷懒想等部署时再上传模板。千万别这样。TKG 创建节点时是直接从内容库克隆模板如果内容库里没有对应版本的 OVA部署会在 preflight 阶段直接报错浪费大量排查时间。正确做法是安装前就把需要的 Photon OS 或 Ubuntu OVA 导入内容库并且确认 OVA 版本与你下载的 TKG CLI 版本匹配。2.3 bootstrap 安装机的准备bootstrap 机是安装过程的起点。我建议用一台干净的 Ubuntu 22.04 虚拟机不要装过多软件避免环境变量、端口占用干扰安装。这台机器需要装三样东西Docker、kubectl、以及后面要重点讲的 tanzu CLI。Docker 的作用前面说过它要在本地临时拉起 bootstrap 集群。这里有一个实际经验Docker 安装完后建议调整一下默认的nofile限制否则集群创建过程中可能出现too many open files的错误。bootstrap 机只要能访问 vCenter 的 443 端口以及后续 TKG 创建的节点之间的网络就行。不要在防火墙策略上卡得太死但也不要完全放开按端口粒度放行最稳妥。2.4 网络、DNS 和 NTP三个最容易翻车的基础项在 TKG 部署中DNS 和 NTP 的问题占了故障原因的一大半。部署前请务必确认vCenter 的 FQDN 在 bootstrap 机和管理集群节点上都能正常解析不要偷懒用 IP 地址Kubernetes 证书体系对主机名敏感所有虚拟机能访问 NTP 服务器时间偏差控制在秒级以内。Kubernetes 组件之间通信大量依赖证书证书校验会考虑时间窗口时间偏移过大时经常出现莫名其妙的 handshake 失败TKG 规划的 Pod 网段CLUSTER_CIDR和 Service 网段SERVICE_CIDR不能与现有物理网络、VLAN 网段冲突。这个冲突在集群创建时不一定会报错但等业务流量跑起来路由混乱会让你怀疑人生。准备阶段可以花十分钟把这三项都验证一遍后面能省下几小时的排查时间。3. 工具链安装tanzu CLI 与插件初始化3.1 下载并安装 tanzu CLI接下来进入实际安装环节。TKG 的所有操作都通过 tanzu CLI 完成所以先把 CLI 装好。从官方渠道下载和你 TKG 版本匹配的 CLI 压缩包后解压出来通常包含一个tanzu可执行文件和一个插件目录。把tanzu放到/usr/local/bin下执行tanzu version确认版本号正常。这里要提醒一句TKG 版本和 tanzu CLI 版本是严格对应的不要拿 A 版本的 CLI 去部署 B 版本的 TKG否则插件下载、模板匹配都会出问题。下载时看清版本命名最好在本地记录下来后面排查时能省很多事。3.2 同步插件management-cluster 与 cluster首次运行 tanzu CLI 时它会提示本地没有插件。由于 TKG 的插件是从发布渠道动态分发的你需要先执行一次插件同步不同小版本命令可能叫tanzu init或tanzu plugin sync按 CLI 启动时的提示操作即可。完成后执行tanzu plugin list正常情况下列表里应该能看到management-cluster、cluster、kubernetes-release这几个核心插件。如果插件列表为空或者某个插件下载时卡死通常是本地缓存损坏造成的。把~/.cache/tanzu和~/.tanzu目录删掉重新同步一次绝大多数情况能解决。3.3 kubectl 和 kubeconfig 管理的小习惯tanzu CLI 在创建完集群后会把 kubeconfig 写到本地。我强烈建议通过环境变量把它指向一个独立文件不要直接往默认的~/.kube/config里覆盖export KUBECONFIG~/.kube/tkg-config这样管理集群和工作负载集群的凭据都汇总在一个文件里后续用kubectl config get-contexts就能清楚看到所有环境切换上下文也非常方便。否则装完几个集群后默认 kubeconfig 会被搞成一锅粥。4. 部署管理集群配置文件逐项解析4.1 管理集群配置文件的结构与字段含义执行tanzu management-cluster create前需要准备一份 YAML 配置文件。不同 TKG 版本的字段名有小幅差异但核心含义一致。一个典型配置长这样VSPHERE_SERVER: vcenter.example.local VSPHERE_USERNAME: administratorvsphere.local VSPHERE_PASSWORD: your-password-here VSPHERE_DATACENTER: /dc1 VSPHERE_DATASTORE: /dc1/datastore/ds1 VSPHERE_RESOURCE_POOL: /dc1/host/cluster1/Resources/tkg-resource-pool VSPHERE_NETWORK: /dc1/network/tkg-mgmt-network VSPHERE_FOLDER: /dc1/vm/tkg-folder VSPHERE_SSH_AUTHORIZED_KEY: ssh-rsa AAAA... VSPHERE_TLS_THUMBPRINT: SHA1-FINGERPRINT CONTROL_PLANE_NODE_COUNT: 3 VSPHERE_CONTROL_PLANE_CPU: 4 VSPHERE_CONTROL_PLANE_MEMORY_MIB: 8192 SERVICE_CIDR: 100.64.0.0/13 CLUSTER_CIDR: 100.96.0.0/11我逐个说下关键字段的作用VSPHERE_SERVER和账号密码就不多解释了。需要说明的是密码会经过加密存入集群的 secret 中留在配置文件里不是大问题但配置文件本身建议设置好权限别随手放公共目录。VSPHERE_TLS_THUMBPRINT是 vCenter 的 CA 证书指纹。TKG 连接 vCenter 时会校验证书不填或者填错会在 preflight 阶段报错。获取方法是在能访问 vCenter 的机器上执行openssl s_client -connect vcenter.example.local:443 /dev/null 2/dev/null | openssl x509 -fingerprint -sha1 -noout输出结果里SHA1 Fingerprint后面的内容就是指纹注意把冒号去掉小写格式写在配置里。VSPHERE_RESOURCE_POOL和VSPHERE_FOLDER的路径格式要写完整从 vCenter 对象路径开始。这里最容易踩坑的是路径多一层少一层建议直接去 vCenter Web 界面复制对象路径不要手敲。SERVICE_CIDR和CLUSTER_CIDR是集群内部网段一个分配给 Service一个分配给 Pod。要在开始就确认它们不会和已有网络重叠。4.2 管理集群规格怎么定管理集群本身也是 Kubernetes 集群所以它也有控制面节点。TKG 里控制面节点数量和规格由这几个参数决定参数开发环境建议生产环境建议CONTROL_PLANE_NODE_COUNT13VSPHERE_CONTROL_PLANE_CPU24VSPHERE_CONTROL_PLANE_MEMORY_MIB40968192控制面节点数量为 1 时etcd 和 kube-apiserver 都跑在同一台虚拟机上管理集群本身没有高可用能力。如果只是测试 TKG 功能1 台够用如果是给团队当底座直接上 3 台否则管理集群一挂所有工作负载集群的管理操作都会瘫痪。4.3 执行创建并观察过程配置文件就绪后执行tanzu management-cluster create --file mgmt-cluster.yaml -v 6-v 6是日志级别数值越大输出越详细。创建过程通常分几个阶段在本地用 Docker 拉起 bootstrap 临时集群通过 Cluster API 在 vCenter 里创建管理集群控制面虚拟机控制面初始化完成后把集群状态从 bootstrap 迁移到新管理集群删除本地 bootstrap 集群。整个过程根据 vCenter 性能不同一般在 15 到 30 分钟不等。期间你会看到大量 Manifest、Machine、Cluster 的状态输出不要因为中间某个阶段日志报红就急着终止很多 Warning 是正常的。创建完成后执行tanzu management-cluster get tanzu management-cluster kubeconfig get --admin用kubectl config use-context切换到管理集群上下文执行kubectl get nodes看到控制面节点 Ready管理集群就算部署成功。这里有一个实用经验TKG 的完整日志会写入本地的~/.tanzu/tkg/logs/目录。如果创建过程异常先别急着重新运行去这个目录看最近的日志文件里面通常有比命令行输出更具体的报错原因。4.4 创建过程中的三个重要提醒第一安装过程中不要按 Ctrl-C。如果你觉得卡住了先开另一个终端去看日志确认是否还在推进。中途强行终止的话vCenter 里可能已经创建了一半虚拟机留下一个半初始化状态的管理集群清理起来比正常重试更麻烦。第二确保 bootstrap 机的 Docker 处于健康状态。我之前遇到过 Docker 磁盘占用满了本地 bootstrap 集群容器反复重启管理集群创建卡在Waiting for bootstrap cluster阶段。提前执行docker system prune清理无用镜像可以避免这个尴尬。第三配置文件里的路径一旦写错会报resource not found之类的错误。排查时直接用 vCenter 里的实际路径对照配置文件多数问题一眼就能看出来。5. 创建工作负载集群并接入现有 kubectl5.1 工作负载集群配置文件的关键差异管理集群就绪后真正的业务集群开始登场。工作负载集群的配置类似但参数更偏向业务侧一个典型文件如下CLUSTER_NAME: workload-dev CLUSTER_PLAN: dev VSPHERE_DATACENTER: /dc1 VSPHERE_DATASTORE: /dc1/datastore/ds1 VSPHERE_RESOURCE_POOL: /dc1/host/cluster1/Resources/tkg-workload-pool VSPHERE_NETWORK: /dc1/network/tkg-workload-network CONTROL_PLANE_NODE_COUNT: 1 WORKER_NODE_COUNT: 3 VSPHERE_WORKER_DISK_GIB: 40CLUSTER_PLAN是一个快速预设参数dev对应较小的节点规格prod对应较大规格。实际生产建议不要依赖 PLAN 的默认值直接指定 VSPHERE_WORKER_CPU、VSPHERE_WORKER_MEMORY_MIB 更可控。工作负载集群的 CIDR 不需要重复配置默认会继承管理集群的规划除非你有特殊隔离需求。如果你希望某些业务集群落在不同资源池或不同网络在这个文件里指定即可。多集群环境通常会把不同业务的集群放进独立资源池方便做配额和成本核算。5.2 创建命令与状态观察执行创建命令tanzu cluster create --file workload-dev.yaml创建过程中你可以在另一个终端用以下命令观察状态tanzu cluster list -A-A表示查看所有命名空间的集群。新集群的 NAME 会出现在列表中状态从provisioning到running。这个过程不再需要本地 bootstrap 集群完全由管理集群驱动所以理论上管理集群健康就能继续创建。工作负载集群的创建时间通常在 10 到 20 分钟。如果长时间卡在某个节点上重点检查 vCenter 里对应虚拟机是否正常启动、网络是否能通信。5.3 获取 kubeconfig 并验证集群可用性工作负载集群创建完成后需要单独拉取它的 kubeconfigtanzu cluster kubeconfig get workload-dev --admin页面会提示如何切换上下文。由于前面设置了KUBECONFIG~/.kube/tkg-config所有集群的凭据都汇总在同一个文件里直接切换上下文即可kubectl config use-context workload-dev-adminworkload-dev kubectl get nodes看到节点全部 Ready 后做两个基础验证查看集群内系统组件状态kubectl get pods -A确认 Antrea 等 CNI 组件处于 Running部署一个测试应用比如启动一个 Nginx Pod确认 Pod 能正常调度和访问。到这里一次完整的 TKG 安装闭环就算走通了管理集群在工作工作负载集群跑起了业务之后你可以通过tanzu cluster scale、tanzu cluster upgrade、tanzu cluster delete来管理这个集群的生命周期。6. 常见问题与排查技巧实录6.1 故障速查表把我在几次部署中遇到的典型问题整理成表遇到对应现象直接对照处理现象可能原因处理方法创建卡在 Waiting for bootstrap clusterbootstrap 机 Docker 异常或磁盘满检查 docker info执行 docker system prune 清理preflight 报模板不兼容内容库 OVA 与 CLI 版本不匹配重新导入对应版本的 OVA节点一直 NotReadyCNI 未就绪或 Pod 网段冲突查看 Antrea 日志确认 CLUSTER_CIDR 不与现有网络重叠报 context deadline exceededDNS 解析或 NTP 时间偏移检查 vCenter FQDN 解析执行 chronyc tracking 看时间偏差无法 SSH 连接新节点网络策略或 SSH Key 配置错误确认节点网络可达检查 VSPHERE_SSH_AUTHORIZED_KEY插件下载失败本地缓存损坏或版本不匹配删除 ~/.cache/tanzu 和 ~/.tanzu重新同步6.2 两个值得单独说的坑第一个坑是 bootstrap 机断电。有一次我执行管理集群创建时安装机意外重启重开后发现之前的临时集群已经没了但 vCenter 里管理集群的虚拟机已经存在。这时如果直接重新执行 create会提示集群名冲突。我的处理方式是用tanzu management-cluster list确认残留状态把 vCenter 里残留的虚拟机清理干净再重新创建。不要尝试硬修不完整的管理集群删除重建的成本往往更低。第二个坑是 vCenter 里的路径问题。TKG 某些操作对文件夹或资源池名称大小写敏感之前我在配置里把资源池路径写成了资源池名字结果 preflight 阶段一直报找不到对象。后来打开 vCenter 界面复制完整路径一次通过。所有 vCenter 路径字段都建议以界面显示为准不要凭记忆写。6.3 排查问题的三条经验第一先看日志再动手。TKG 的日志信息量其实不少~/.tanzu/tkg/logs/下的文件会记录到具体的 API 调用和报错原因比命令行输出可靠得多。第二优先检查网络基础项。TKG 是分布式的任何节点之间的网络不通、DNS 解析不到、时间不同步都会表现为各种奇怪的超时或证书错误。这三大基础项没问题大多数安装失败案例都能排除一半原因。第三不要在一个环境上反复重试同一个错误。Cluster API 的优势在于“一切皆可重来”遇到持久性故障最快的方式是把半成品环境删除重新创建。很多初学者会陷入“改一个小参数再试一次”的循环实际效率远不如重建。最后再分享一个个人习惯TKG 这种基于 Cluster API 的部署方式和传统手工初始化 Kubernetes 完全不同。出现问题后我一般不会在单个节点上死磕而是快速删除重建充分利用它的生命周期管理能力。只要 vCenter 资源足够多试几次你对整个集群生命周期的掌控感会明显增强。希望这份安装记录能帮你少踩一些坑顺利把 TKG 用起来。