在 Google Kubernetes Engine（GKE）上运行 Istio 端到端集成测试：从 GCP 环境准备到镜像选择

Istio 仓库将 Kubernetes 环境下的端到端（E2E）集成测试设计为可以直接跑在开发者自有的集群上，而 GKE.md 就是指导如何在 Google Cloud Platform（GCP）上从零搭建 GKE 集群并运行这套测试的操作手册。本文以该文档为主线，结合仓库中 create_cluster_gke.sh 脚本、tests.mk 集成测试构建规则与 Makefile.core.mk 中的镜像变量定义，完整讲解「GCP 一次性准备 → 创建 GKE 集群 → 配置 Istio 镜像环境变量」三步流程，并延伸介绍测试真正落地运行时所需的 HUB/TAG 语义，帮助你快速复现 Istio 在真实 Kubernetes 集群上的 E2E 验证环境。

一、写在前面：E2E 测试要跑在什么环境上

在 tests/integration/README.md 中明确说明：Istio 集成测试的测试逻辑运行在测试二进制中，而测试目标是一个真实可用的 Kubernetes 集群。因此，在执行任何 go test ./... -p 1 之前，你必须先准备一个集群并提供其 kubeconfig，这一准备工作即由 GKE.md 承担——它专门面向 Google Kubernetes Engine 场景，是官方文档指明的 GKE 集群搭建参考。

整体流程分为三个步骤，也是本文的核心骨架：

• Step 1：GCP 一次性环境准备（gcloud SDK、项目、服务账号权限）；
• Step 2：创建并授权一个 GKE 集群（推荐使用配套脚本自动化完成）；
• Step 3：设置 Istio 构建/运行所需的环境变量（自建镜像或预发布镜像二选一）。

二、Step 1：GCP 一次性环境准备

这一步属于一次性（one-time）配置，用于创建并配置一个 GCP 项目，后续所有集群创建都复用它。

2.1 安装 Google Cloud SDK

若尚未安装 Google Cloud SDK，请先完成安装；可通过如下命令确认当前机器是否已经可用：

which gcloud

若命令有输出，则说明 gcloud 已存在于 PATH 中。

2.2 创建项目

在 Google Cloud Console 中创建一个 GCP 项目并记录其 Project ID（PROJECT_ID），后续创建集群时需要显式传入。请务必记录该项目对应的 Project Number，因为默认计算服务账号的命名依赖它。

2.3 配置 GCE/GKE 服务账号权限

在创建部署之前，必须给默认计算服务账号（default compute service account）授予正确的权限，否则后续安装会失败。该账号默认命名为：

[PROJECT_NUMBER][e-mail]

请在 Google Cloud Console 的 IAM 页面中，确认上述账号至少被授予以下两个角色：

角色	说明
Kubernetes Engine Admin（roles/container.admin）	允许管理 GKE 集群及其节点
Editor（roles/editor）	项目编辑者，默认已包含，一般无需额外操作

从脚本实现看，服务账号实际需要的能力会体现在 gcloud container clusters create 与凭据获取环节（见下节），角色缺失时 gcloud 会直接报权限类错误——这正是文档强调“必须提前配置，否则安装失败”的原因。

三、Step 2：创建并配置 GKE 集群

3.1 方式一：使用自动化脚本（推荐）

仓库在同目录下提供了自动化脚本 create_cluster_gke.sh，用于“创建并配置一个可供 Istio E2E 测试使用的 GKE 集群”。创建集群只需一行命令：

./tests/integration/create_cluster_gke.sh -c ${CLUSTER_NAME}

查看脚本支持的参数：

./tests/integration/create_cluster_gke.sh -h

脚本内部使用 getopts 解析命令行参数，并将其与环境变量默认值合并。从 create_cluster_gke.sh 源码（第 23-27 行、31-47 行）可以整理出完整的参数语义：

命令行参数	对应环境变量	默认值	说明
-p PROJECT	$PROJECT	当前 gcloud config 中的 project（即 gcloud config list --format 'value(core.project)'）	GCP 项目名；若最终为空会直接报错退出
-z ZONE	$ZONE	us-central1-f	集群所在可用区
-c CLUSTER_NAME	$CLUSTER_NAME	istio-e2e	集群名称
-v CLUSTER_VERSION	$CLUSTER_VERSION	不指定则用 GCP 默认版本	GKE 集群版本
-m MACHINE_TYPE	$MACHINE_TYPE	n1-standard-4	节点机器类型
-n NUM_NODES	$NUM_NODES	3	节点数量
-h	—	—	打印 usage 帮助

脚本在解析参数后会执行如下操作序列（对应源码第 90-126 行）：

1. 开启 errexit/nounset/pipefail/xtrace，任何一步失败立即终止并输出日志；
2. 调用 gcloud container clusters create，显式传入 --project、--cluster-version、--zone、--machine-type、--num-nodes，并固定追加 --no-enable-legacy-authorization；
3. 将 container/use_client_certificate 设置为 False；
4. 执行 gcloud container clusters get-credentials 下载集群凭据；
5. 执行 kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user="$(gcloud config get-value core/account)" 为当前账号授予集群管理员权限。

其中第 3 步是一个针对已知坑的 hack：源码注释（第 116-119 行）指出，某些情况下创建 clusterrolebinding 会报错 clusterrolebindings.rbac.authorization.k8s.io is forbidden: User "client" cannot create ...，因此先强制改用客户端证书之外的身份校验方式。脚本还通过 trap cleanup EXIT（第 95-105 行）保证退出时恢复用户原先的 container/use_client_certificate 配置——如果用户此前未设置过，则执行 gcloud config unset；如果设置过，则还原旧值。

3.2 方式二：手动创建集群

不依赖脚本时，也可以使用 gcloud 原生命令手动创建：

gcloud container clusters \
  create ${CLUSTER_NAME} \
  --zone ${ZONE} \
  --project ${PROJECT_ID} \
  --cluster-version ${CLUSTER_VERSION} \
  --machine-type ${MACHINE_TYPE} \
  --num-nodes ${NUM_NODES} \
  --enable-kubernetes-alpha \
  --no-enable-legacy-authorization

各参数的建议取值（来自原文档指引）：

• CLUSTER_NAME：任取一个合适的名称，例如 istio-e2e；
• ZONE：推荐 us-central1-f；
• PROJECT_ID：承载集群的 GCP 项目 ID；
• CLUSTER_VERSION：需要支持较新版本特性的 GKE 版本（原文档示例以 1.7.3 起为参考基线；实际应以你所在区域当前可用的 GKE 版本为准）；
• MACHINE_TYPE：推荐 n1-standard-4；
• NUM_NODES：推荐 3；
• --enable-kubernetes-alpha：启用 GKE Alpha 集群特性；
• --no-enable-legacy-authorization：可选，当你希望测试 RBAC 相关能力时必须开启（禁用旧版基于 ABAC 的授权）。

需要留意的是，手动命令与 create_cluster_gke.sh 的参数略有出入（如脚本默认不带 --enable-kubernetes-alpha），这正说明：脚本是“为 E2E 测试优化过的默认集合”，手动方式则把更多自由度交给用户按需调整。

3.3 获取集群凭据

无论哪种方式创建，都需要先拿到集群的 kubeconfig 凭据：

gcloud container clusters get-credentials ${CLUSTER_NAME} \
   --zone ${ZONE} --project ${PROJECT_ID}

3.4 授予管理员权限

Istio E2E 测试需要在集群范围内部署、清理大量资源（命名空间、CRD、ClusterRole、Webhook 等），因此当前用户必须具备 cluster-admin 权限。手动执行如下命令完成绑定：

kubectl create clusterrolebinding myname-cluster-admin-binding \
   --clusterrole=cluster-admin \
   --user=$(gcloud config get-value core/account)

注意：绑定名称（上例为 myname-cluster-admin-binding）可自定；core/account 取的是当前 gcloud 登录账号。集成测试会在你的集群上部署、修改并删除大量既有/新增资源，建议仅在专用的测试集群上执行。

四、Step 3：设置 Istio 构建与镜像环境变量

集群就绪后，还需通过环境变量告知测试框架“要部署哪个 Istio 镜像”。这里有两条路线，取决于你要验证自己修改过的代码还是官方已发布的构建。

4.1 选项一：自建镜像（开发场景）

将镜像仓库与版本指向你自己的 Docker Registry：

export HUB=myname
export TAG=latest
export GS_BUCKET=mybucket

• HUB：镜像的 registry/组织前缀；
• TAG：镜像标签；
• GS_BUCKET：可选，指定一个不同于默认值的 Google Storage Bucket（需要写权限），用于定制 Makefile 相关规则。

随后在本地构建并推送 Docker 镜像：

# 在本地 docker 上构建镜像
make docker

# 推送到 docker registry
make push

在 macOS 上，由于本机架构与目标 Linux 环境不一致，需要在构建前显式设置目标操作系统：

GOOS=linux make docker push

4.2 选项二：使用预构建的 Istio 镜像（快速验证场景）

如果你不修改源码，可以直接使用官方发布渠道的预构建镜像，此时 TAG 需要填写具体的镜像 SHA（可从已发布的构建版本列表中挑选），或使用 latest 指向最新的开发镜像：

export HUB="registry.istio.io/testing"
export TAG="latest"

这样即可跳过本地编译与推送，直接以官方测试镜像跑 E2E。

五、源码视角：HUB / TAG 如何在构建链路中生效

为了准确理解上面两组环境变量的含义，可以回到仓库构建系统核实它们的消费点。

5.1 默认值与非空校验

在 Makefile.core.mk 中可以找到：

• HUB 默认值为 istio（第 124 行 HUB ?=istio），并校验不能为空（第 125-127 行）；
• TAG 默认取当前 git 提交的 SHA，即 TAG ?= $(shell git rev-parse --verify HEAD)（第 133 行），同样不能为空。

也就是说，即使你不显式设置环境变量，构建系统也会用 istio 与当前 commit 作为兜底镜像标识。设置 HUB/TAG 正是为了把镜像导向你自己的 registry（myname）或官方 testing registry（registry.istio.io/testing）。

5.2 make docker 与 make push 的真实调用链

• Makefile.core.mk 中 push: docker.push，其注释为：Build and push docker images to registry defined by $HUB and $TAG；
• 进一步的 docker 目标定义在 tools/istio-docker.mk：docker.push 实际执行 ./tools/docker --push，docker.% 这类目标（例如 docker.pilot）则只构建单个镜像；
• 由此可以推断：make docker 走的是 tools/docker 二进制对各 Dockerfile 的编排构建，make push 是在构建完成后把所有镜像推送到 $HUB 对应的仓库。

六、环境变量就绪后：如何真正跑起 E2E 测试

HUB/TAG 设置完成只是“镜像来源”就绪。参照 tests/integration/README.md 与 tests/integration/tests.mk，在 GKE 集群上执行测试的典型方式如下。

6.1 直接使用 go test

集成测试通过 integ 构建标签隔离（未加该标签则不会执行任何用例），指定 kubeconfig 运行：

go test ./... -p 1 -tags=integ --istio.test.kube.config ~/.kube/config

• -p 1：README 明确要求，在 tests/integration/ 目录下直接运行时必须使用，避免多个并行 suite 同时部署 Istio（Istio 部署在集群中是单例，并行部署会互相污染甚至失败）；
• 未指定 --istio.test.kube.config 时默认使用 ~/.kube/config；
• 在 Kubernetes 环境下运行时，HUB 与 TAG 环境变量必须设置，测试框架依赖它们决定拉取哪个镜像。

6.2 通过 Makefile 集成测试目标

仓库通过 tests/integration/tests.mk 生成了 test.integration.*.kube 系列目标，其关键行为（对应源码第 27-33 行）是：当设置了 HUB、TAG 时，自动把它们转换成框架 flag：

ifneq ($(HUB),)
	_INTEGRATION_TEST_FLAGS += --istio.test.hub=$(HUB)
endif
ifneq ($(TAG),)
	_INTEGRATION_TEST_FLAGS += --istio.test.tag=$(TAG)
endif

即 HUB/TAG 环境变量最终映射为框架侧的 --istio.test.hub / --istio.test.tag，二者语义一致。此外：

• CI 环境（CI 非空）会追加 --istio.test.ci 与 --istio.test.pullpolicy=IfNotPresent；
• 测试命令统一为 go test -p 1 -tags=integ -vet=off -timeout 30m ...，并将结果通过 go-junit-report 输出为 JUnit 报告；
• check-go-tag 目标会强制校验 tests/integration/ 下所有测试文件都带有 //go:build integ 标签，防止测试被无意跳过。

例如运行所有 presubmit 级别的 Kubernetes 集成测试：

make test.integration.kube.presubmit

或只运行某个组件（如 pilot）：

make test.integration.pilot.kube

七、排障与注意事项速查

结合原文档与相关脚本实现，实践中最容易踩坑的点如下：

1. 服务账号权限缺失导致创建失败：务必在创建前确认默认计算服务账号具备 roles/container.admin 等角色（见第二节）；
2. clusterrolebinding 被 Forbidden：优先使用仓库自带的 create_cluster_gke.sh，它内置了 container/use_client_certificate False 的 workaround，并在退出时自动恢复原配置；
3. 集群版本与特性：文档示例中 CLUSTER_VERSION 以 1.7.3 起作为参考基线，并配合 --no-enable-legacy-authorization 使用以支持 RBAC 类测试；实际选择应以你所在区域当前可用的 GKE 版本为准；
4. 务必在专用测试集群上执行：集成测试会改动甚至删除集群中的既有资源，切勿指向生产集群；
5. 镜像来源二选一：修改了源码就走「自建镜像 + make docker push」，只做验证就走「registry.istio.io/testing + latest」；macOS 上构建务必加上 GOOS=linux。

按照「GCP 准备 → 建集群授权 → 配镜像变量」三步完成之后，你的 GKE 集群就具备了运行 Istio E2E 集成测试的全部前置条件，可以继续按 tests/integration/README.md 中的指南编写与执行具体测试用例了。

</｜｜DSML｜｜tool_calls>