← 文章 / 云原生与基础设施
freeCodeCamp 2026/10/16 · 2026-10-16 00:55:22 · 17 阅读

如何在 GKE 上用 GitHub Actions、Ingress 和自动 TLS 构建 PR 临时预览环境

每个做软件的团队最终都会搭建一个 staging 环境,而每个搭了 staging 环境的团队最终都会遇到同一个问题。

Staging 是共享的:一个环境,无数个 pull request。有人部署了一个半成品功能来测试,另一个人又往上面叠加了部署,第三个人还跑了一次数据库迁移。到周四下午,没人说得清现在跑的到底是哪个分支的哪个版本,"staging 上没问题"这句话也彻底失去了意义。

于是各种变通办法层出不穷:在 Slack 频道里像抢会议室一样认领 staging、排部署时间表轮流用,或者再建第二个、第三个 staging 环境——而它们每一个都离生产环境配置越来越远。

其实有更好的模式,Vercel、Netlify、Shopify 等公司的平台团队早已把它变成标配:给每个 pull request 独立的环境。

打开一个 PR,就自动部署一个全新且隔离的应用副本;再推一个 commit,它就自动更新;合并或关闭 PR,整套环境自动销毁。不用排队、不用认领、不用手动清理,也不会产生配置漂移。

这就是本教程要构建的东西。从 reviewer 的视角看是这样的:PR 上出现一条 bot 评论,附带一个可正常访问的 URL。

A GitHub pull request thread showing an automated bot comment titled "Preview environment is ready", containing a live HTTPS URL, the commit SHA, and the namespace name, with all checks passing below it.

你要构建什么

读完这篇手册,你将拥有一套这样的系统:

  • 打开 pull request 会触发 GitHub Actions workflow,构建一个专门为该 PR 打标签的容器镜像

  • 镜像被推送到 Google Artifact Registry

  • 在 GKE 集群内创建专用 Kubernetes namespace(pr-42、pr-43 等),并在任何东西部署之前先应用资源配额

  • 应用部署到该 namespace 中,与其他所有 PR 的环境完全隔离

  • 共享的 Ingress controller 将 pr-42.preview.yourdomain.com 路由到该 namespace,并自动签发有效的 TLS 证书

  • 一个机器人会在 PR 上评论实时 URL,并在每次推送时更新同一条评论

  • 推送新提交时会用更新后的代码重新部署环境

  • 关闭或合并 PR 时,删除该命名空间及其内部所有资源

  • 一个定时任务负责清理那些被正常销毁流程遗漏的环境

你还将使用 Terraform 构建底层基础设施,其中包含三个关键设计决策,每个决策都有独立章节阐述。

  1. 不使用服务账号密钥:GitHub Actions 通过 Workload Identity Federation 向 Google Cloud 进行身份验证。使用针对仓库声明验证的短期 OIDC token。GitHub Secrets 中存放的服务账号 JSON 密钥是目前 CI/CD 流水线中常见的高危安全问题,而这里完全不需要。

  2. 一个负载均衡器,而非每个 PR 一个:一个共享的 Ingress 控制器按主机名路由所有环境,一条通配符 DNS 记录即可覆盖所有可能存在的主机名。朴素的做法是为每个环境配置一个云负载均衡器,成本会迅速失控。

  3. 假设清理会失败:PR 关闭时执行销毁操作。但还有一个定时清理任务,它会删除那些 PR 已消失或超过最大存活时间的命名空间。因为即使 95% 的自动清理有效率,剩下的泄漏也会体现在账单上。

以下是我们要实现的架构:

完整系统的架构示意图。GitHub Actions 通过 Workload Identity Federation 和 Artifact Registry 构建并部署到 GKE 集群,而浏览器通过通配符 DNS、共享的 Google Cloud 负载均衡器以及由 cert-manager 处理 TLS 的 NGINX Ingress 控制器访问每个 PR 的命名空间。

图中展示了同一系统中的两条独立路径。

实线蓝色路径代表自动化流程。PR 触发 GitHub Actions,通过 Workload Identity Federation 向 Google Cloud 进行身份验证,将带有 PR 标签的镜像推送到 Artifact Registry,并部署到 GKE 集群中的专用命名空间。

每个命名空间(如 pr-42、pr-43 等)都持有自己的 Deployment、Service 和 Pod,与其他命名空间完全隔离。

还有两个自动化组件与之协同工作:一个机器人负责在 Pull Request 上发布并更新预览 URL,以及一个定期运行的清理任务,用于查找并删除孤立的命名空间。

图中虚线绿色路径代表公网流量。浏览器对预览 URL 的请求通过一条通配符 DNS 记录解析到一个 Google Cloud 负载均衡器,然后由共享的 NGINX Ingress 控制器接管。该控制器读取请求的 Host 头,并将其路由到正确的命名空间。cert-manager 运行在一旁,从 Let's Encrypt 申请证书,确保每个环境都能获得独立的合法 TLS 证书。

关键点在于哪些资源*不*随环境数量增加。无论有多少个 Pull Request 处于打开状态,始终只使用一个负载均衡器、一条 DNS 记录和一个 Ingress 控制器服务所有环境。

目录

前置条件

开始之前,请确保已准备好以下内容:

  • 一个已启用计费的 Google Cloud 项目。如果没有,可以在 console.cloud.google.com 创建。跟着本教程操作大约会花费 5–10 美元,具体取决于集群运行多久,最后别忘了完成文末的清理步骤。

  • 已安装并完成认证的 gcloud CLI。运行 gcloud auth login 登录,再执行 gcloud config set project YOUR_PROJECT_ID 指定你的项目。

  • Terraform 1.5 或更高版本,可用 terraform version 检查。

  • 已安装 kubectl,这是与 Kubernetes 集群交互的命令行工具。

  • 本地安装了 Docker,用于在交给 CI 之前测试构建。

  • 一个你拥有的 GitHub 仓库。你必须能向该仓库推送分支并发起 Pull Request,因为这些操作是后续所有构建流程的触发源。

  • 熟悉 Docker(镜像、分层、Dockerfile)、Kubernetes(Pods、Deployments、Services、Namespaces)以及 GitHub Actions(Workflows、Jobs、Steps)。你不需要精通,但得了解这些概念。

  • Helm 3 版本,用于安装 Ingress controller 和 cert-manager。可通过 helm version 检查。

  • 一个你控制的域名,且具备添加 DNS 记录的能力。注册商无关紧要。你需要将其中一个子域专门用于预览环境,例如 preview.yourdomain.com,所有环境都将挂载在此子域之下。

关于域名要求的说明:这是项目中无法“造假”的部分。Let's Encrypt 在颁发证书前,必须验证你确实控制该域名。验证方式是从公网发起真实的 HTTP 请求。.local 域名、/etc/hosts 中的条目,或你未拥有的域名均无法通过验证。

如果没有现成的闲置域名,购买一个 .dev 或 .xyz 域名每年只需几英镑,对于这类项目来说非常划算。

还有件事需要早期注意:你还需要 gke-gcloud-auth-plugin。较新版本的 gcloud 在首次连接 GKE 集群时会提示安装此插件。你可以提前安装:

gcloud components install gke-gcloud-auth-plugin

步骤 1:搭建项目结构

先规划目录结构,以便清晰理解各部分的位置。

mkdir -p pr-preview-envs/{app,terraform,k8s/base,.github/workflows}
cd pr-preview-envs
git init

各目录包含内容如下:

  • app/:Go 应用及其 Dockerfile

  • terraform/:基础设施即代码:包括 GKE 集群、Artifact Registry 以及 Workload Identity Federation 配置

  • k8s/base/:作为所有预览环境基础配置的 Kubernetes 清单文件

  • .github/workflows/:用于创建和销毁环境的两个 GitHub Actions 工作流

现在将此配置连接到 GitHub 仓库,因为第 5 步中的 Workload Identity Federation 设置需要知道仓库的完整名称(owner/repo):

git remote add origin https://github.com/YOUR_USERNAME/pr-preview-envs.git

第二步:编写应用程序

我们需要一个可部署的对象。这里选用 Go,有三个针对本项目的具体理由。

首先,Go 编译为单个静态链接的二进制文件。无需安装运行时或解释器,这意味着容器镜像非常小;小镜像意味着推送和拉取速度快,而这对于在每个开放 PR 的每次提交时构建镜像至关重要。

其次,Go 的 -ldflags -X 机制允许我们在构建时向二进制文件注入值。我们将利用这一点将 PR 编号和 Git 提交 SHA 直接“烘焙”进应用中,这样运行中的应用就能准确告知我们它是哪个构建版本。

最后,Go 的构建速度很快,而 CI 分钟数并不是免费的。

创建 app/main.go:

package main

import (
	"fmt"
	"net/http"
	"os"
)

// These values are empty at compile time and get injected by the
// linker via -ldflags -X during the Docker build. See the Dockerfile.
var (
	prNumber = "local"
	gitSha   = "dev"
)

func handler(w http.ResponseWriter, r *http.Request) {
	// Kubernetes injects these via the Downward API — see deployment.yaml
	namespace := os.Getenv("POD_NAMESPACE")
	podName := os.Getenv("POD_NAME")

	if namespace == "" {
		namespace = "not-in-kubernetes"
	}
	if podName == "" {
		podName, _ = os.Hostname()
	}

	fmt.Fprintf(w, "Preview environment is live\n\n")
	fmt.Fprintf(w, "PR number  : %s\n", prNumber)
	fmt.Fprintf(w, "Git SHA    : %s\n", gitSha)
	fmt.Fprintf(w, "Namespace  : %s\n", namespace)
	fmt.Fprintf(w, "Pod name   : %s\n", podName)
}

func healthz(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	fmt.Fprintln(w, "ok")
}

func main() {
	http.HandleFunc("/", handler)
	http.HandleFunc("/healthz", healthz)

	fmt.Println("Server starting on port 8080...")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		fmt.Fprintf(os.Stderr, "server error: %v\n", err)
		os.Exit(1)
	}
}

在 app/ 目录内初始化 Go 模块:

cd app
go mod init preview-app

下面我们来看看这段代码在做什么,以及为什么要有这些部分。

var prNumber = "local" 和 var gitSha = "dev" 是两个带默认值的包级字符串变量。如果你不走 Docker 构建、直接在本地运行二进制,看到的就是这些默认值。

在 CI 构建时,Go 链接器会把它们覆盖为真实的 PR 编号和 commit SHA。这是整个项目里最实用的调试特性:访问一个 preview 环境时,应用自己就会告诉你它是从哪个 commit 构建的,完全不用猜。

os.Getenv("POD_NAMESPACE") 和 os.Getenv("POD_NAME") 读取的是 Kubernetes 通过 Downward API 注入到容器里的环境变量。我们会在第 8 步的 deployment 清单里配置这部分。

Downward API 让 Pod 无需任何 Kubernetes API 凭证就能读取自己的元数据(名称、namespace、标签)。这是让应用知道自身运行位置最简洁的方式。

handler 函数注册在根路径 / 上,会把 PR 编号、commit SHA、namespace 和 Pod 名称写入响应。这四项信息加在一起,就能回答“我现在看的到底是什么”。

healthz 函数注册在 /healthz,返回 HTTP 200 和文本 ok。Kubernetes 用这个端点做存活和就绪探针,我们会在 deployment 清单里配置。

http.ListenAndServe(":8080", nil) 在 8080 端口启动服务器。如果启动失败,它会打印错误并以非零状态码退出,这样 Kubernetes 就知道容器出了问题并进行重启。

继续之前,先在本地测试一下:

go run main.go

再开一个终端:

curl http://localhost:8080

由于没经过 Docker 构建,你应该会看到 PR number : local 和 Git SHA : dev。这就是本地运行的预期结果。

curl 终端输出:在 Docker 构建环境外运行时,应用报告 PR 编号为 local,Git SHA 为 dev

第三步:编写 Dockerfile

创建 app/Dockerfile:

# -----------------------------------------------------------
# 阶段 1:构建
# -----------------------------------------------------------
FROM golang:1.27-alpine AS builder
#确保版本与 go.mod 文件中保持一致

# 这些变量由 CI 流水线在构建时注入
ARG PR_NUMBER=local
ARG GIT_SHA=dev

WORKDIR /app

# 先复制 go.mod,以便 Docker 缓存依赖层
COPY go.mod .
RUN go mod download

COPY main.go .

# -w -s 剥离调试符号(二进制文件可缩小约 30%)
# -X 在链接时覆盖包级字符串变量
RUN CGO_ENABLED=0 go build \
    -ldflags="-w -s -X main.prNumber=${PR_NUMBER} -X main.gitSha=${GIT_SHA}" \
    -o server main.go

# -----------------------------------------------------------
# 阶段 2:运行时
# -----------------------------------------------------------
FROM alpine:latest

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

WORKDIR /app
COPY --from=builder /app/server .

EXPOSE 8080
CMD ["./server"]

其中有几个关键点需要理解清楚。

1. -ldflags -X 注入机制

-X main.prNumber=${PR_NUMBER}

-X 链接器标志用于在链接时设置包级字符串变量的值。语法为 -X importpath.name=value。由于变量位于 package main 中,导入路径即为 main。

此方法仅适用于源代码中已声明的 string 类型变量。无法通过这种方式创建新变量,也不能向 int 或 bool 类型变量注入值。这就是 main.go 中的 prNumber 被定义为字符串而非数字类型的原因。

为什么不直接在部署清单中传递环境变量?因为构建元数据归属于镜像本身,而非部署配置。如果通过环境变量传递,就可能有人将镜像 abc123 部署上去,却谎称它是提交 def456,而应用会默不吭声地接受这个谎言。将元数据直接编译进二进制文件中,就能确保镜像只能报告它真实的身份信息。

CGO_ENABLED=0 标志

默认情况下,Go 可以链接 C 库。一旦这样做,生成的二进制文件在运行时就会依赖系统的 C 库。Alpine 使用的是 musl 而非更常见的 glibc,这种不匹配是典型的“在构建阶段正常,在运行阶段崩溃”错误的根源。

设置 CGO_ENABLED=0 会强制生成纯 Go、完全静态的二进制文件,不依赖任何外部库。这样的二进制文件可以在任何 Linux 系统上运行,包括空的 scratch 镜像。

在 COPY main.go . 之前执行 COPY go.mod .

Docker 按层构建镜像并缓存每一层。先只复制 go.mod 并执行 go mod download,再复制源代码,就能创建一个被缓存的依赖层。

在后续构建中(记住,这条流水线会为每个打开的 PR 的每次提交触发构建),只要 go.mod 没变,Docker 就会跳过依赖下载。对于一个拥有数十个依赖的实际项目来说,这相当于在 20 秒构建和 3 分钟构建之间的巨大差别,而团队每推送一次代码,这个差距就会被放大一次。

非 Root 用户

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

容器默认以 root 身份运行。如果攻击者发现应用漏洞,以 root 身份运行容器会给他们提供更大的权限提升空间。创建一个非特权用户并切换过去,可以限制爆炸半径。这只需两行代码,没有任何理由不做。

在本地构建并测试:

docker build --build-arg PR_NUMBER=99 --build-arg GIT_SHA=abc1234 -t preview-app:test .
docker run -p 8080:8080 preview-app:test

然后在另一个终端执行 curl http://localhost:8080。你应该能看到 PR number : 99 和 Git SHA : abc1234。注入成功。

终端 curl 输出,应用显示 PR 编号 99 和 Git SHA abc1234,它们由 Docker 构建参数在构建时注入

第 4 步:用 Terraform 创建基础设施

接下来搭建云基础设施。我们选择 Terraform 而不是一堆 gcloud 命令,原因在出问题时才最明显:一条 terraform destroy 就能按正确顺序清理所有创建的资源,不会有被遗忘的资源在背后悄悄计费。

创建 terraform/variables.tf:

variable "project_id" {
  description = "GCP project ID"
  type        = string
}

variable "region" {
  description = "GCP region"
  type        = string
  default     = "europe-west2"
}

variable "zone" {
  description = "GCP zone. A zonal cluster is cheaper than a regional one."
  type        = string
  default     = "europe-west2-a"
}

variable "cluster_name" {
  description = "Name of the GKE cluster"
  type        = string
  default     = "pr-preview-cluster"
}

variable "github_repo" {
  description = "GitHub repository in owner/repo format, e.g. amina/pr-preview-envs"
  type        = string
}

variable "machine_type" {
  description = "Node machine type"
  type        = string
  default     = "e2-standard-2"
}

variable "node_count" {
  description = "Number of nodes in the pool"
  type        = number
  default     = 2
}

然后创建 terraform/main.tf:

terraform {
  required_version = ">= 1.5"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

# 查询当前项目以获取其数字项目 ID,
# Workload Identity Federation 需要该 ID(不接受人类可读的项目名称)。
data "google_project" "current" {}

# -----------------------------------------------------------
# 启用必需的 API
# -----------------------------------------------------------
resource "google_project_service" "apis" {
  for_each = toset([
    "container.googleapis.com",
    "artifactregistry.googleapis.com",
    "iamcredentials.googleapis.com",
    "sts.googleapis.com",
  ])

  service            = each.value
  disable_on_destroy = false
}

# -----------------------------------------------------------
# Artifact Registry — 存放预览镜像的位置
# -----------------------------------------------------------
resource "google_artifact_registry_repository" "preview" {
  location      = var.region
  repository_id = "pr-preview"
  description   = "PR 预览环境的容器镜像"
  format        = "DOCKER"

  depends_on = [google_project_service.apis]
}

# -----------------------------------------------------------
# GKE 集群
# -----------------------------------------------------------
resource "google_container_cluster" "primary" {
  name     = var.cluster_name
  location = var.zone

  # 创建集群时先使用一次性的默认节点池,随后删除该节点池,
  # 并改用独立的节点池资源来管理节点。这是标准做法——
  # 允许调整或升级节点池而无需重建集群控制平面。
  remove_default_node_pool = true
  initial_node_count       = 1

  networking_mode = "VPC_NATIVE"
  ip_allocation_policy {}

  # 在生产环境中使用前请设为 true。
  deletion_protection = false

  depends_on = [google_project_service.apis]
}

resource "google_container_node_pool" "primary_nodes" {
  name       = "${var.cluster_name}-pool"
  location   = var.zone
  cluster    = google_container_cluster.primary.name
  node_count = var.node_count

  node_config {
    machine_type = var.machine_type
    disk_size_gb = 50

    oauth_scopes = [
      "https://www.googleapis.com/auth/cloud-platform",
    ]

    labels = {
      purpose = "pr-preview-envs"
    }
  }

  management {
    auto_repair  = true
    auto_upgrade = true
  }
}

这里有几点值得关注。

data "google_project" "current" 并不创建任何资源。它是一个数据源,用于从提供商读取现有信息。我们需要它,是因为 Workload Identity Federation 通过数字项目编号而非你在控制台输入的项目 ID 来识别项目。这样 Terraform 可以自动获取该编号,省去了你手动查找并粘贴的步骤。

对 google_project_service 使用 for_each:与其编写四个几乎相同的资源块来启用四个 API,不如让 for_each 遍历一个集合,为每个项创建一个资源。disable_on_destroy = false 意味着运行 terraform destroy 时不会关闭这些 API,这通常是你想要的,因为项目中的其他资源可能正在使用它们。

remove_default_node_pool = true:创建集群时,GKE 会强制创建一个默认节点池。设置此选项会立即删除默认池,我们将节点池定义为独立的资源。好处是,后续对节点池的更改(如调整大小、变更机型、升级)不会强制更新集群资源本身。

node_count = 2 搭配 e2-standard-2:两个节点,每个节点 2 vCPU 和 8GB 内存。预览环境规模较小,但通常会同时运行多个,且 GKE 自身也有系统 Pod。两个节点提供了足够的余量。如果你计划同时保持大约八个以上预览环境存活,请增加节点数量。

deletion_protection = false:GKE 引入此选项以防止误删生产集群。由于这是一个最终会被删除的教程集群,我们将其设为 false。若将此配置用于生产环境,务必设为 true。

步骤 5:使用 Workload Identity Federation 配置无密钥认证

这是最关键的部分,让我们慢慢来。

服务账号密钥的问题

GitHub Actions 需要权限将镜像推送到 Artifact Registry 并部署到 GKE 集群。大多数教程的做法是:

  1. 在 GCP 中创建服务账号

  2. 为其生成 JSON 密钥

  3. 将该 JSON 粘贴到名为 GCP_SA_KEY 的 GitHub secret 中

  4. 在工作流中加载该密钥

这样能跑通,但存在安全隐患,原因如下:

第一,密钥永不过期。Service account JSON key 是长期有效的凭证,只有有人主动撤销才会失效——实际上就是永远有效,因为没人会记得去轮换。

第二,密钥就是 bearer token。谁拿到那个 JSON 文件,谁就是你的 service account。没有二次验证、没有 IP 限制、没有过期时间。复制文件,就能在世界任何地方使用。

第三,影响范围极大。GitHub secrets 会暴露给 workflow。被投毒的第三方 action、构建依赖中的恶意代码、或者 PR 中被篡改的 workflow,都可能把这个 secret 泄露出去。一旦泄露,攻击者就能持续访问你的云项目。

这不是危言耸听。Service account 密钥泄露是云安全事件最常见的根因之一。

Workload Identity Federation 如何解决这个问题

Workload Identity Federation 彻底去掉了长期密钥。流程如下:

  1. GitHub Actions 为当前运行的 workflow 生成一个短期的 OIDC token。这个 token 由 GitHub 签名,包含经过验证的声明(claims):是哪个仓库在运行、哪个分支、哪个 workflow、哪个操作者。

  2. Workflow 把这个 token 提交给 Google Cloud 的 Security Token Service。

  3. Google 用 GitHub 的公钥验证 token 签名,并根据你配置的规则检查 claims——具体来说,就是确认 token 确实来自你的仓库,而非其他任何仓库。

  4. 全部校验通过后,Google 签发一个短期的 access token,有效期通常约一小时。

  5. Workflow 使用这个 token,它很快就会过期。

整个过程中没有任何地方存储 secret,也就没有东西可以泄露、轮换或撤销。如果有人 fork 你的仓库并运行同样的 workflow,他们生成的 OIDC token 的 claims 里带的会是他们的仓库名,Google 校验不通过,什么都拿不到。

把下面的内容添加到 terraform/main.tf:

# -----------------------------------------------------------
# GitHub Actions 将要模拟使用的服务账号
# -----------------------------------------------------------
resource "google_service_account" "github_actions" {
  account_id   = "github-actions-preview"
  display_name = "GitHub Actions — PR 预览环境"
}

# 向 Artifact Registry 推送镜像的权限
resource "google_project_iam_member" "artifact_writer" {
  project = var.project_id
  role    = "roles/artifactregistry.writer"
  member  = "serviceAccount:${google_service_account.github_actions.email}"
}

# 在 GKE 中创建命名空间和部署工作负载的权限。
# container.developer 授予对 Kubernetes API 对象的完全访问权限,
# 但不允许修改集群本身。
resource "google_project_iam_member" "gke_developer" {
  project = var.project_id
  role    = "roles/container.developer"
  member  = "serviceAccount:${google_service_account.github_actions.email}"
}

# -----------------------------------------------------------
# 工作负载身份联合
# -----------------------------------------------------------
resource "google_iam_workload_identity_pool" "github" {
  workload_identity_pool_id = "github-pool"
  display_name              = "GitHub Actions 身份池"
  description               = "用于 GitHub Actions OIDC 的身份池"

  depends_on = [google_project_service.apis]
}

resource "google_iam_workload_identity_pool_provider" "github" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.github.workload_identity_pool_id
  workload_identity_pool_provider_id = "github-provider"
  display_name                       = "GitHub OIDC 提供者"

  # 将 GitHub OIDC 令牌中的声明映射到 Google 属性
  attribute_mapping = {
    "google.subject"       = "assertion.sub"
    "attribute.actor"      = "assertion.actor"
    "attribute.repository" = "assertion.repository"
  }

  # 关键:没有此条件,互联网上任何 GitHub 仓库都可能向你的池进行身份验证
  attribute_condition = "assertion.repository == '${var.github_repo}'"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }
}

# 允许来自你特定仓库的令牌模拟该服务账号
resource "google_service_account_iam_member" "github_impersonation" {
  service_account_id = google_service_account.github_actions.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/projects/${data.google_project.current.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github.workload_identity_pool_id}/attribute.repository/${var.github_repo}"
}

这里拆解几个最容易踩坑的细节。

attribute_mapping:GitHub 的 OIDC token 包含一组声明(claims)。这一段配置告诉 Google 需要读取哪些声明,以及内部如何命名这些字段。assertion.sub 是 token 的主体(类似 repo:owner/name:ref:refs/heads/main 的格式),assertion.repository 是完整的仓库名称。google.subject 是必填项,其他字段则是可选属性,后续可以基于它们编写规则。

attribute_condition:这一行请仔细阅读,因为配置错误会引发严重的安全漏洞:

attribute_condition = "assertion.repository == '${var.github_repo}'"

缺少这个条件的话,你的身份池将信任GitHub 的 OIDC 发行方,这意味着它会信任 GitHub 上的所有仓库。任何知道你的身份池资源路径(这不是机密,且常出现在工作流文件中)的人,都能进行认证并冒充你的服务账号。

这个条件将信任范围严格限制在特定仓库。由于很多人曾在此处出错,Google 现在强制要求在映射 assertion.repository 时设置属性条件。

principalSet://...:这是被授予 workloadIdentityUser 角色的主体。请从右往左解读:任何 github-pool 中 attribute.repository 与你仓库匹配的主体,都可以冒充该服务账号。注意这里使用的是 data.google_project.current.number,即数字项目 ID,而非项目名称。如果在此处使用项目名称,系统会报出一个错误信息不明确的问题,这是 WIF 配置中最常见的错误之一。

为什么选择 roles/container.developer 而不是 roles/container.admin?container.developer 授予了对集群内部 Kubernetes API 对象的完整访问权限:创建命名空间、应用 Deployment、删除资源等。container.admin 则额外允许修改集群本身:调整节点池大小、升级集群或完全删除集群。

我们的工作流从未需要触碰集群自身的配置,因此也不应拥有相应的权限。这就是最小权限原则的实际应用:只授予任务所需的最小权限,不多不少。

现在创建 terraform/outputs.tf:

output "cluster_name" {
  value = google_container_cluster.primary.name
}

output "cluster_zone" {
  value = var.zone
}

output "artifact_registry_url" {
  description = "镜像推送的基础 URL"
  value       = "${var.region}-docker.pkg.dev/${var.project_id}/${google_artifact_registry_repository.preview.repository_id}"
}

output "workload_identity_provider" {
  description = "把这个值粘贴到 GitHub Actions workflow 里"
  value       = "projects/${data.google_project.current.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github.workload_identity_pool_id}/providers/${google_iam_workload_identity_pool_provider.github.workload_identity_pool_provider_id}"
}

output "service_account_email" {
  description = "把这个值粘贴到 GitHub Actions workflow 里"
  value       = google_service_account.github_actions.email
}

output "get_credentials_command" {
  value = "gcloud container clusters get-credentials ${google_container_cluster.primary.name} --zone ${var.zone} --project ${var.project_id}"
}

这些 output 并不是摆设。workload_identity_provider 和 service_account_email 是接下来要粘贴到 GitHub Actions workflow 里的两个值,手动拼出来相当麻烦。

第 6 步:应用 Terraform 配置

进入 terraform/ 目录,执行:

terraform init

这一步会下载 Google provider 并配置 backend。看到 "Terraform has been successfully initialized!" 就说明成功了。

接着预览将要创建的资源:

terraform plan \
  -var="project_id=YOUR_PROJECT_ID" \
  -var="github_repo=YOUR_USERNAME/pr-preview-envs"

仔细看一遍 plan 的输出。Terraform 在真正创建之前会把要做什么全部列出来。正常情况下应该是新增十来个资源,没有任何修改或删除。

确认没问题后执行:

terraform apply \
  -var="project_id=YOUR_PROJECT_ID" \
  -var="github_repo=YOUR_USERNAME/pr-preview-envs"

提示时输入 yes。集群创建大约需要五分钟。

提示:反复输入 -var 参数很快就会让人厌烦。请创建一个名为 terraform.tfvars 的文件,其中包含 project_id = "your-project-id" 和 github_repo = "you/pr-preview-envs",Terraform 会自动读取该文件。记得将此文件添加到 .gitignore 中。

执行完成后,Terraform 会打印出输出结果。请保存这些信息,因为它们在步骤 9 中会被用到:

artifact_registry_url = "europe-west2-docker.pkg.dev/your-project/pr-preview"
service_account_email = "github-actions-preview@your-project.iam.gserviceaccount.com"
workload_identity_provider = "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider"

随时可以使用 terraform output 再次打印这些信息。

Terraform apply 的输出,显示所需的凭证信息

使用 get_credentials_command 输出中的命令,将 kubectl 连接到新集群:

gcloud container clusters get-credentials pr-preview-cluster \
  --zone europe-west2-a \
  --project YOUR_PROJECT_ID

验证连接:

kubectl get nodes

你应该能看到两个处于 Ready 状态的节点。

kubectl get nodes 的输出,显示两个 GKE 节点状态为 Ready

步骤 7:手动验证生命周期

在实现自动化之前,先手动操作一次。

这并非无用功。自动化本质上只是运行那些你原本可以手动输入的命令的脚本。如果不知道这些命令是什么,当自动化失败时你就无法调试……而它肯定会失败,通常发生在演示前一晚的 11 点。在这里花上十分钟,能节省以后的数小时。

创建一个命名空间:

kubectl create namespace pr-test

在其中部署一个占位程序:

kubectl create deployment hello \
  --image=nginx:1.27-alpine \
  --namespace=pr-test

检查状态:

kubectl get pods --namespace=pr-test

现在是关键部分——证明隔离性:

kubectl get pods --all-namespaces | grep hello
该 pod 仅存在于 pr-test 中。default 及其他任何命名空间对其均一无所知。这正是整个项目所依赖的核心特性:命名空间是一道边界,一个 PR 命名空间内的所有内容,对其余所有空间都不可见。 现在将其销毁:
kubectl delete namespace pr-test
观察后续变化:
kubectl get namespace pr-test
几秒钟内,状态将显示为 Terminating,随后该命名空间彻底消失。删除命名空间会移除其中包含的所有资源:deployments、pods、services、config maps、secrets,无一遗漏。一条命令,彻底清理。 正是这一特性,使得“每 PR 一个命名空间”成为预览环境的理想方案。销毁过程无需精心设计的删除序列,一条命令即可确保不留残迹。

第 8 步:使用 Kustomize 编写 Kubernetes 清单

每个预览环境部署的应用程序相同。pr-42 与 pr-43 之间的区别仅在于命名空间和镜像标签。 这正是 Kustomize 要解决的问题。你先编写一份基础的 base 清单,再在其上应用少量声明式修改(即 overlay),而无需使用模板、字符串替换或 sed 脚本来破坏 YAML 格式。 Kustomize 已内置于 kubectl(即 -k 参数),因此无需额外安装任何工具。 创建 k8s/base/deployment.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: preview-app
  labels:
    app: preview-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: preview-app
  template:
    metadata:
      labels:
        app: preview-app
    spec:
      containers:
        - name: preview-app
          # 这里只是占位符,overlay 会把它替换为
          # 真正的镜像仓库路径和 PR 专属的 tag。
          image: preview-app
          ports:
            - containerPort: 8080
          env:
            # Downward API:让 pod 获取自身的身份信息
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 2
            periodSeconds: 5
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "200m"
              memory: "128Mi"

创建 k8s/base/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: preview-app
spec:
  selector:
    app: preview-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP

创建 k8s/base/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml

这里有几个刻意的设计选择。

replicas: 1:生产环境为了可用性会跑多个副本,但预览环境不需要高可用。每个环境只跑一个副本,即使所有打开的 PR 都各有环境,节点数量和账单也能控制在合理范围内。

image: preview-app:一个不带仓库地址和 tag 的纯占位符,按原样肯定拉不下来镜像。Kustomize 的 image transformer 会按这个名字匹配并整体替换,所以 base 清单完全不需要知道你的镜像仓库地址。

Downward API env 块:POD_NAMESPACE 和 POD_NAME 由此获取。fieldRef 会在运行时读取 Pod 自身 spec 中的字段,并将其暴露为环境变量。无需 API 调用、凭证或 Service Account。

type: ClusterIP:仅限内部使用。每个 LoadBalancer 服务都会创建一个真实的 Google Cloud 负载均衡器,产生实际的每小时费用和公共 IP。按 PR 粒度创建既昂贵又浪费。当前我们先用 kubectl port-forward 访问应用;第 13 步中,单个共享的 Ingress 控制器将接管,通过一个负载均衡器服务所有环境。

资源 requests 与 limits:requests 预留容量,让调度器知道 Pod 需要多少空间;limits 则限制其最大消耗。没有 limits,一个失控的预览环境可能会耗尽节点上其他所有环境的资源。随着大量短生命周期环境频繁创建销毁,这项配置必不可少。

测试 base 是否正确渲染:

kubectl kustomize k8s/base

该命令会打印渲染后的 YAML,但不会实际应用。这在调试时很有用。

第 9 步:构建自举工作流

现在把所有东西连接起来。

创建 .github/workflows/preview-deploy.yml:

name: 部署 PR 预览

on:
  pull_request:
    types: [opened, synchronize, reopened]

# 如果某人快速推送了三个 commit,取消较早的运行。
# 否则,三个部署会竞争同一个命名空间,
# 最后完成的那个获胜——但未必是最新的 commit。
concurrency:
  group: preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

permissions:
  contents: read
  id-token: write   # Workload Identity Federation 必需
  pull-requests: write

env:
  PROJECT_ID: YOUR_PROJECT_ID
  REGION: europe-west2
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a
  REPOSITORY: pr-preview
  IMAGE_NAME: preview-app

jobs:
  deploy:
    name: 构建并部署预览
    runs-on: ubuntu-latest

    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置环境变量
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          SHORT_SHA=$(echo "${{ github.event.pull_request.head.sha }}" | cut -c1-7)

          echo "PR_NUMBER=${PR_NUMBER}"   >> $GITHUB_ENV
          echo "SHORT_SHA=${SHORT_SHA}"   >> $GITHUB_ENV
          echo "NAMESPACE=pr-${PR_NUMBER}" >> $GITHUB_ENV
          echo "IMAGE_TAG=pr-${PR_NUMBER}-${SHORT_SHA}" >> $GITHUB_ENV
          echo "IMAGE_BASE=${{ env.REGION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ env.REPOSITORY }}/${{ env.IMAGE_NAME }}" >> $GITHUB_ENV

      - name: 认证 Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: 配置 gcloud
        uses: google-github-actions/setup-gcloud@v2

      - name: 为 Artifact Registry 配置 Docker
        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet

      - name: 构建并推送镜像
        run: |
          docker build \
            --build-arg PR_NUMBER="${PR_NUMBER}" \
            --build-arg GIT_SHA="${SHORT_SHA}" \
            -t "${IMAGE_BASE}:${IMAGE_TAG}" \
            ./app

          docker push "${IMAGE_BASE}:${IMAGE_TAG}"

      - name: 获取 GKE 凭证
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: 创建命名空间
        run: |
          # --dry-run=client | apply 使操作具有幂等性。
          # 对已存在的命名空间执行此操作是无效操作,而非报错。
          kubectl create namespace "${NAMESPACE}" \
            --dry-run=client -o yaml | kubectl apply -f -

      - name: 生成 Kustomize 覆盖层
        run: |
          mkdir -p k8s/overlays/"${NAMESPACE}"
          cat > k8s/overlays/"${NAMESPACE}"/kustomization.yaml <<EOF
          apiVersion: kustomize.config.k8s.io/v1beta1
          kind: Kustomization

          namespace: ${NAMESPACE}

          resources:
            - ../../base

          images:
            - name: preview-app
              newName: ${IMAGE_BASE}
              newTag: ${IMAGE_TAG}
          EOF

          echo "--- 渲染后的清单 ---"
          kubectl kustomize k8s/overlays/"${NAMESPACE}"

      - name: 部署
        run: kubectl apply -k k8s/overlays/"${NAMESPACE}"

      - name: 等待滚动更新完成
        run: |
          kubectl rollout status deployment/preview-app \
            --namespace="${NAMESPACE}" \
            --timeout=180s

      - name: 显示部署详情
        run: |
          echo "命名空间: ${NAMESPACE}"
          kubectl get pods,svc --namespace="${NAMESPACE}"

添加两个 Secret

打开 GitHub 上的仓库页面,依次进入 Settings、Secrets and variables、Actions,点击 New repository secret,添加以下两个:

Secret 名称 值
WIF_PROVIDER Terraform 输出的 workload_identity_provider
WIF_SERVICE_ACCOUNT Terraform 输出的 service_account_email
GitHub 仓库 secrets 页面,显示 WIF_PROVIDER 和 WIF_SERVICE_ACCOUNT

严格来说这两个值都不是凭据。provider 路径和服务账号邮箱只是标识符,本身不授予任何权限,真正的访问控制靠的是 OIDC token 和 attribute condition。把它们存成 secret 只是为了管理规范。另外,记得把 workflow 中 env: 块里的 PROJECT_ID 和区域值改成你自己的配置。

理解这个 Workflow

on: pull_request: types: [opened, synchronize, reopened]:这是三个不同的触发条件。

  • opened:PR 首次创建时触发。

  • synchronize:后续每次向该分支推送代码时触发,保证预览环境始终是最新代码。

  • reopened:处理关闭后又重新打开的 PR。没有它,这个 PR 的环境已被销毁,就没有机制重建了。

concurrency:这个配置能省去不少调试时间。快速连续推送三个 commit,就会触发三次 workflow 运行,目标是同一个命名空间,于是产生竞争。最后完成的胜出,但那不一定是最新代码——一个跑得快的早期构建可能反超跑得慢的后续构建,导致预览环境悄悄跑着旧代码,而 PR 状态却显示绿色通过。按 PR 编号分组并设置 cancel-in-progress: true,就能保证只有最新一次运行存活。

permissions: id-token: write:缺少这行配置,后续所有操作都无法执行。它允许工作流向 GitHub 请求 OIDC token。如果遗漏此配置,google-github-actions/auth 会因无法获取 ID token 而报错。这是 Workload Identity Federation(WIF)配置中最常见的错误。

$GITHUB_ENV:向此文件写入 KEY=value 后,变量将在所有*后续*步骤中可用。当前步骤不行,因为在步骤中写入的变量无法在同一步骤后续代码中读取。这就是为什么设置操作要放在顶部独立的步骤中执行。

github.event.pull_request.head.sha:注意使用此变量而非 github.sha。在 pull_request 事件中,GitHub 检出的是一个*合并提交*(merge commit),这是将你的分支与基础分支组合而成的临时提交。github.sha 指向该合并提交,它并不存在于仓库历史中,会导致试图查找该提交的人产生困惑。head.sha 才是 PR 分支上的实际最后一次提交,也是开发者预期看到的版本。

--dry-run=client -o yaml | kubectl apply -f - 是一个值得借鉴的小技巧。kubectl create namespace 在命名空间已存在时会失败,这会导致首次推送后的所有后续推送都失败。该管道在不调用集群的情况下生成命名空间 YAML,然后通过管道传给 apply,如果缺失则创建,若已存在则不做任何操作。天然具备幂等性。

Heredoc 覆盖层:工作流在运行时动态写入一个覆盖层并在使用后丢弃,而不是为每个 PR 提交一个覆盖层(这是不可能的,因为你无法预知 PR 编号)。这是为临时环境设计的临时配置。

kubectl rollout status 确保了工作流结果的准确性。如果没有它,一旦 API 服务器接受 kubectl apply,任务就会立即标记为成功,而此时可能还没有任何 Pod 启动。即使镜像处于崩溃循环,状态也会显示为绿色对勾。rollout status 会阻塞直至 Pod 真正就绪,或者在 180 秒后失败。绿色代表真正可用。

关于 Fork 的 Pull Request

在把这个方案部署到任何公开环境之前,有一点需要特别注意:出于安全设计,来自 fork 仓库的 pull request 默认不会获得 id-token: write 权限。GitHub 这样做的目的是防止陌生人通过提交 PR 窃取你的云凭证。

对于私有仓库或个人项目,这没什么影响。但如果你是维护一个接受外部贡献的公开仓库,就需要采用基于 workflow_run 的模式:即由基础仓库在不可信的外部构建完成后,触发一个具有更高权限的工作流来处理后续步骤。这超出了本文的范围,但如果你要在开源项目中使用该方案,千万不要忽略这一点。

步骤 10:构建拆除工作流

仅仅创建环境只体现了一半的价值。如果环境永远不消失,它就像你云账单上一直滴水的漏点。

创建 .github/workflows/preview-teardown.yml:

name: Tear Down PR Preview

on:
  pull_request:
    types: [closed]

permissions:
  contents: read
  id-token: write

env:
  PROJECT_ID: YOUR_PROJECT_ID
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a

jobs:
  teardown:
    name: Delete preview namespace
    runs-on: ubuntu-latest

    steps:
      - name: Set namespace
        run: echo "NAMESPACE=pr-${{ github.event.pull_request.number }}" >> $GITHUB_ENV

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Get GKE credentials
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: Delete namespace
        run: |
          echo "Deleting namespace ${NAMESPACE}"
          kubectl delete namespace "${NAMESPACE}" \
            --ignore-not-found=true \
            --wait=false

      - name: Confirm
        run: |
          echo "Preview environment for PR #${{ github.event.pull_request.number }} torn down."

这里有几个细节比表面看起来更重要。

首先,types: [closed] 也涵盖合并操作。GitHub 并没有单独的 merged 事件类型,合并 PR 触发的仍然是 closed 事件,只是 payload 里会带上 merged: true 字段。所以这一个触发条件就能同时覆盖"合并成功"和"直接关闭"两种情况——两者都需要清理环境,无需区分。

接下来是 --ignore-not-found=true:如果命名空间不存在(比如部署失败过,或有人手动删掉了),kubectl delete 通常会报错退出,把整个 workflow 标红。但这其实是个误报——我们期望的最终状态就是"命名空间不存在",而它确实不存在。加上这个参数后,没有东西可删时这一步也会顺利通过。

最后是 --wait=false:命名空间的删除是异步的。Kubernetes 会先把它标记为 Terminating,然后逐一清理里面的资源。如果干等这个过程完成,CI runner 可能会被占用一分钟甚至更久,完全没必要。直接触发删除,让集群自己慢慢处理就行。

第 11 步:提一个 Pull Request,看看效果

提交所有改动并推送:

git add .
git commit -m "Add PR preview environment infrastructure"
git push -u origin main

现在创建一个分支,做一个肉眼可见的改动:

git checkout -b test-preview

编辑 app/main.go,修改 handler 输出的第一行:

fmt.Fprintf(w, "Preview environment is live — testing the pipeline\n\n")

提交并推送:

git add .
git commit -m "Test preview environment"
git push -u origin test-preview

在 GitHub 上创建一个 pull request,然后切到 Actions 标签页,应该能看到 "Deploy PR Preview" 正在运行。

GitHub Actions summary for a pull request showing the Deploy PR Preview workflow completed successfully

按顺序观察各个步骤:无需密钥即可完成认证,镜像构建并推送成功,命名空间创建完成,Kustomize 渲染 overlay(你会看到完整的最终 manifest 被打印出来),部署生效,最后 rollout status 会一直等待直到 Pod 就绪。

Expanded GitHub Actions log showing the deploy, wait for rollout, and show deployment details steps completing successfully

看到状态变绿后,在终端里验证一下:

kubectl get namespaces | grep pr-

你应该能看到对应的 pr-1(或者你的 PR 实际拿到的编号)。

kubectl get pods --namespace=pr-1

接下来访问应用:

kubectl port-forward --namespace=pr-1 service/preview-app 8080:80

再开一个终端:

curl http://localhost:8080

预期输出:

Preview environment is live — testing the pipeline

PR number  : 1
Git SHA    : a1b2c3d
Namespace  : pr-1
Pod name   : preview-app-7d9f8b6c4-xk2mp

应用正在报告编译时打进二进制里的 PR 编号、commit SHA,以及它通过 Downward API 发现到的 namespace。这些值分别由流水线的不同环节解析,且全部一致,这就证明整条链路是通的。

原始来源: freeCodeCamp

评论 (0)