📚 课程目录第4章环境准备与工具链搭建

4. 环境准备与工具链搭建

在真正开始用 Terraform 管理 Kubernetes 平台之前，必须先让本地或跳板机具备“能写、能连、能验”的三类能力：能写 Terraform 配置、能通过云厂商凭证调用 API、能用 kubectl 访问目标集群。本节围绕这三条链路展开，重点不是把命令抄一遍，而是理解每条链路中“输入是什么、凭证放在哪里、如何验证成功”。

一、安装 Terraform 并固定版本

Terraform 是声明式工具，版本差异会直接影响 provider 行为与语法支持。生产环境建议固定版本，而不是永远使用 latest。以 Linux x86_64 为例，可从 HashiCorp 官方发布页下载对应压缩包，解压后把二进制放入 /usr/local/bin：

# 示例：安装 Terraform 1.7.5（版本号仅为示例）
curl -fsSL -o terraform_1.7.5_linux_amd64.zip \
  https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
unzip terraform_1.7.5_linux_amd64.zip -d /usr/local/bin/
terraform version

执行 terraform version 后应输出 Terraform 版本号以及已安装的 provider 版本（首次运行可能为空）。如果团队多人协作，建议在项目根目录放置 .terraform-version 或使用 tfenv 统一版本，避免“我本地能跑、CI 上失败”的问题。安装完成后，建议立即执行一次 terraform init 的预演，确认能正常访问 registry：

mkdir -p ~/tf-k8s-demo && cd ~/tf-k8s-demo
cat > main.tf <<'EOF'
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 2.27"
    }
  }
}
EOF
terraform init

若 terraform init 成功，说明 Terraform 本体与 provider 下载链路已通。此时还没有任何云资源，属于“工具就绪”状态。

二、配置云厂商凭证

Terraform 调用云 API 时，凭证通常来自环境变量、共享凭证文件或实例角色。以 AWS 为例，最常用的方式是 ~/.aws/credentials 配合 AWS_PROFILE，或直接使用环境变量：

# 示例：使用命名 profile，避免污染默认凭证
export AWS_PROFILE=platform-dev
export AWS_REGION=ap-southeast-1
aws sts get-caller-identity

aws sts get-caller-identity 返回的 Account、Arn、UserId 就是“凭证是否有效”的直接证据。若使用阿里云、腾讯云或 Azure，思路一致：先通过 CLI 的 whoami 类命令确认身份，再让 Terraform 的 provider 读取同一套凭证。需要特别注意的是，凭证不要写进 .tf 文件，也不要提交到 Git；推荐用环境变量或 CI 的 Secret 注入。对于需要长期运行的平台，更稳妥的做法是给 Terraform 执行角色授予最小权限，而不是使用个人管理员 AK。

验证顺序建议：先 CLI 验证身份 → 再 terraform plan 验证 provider 能读到凭证 → 最后才创建资源。这样能把“凭证错误”和“配置错误”分开定位。

三、准备 kubectl 与集群访问入口

Terraform 负责“把集群建出来”，kubectl 负责“进去看和改”。两者使用的 kubeconfig 必须指向同一个集群。安装 kubectl 时同样建议固定版本，且与集群版本偏差不超过一个小版本。安装后通过 kubectl version --client 确认客户端版本。

集群访问入口的核心是 kubeconfig 文件，默认位于 ~/.kube/config。它由三部分组成：cluster（API Server 地址与 CA）、user（客户端证书或 token）、context（把 cluster 和 user 绑定并指定 namespace）。可以用 kubectl config view 查看当前配置，用 kubectl config get-contexts 列出所有上下文。切换集群时使用：

kubectl config use-context platform-dev
kubectl cluster-info
kubectl get nodes -o wide

如果 kubectl cluster-info 能返回 API Server 地址，且 kubectl get nodes 能看到节点列表，说明“访问入口”已打通。若返回 Unable to connect to the server，优先检查三件事：kubeconfig 中的 server 地址是否可达、证书是否过期、当前 context 是否指向正确集群。对于云托管 Kubernetes，通常由云 CLI 自动写入 kubeconfig，例如 aws eks update-kubeconfig --name <cluster> --region <region>；这一步本质上是把集群的 API 入口和认证信息写入本地配置。

四、三条链路的衔接关系

把上述内容串起来看，环境准备不是三个孤立步骤，而是一条有依赖的链路：Terraform 用云凭证创建或读取集群，集群产生 kubeconfig 入口，kubectl 再用该入口访问集群。任何一环断裂，后续的 Terraform Kubernetes provider 都会失败。下面的 SVG 展示了这三条链路之间的输入、凭证与验证关系。

图中左侧是工具链，中间是云凭证，右侧是 kubectl 与集群入口。三者不是并列关系，而是“工具 → 凭证 → 集群 → 入口 → 验证”的依赖链。特别要注意右下角那条虚线框：后续 Terraform 的 Kubernetes provider 会复用同一份 kubeconfig，因此本节验证通过的 kubeconfig，就是后面所有 Kubernetes 资源声明的基础入口。

五、常见问题与判断依据

环境准备阶段最容易出现三类问题。第一类是版本不匹配：Terraform 版本过低导致 provider 语法报错，或 kubectl 与集群版本偏差过大导致部分子命令不可用。判断依据是 terraform version 与 kubectl version 的输出，以及集群版本号。第二类是凭证失效：terraform plan 报 NoCredentialProviders 或 AccessDenied，此时先用云 CLI 的 whoami 命令确认身份，再检查权限策略是否覆盖所需 API。第三类是 kubeconfig 指向错误：kubectl get nodes 返回 connection refused 或 x509: certificate signed by unknown authority，通常说明 server 地址不可达或 CA 不匹配，需要重新执行云 CLI 的 update-kubeconfig 命令，或手动核对 kubectl config view 中的 cluster 段。

不要把 kubeconfig 直接提交到 Git 仓库。它包含集群地址、CA 和用户凭证，泄露后等同于把集群入口交给他人。CI 环境中应使用 Secret 注入，并在任务结束后清理临时文件。

完成本节后，可以用一条最小验证命令确认整条链路是否闭环：在 Terraform 项目中加入一个只读的 Kubernetes data source，例如查询 default namespace，然后执行 terraform plan。如果 plan 能正常输出，说明 Terraform、云凭证、kubeconfig 三者已经协同工作，可以进入下一阶段的资源声明与平台交付。