使用 CDK for Terraform (Go) 在 Google Cloud Run 上部署容器应用:完整实践指南

原创2026-10-14 13:17:581,371 阅读
文章标签:IaC云原生开发工具

使用 CDK for Terraform (Go) 在 Google Cloud Run 上部署容器应用:完整实践指南

导读

本文基于 terraform-cdk 仓库中的官方 Go 示例 examples/go/google-cloudrun,完整演示如何使用 CDK for Terraform(CDKTF)以 Go 语言编写基础设施即代码:从 cdktf get 生成 Google Provider 的 Go 绑定,到在 main.go 中定义 Cloud Run 服务、IAM 策略与输出,再到 cdktf synth / diff / deploy / destroy 的完整部署生命周期。读完本文,你将掌握在 Go 项目中用 CDKTF 声明式管理 Google Cloud Run 服务、并实现匿名公网访问的端到端实战能力。

示例背景:TypeScript 示例的 Go 移植

该示例是一个由 TypeScript 版本移植而来的 Go 实现。原 TypeScript 示例位于 examples/typescript/google-cloudrun/main.ts,其业务逻辑参考了 HashiCorp Learn 平台上“使用 Terraform 构建 GCP 基础设施”的经典教程:创建一个公开可访问的 Cloud Run 服务,运行 gcr.io/cloudrun/hello 示例镜像。

Go 版本与 TypeScript 版本在业务上完全等价,都包含四类核心资源:

资源 作用
GoogleProvider 配置 GCP 区域、项目、凭据,作为后续资源的地基
CloudRunService 创建 Cloud Run 服务,指定镜像与部署位置
DataGoogleIamPolicy + CloudRunServiceIamPolicy 声明 IAM 策略,将 roles/run.invoker 角色授予 allUsers,实现匿名访问
TerraformOutput 输出部署完成后的服务 URL

从实现细节看,Go 移植版并非简单逐行翻译,而是针对 Go 语言的类型系统做了适配:由于 Cloud Run 的 containers 参数在 Provider 生成结果中是 interface{} 类型,Go 示例自行定义了 Container 结构体(见 main.go),这正是两种语言在强类型与弱类型之间的典型差异体现。

环境准备与前置条件

项目依赖

示例的 Go 版本要求与依赖关系记录在 go.mod 中:

  • Go 1.18 及以上;
  • github.com/aws/constructs-go/constructs/v10(构造抽象基座);
  • github.com/aws/jsii-runtime-go(CDKTF 底层依赖 jsii 的 Go 运行时);
  • github.com/hashicorp/terraform-cdk-go/cdktf(CDKTF 核心库,示例锁定的版本为 v0.12.0);
  • github.com/hashicorp/cdktf-provider-google-go/google(Google Provider 的预生成 Go 绑定)。

值得注意的一点:go.mod 中通过 replace 指令将 terraform-cdk-go/cdktf 指向仓库内的 packages/cdktf/dist/go/cdktf,这意味着在仓库内运行该示例时,会直接使用当前源码构建的 CDKTF 核心库,便于与主分支代码保持同步调试。

安装依赖的方式与普通 Go 项目一致:

go get ./...

需要准备的凭据

根据 README.md,运行示例前你必须准备两样东西:

  1. GCP 项目 ID:在 main.go 中通过 projectID := "your-google-project-id" 设置(例如 plasma-goblin-123567 这样的真实项目 ID);
  2. GCP 服务账号凭据文件:创建一个名为 cdktf-example.json 的文件,内容为你的 GCP credentials(服务账号 JSON 密钥)。

程序启动时通过 os.ReadFile("cdktf-example.json") 读取该文件(见 main.go),读取失败会直接 panic,提示 failed to load credentials。因此该文件必须放在示例项目根目录下才能正常运行。

生成 Provider 绑定:cdktf get

cdktf get

这一命令是 Go 版 CDKTF 工作流的关键一步。它会根据 cdktf.json 中的配置,从 Terraform Registry 下载 Provider/Module 的 schema,并生成对应语言的绑定代码。

在 cdktf.json 中可以观察到核心配置项:

{
  "language": "go",
  "app": "go run main.go",
  "codeMakerOutput": "generated",
  "sendCrashReports": "false",
  "terraformProviders": [],
  "terraformModules": [],
  "context": {}
}
  • language: "go":声明代码生成的目标语言为 Go;
  • app: "go run main.go":synth 时实际执行的入口命令;
  • codeMakerOutput: "generated":绑定代码的输出目录。

从源码层面看,codeMakerOutput 由 CLI 核心的配置解析类 CdktfConfig 提供读取能力,而真正执行下载与生成逻辑的是 get 命令(见 get.ts),其内部调用 ConstructsMaker 完成 schema 下载、filterAlreadyGenerated 增量过滤与绑定生成。虽然示例中的 terraformProviders 为空数组,但这不影响 cdktf get 正常执行——示例已预先通过 go.mod 引入预构建的 cdktf-provider-google-go 绑定,这与使用 terraformProviders 配置走本地生成路径是 CDKTF 支持的两条并行走法。

提示:该示例的 package.json 中 "build": "cdktf get",说明 cdktf get 也被视为项目构建步骤的一部分(见 package.json)。

编写 Go 栈:main.go 结构拆解

cdktf get 完成后,就可以编辑 main.go 了。整个文件可拆解为四个层次:

1. 定义强类型辅助结构体

由于生成的 Google Provider Go 绑定中,CloudRunService 的 Template.Spec.Containers 参数类型为 interface{},示例按 Terraform 官方文档(Cloud Run Service 资源的 containers 属性)自定义了两个辅助结构体:

type Container struct {
	Image string `json:"image"`
}

type Binding struct {
	Role    string   `json:"role"`
	Members []string `json:"members"`
}

Container 用于描述容器镜像,Binding 用于描述 IAM 策略绑定关系。这种做法在 Go + CDKTF 组合中非常典型:面对生成绑定中的弱类型字段,用带 json tag 的结构体将 JSON 序列化交给 Go 标准库处理。

2. 创建 Stack 并配置 GoogleProvider

stack := cdktf.NewTerraformStack(scope, &id)

region := "europe-west1"
projectID := "your-google-project-id"
imageName := "gcr.io/cloudrun/hello"

credentials, err := os.ReadFile("cdktf-example.json")
if err != nil {
	panic("failed to load credentials: " + err.Error())
}

google.NewGoogleProvider(stack, jsii.String("GoogleAuth"), &google.GoogleProviderConfig{
	Region:      &region,
	Zone:        jsii.String(region + "-c"),
	Project:     &projectID,
	Credentials: jsii.String(string(credentials)),
})

关键点说明:

  • region 默认取 europe-west1,zone 由 region 拼接 -c 得到;
  • projectID 必须替换为你的真实 GCP 项目 ID;
  • 凭据以字符串形式内联传给 Credentials 字段,避免额外的环境变量配置;
  • 所有字符串参数需通过 jsii.String(...) 包装,这是 CDKTF Go 绑定的强制约定。

3. 定义 Cloud Run 服务与 IAM 策略

crs := google.NewCloudRunService(stack, jsii.String("cloudRun"), &google.CloudRunServiceConfig{
	Location: &region,
	Name:     jsii.String("gcpcdktfcloudrunsvc2020"),
	Template: &google.CloudRunServiceTemplate{
		Spec: &google.CloudRunServiceTemplateSpec{
			Containers: []Container{
				{
					Image: imageName,
				},
			},
		},
	},
})

policyData := google.NewDataGoogleIamPolicy(stack, jsii.String("datanoauth"), &google.DataGoogleIamPolicyConfig{
	Binding: []Binding{
		{
			Role:    "roles/run.invoker",
			Members: []string{"allUsers"},
		},
	},
})

google.NewCloudRunServiceIamPolicy(stack, jsii.String("runsvciampolicy"), &google.CloudRunServiceIamPolicyConfig{
	Location:   &region,
	Project:    crs.Project(),
	Service:    crs.Name(),
	PolicyData: policyData.PolicyData(),
})

这里的核心技巧在于资源间的引用:

  • CloudRunService 的 Name 固定为 gcpcdktfcloudrunsvc2020,符合 Cloud Run 服务命名规则;
  • CloudRunServiceIamPolicy 的 Project 与 Service 分别取自 crs.Project() 与 crs.Name(),实现了 CDKTF 的跨资源引用——合成阶段会自动把依赖关系写入 Terraform JSON,保证 IAM 策略在服务创建后才生效;
  • DataGoogleIamPolicy 先声明策略数据,再由 CloudRunServiceIamPolicy.PolicyData 消费,roles/run.invoker 配合 allUsers 意味着任何匿名用户都可以调用该服务,请在生产环境谨慎评估这一权限设置。

4. 输出服务 URL

cdktf.NewTerraformOutput(stack, jsii.String("cdktfcloudrunUrl"), &cdktf.TerraformOutputConfig{
	Value: *crs.Fqn(),
})

crs.Fqn() 返回该资源在 Terraform 中的完全限定名(Fully Qualified Name),它会被解析为 google_cloud_run_service.cloudRun.status<a href="https://link.gitcode.com/i/9ef34af09bf836be90d64f7d3064dba8" target="_blank">0].url 一类的属性引用,最终以 Terraform Output 的形式展示部署后的服务访问地址。对比 TypeScript 原版 [main.ts 中的 "${" + cloudrunsvcapp.fqn + ".status[0].url}" 写法,Go 版直接以资源 Fqn 作为输出值,依赖解析由 CDKTF 在合成期完成,写法更简洁。

入口函数

func main() {
	app := cdktf.NewApp(nil)
	NewMyStack(app, "learn-cdktf-docker")
	app.Synth()
}

NewApp 创建 CDKTF 应用,NewMyStack 注册栈(栈 ID 为 learn-cdktf-docker),app.Synth() 触发合成。这与 cdktf.json 中 "app": "go run main.go" 的入口配置一一对应——cdktf synth 正是通过执行该命令来驱动合成过程的。

部署生命周期:synth / diff / deploy / destroy

合成配置:cdktf synth

cdktf synth

该命令会在项目根目录生成名为 cdktf.out 的文件夹,里面包含合成的全部 Terraform JSON 配置。整个过程分两步:先运行 app 配置中声明的 go run main.go 执行合成,再由 CLI 的合成模块(见 synth-stack.ts)收集各栈产物并写出到 cdktf.out。

在仓库的 Go 集成测试中,synth-app 用例(见 test/go/synth-app)会完整走一遍“执行 Go 程序 + 校验合成 JSON”的流程,可作为该命令行为是否符合预期的验证依据。

预览变更:cdktf diff

cdktf diff

diff 会调用底层 Terraform 执行 plan,将当前代码合成结果与远端实际基础设施(或本地状态)做对比,展示将要做出的增删改。上线前执行该命令是确认变更范围的标准动作。

部署:cdktf deploy

cdktf deploy

deploy 实际执行 Terraform apply。本示例会依次创建:

  1. Google Provider 对应的授权上下文;
  2. gcr.io/cloudrun/hello 镜像的 Cloud Run 服务(位置 europe-west1,服务名 gcpcdktfcloudrunsvc2020);
  3. 允许匿名调用的 IAM 策略绑定;
  4. 输出服务 URL。

部署完成后,控制台会打印 cdktfcloudrunUrl 的值,浏览器打开该地址即可访问 Cloud Run 提供的 “Hello World” 页面。

清理资源:cdktf destroy

cdktf destroy

实验结束后执行 destroy 销毁全部由该栈管理的基础设施,避免持续产生 GCP 费用。这是 CDKTF 提供的一键回收能力,与 Terraform destroy 语义一致。

测试与验证

示例目录附带 main_test.go,其中展示了 CDKTF Go 测试的三种典型断言模式(当前以注释形式保留,可取消注释后配合 cdktf.Testing 使用):

// 断言合成结果中包含某类资源
cdktf.Testing_ToHaveResource(synth, docker.Container_TfResourceType())

// 断言某资源具备指定属性
cdktf.Testing_ToHaveResourceWithProperties(synth, docker.Image_TfResourceType(), &properties)

// 断言合成结果是合法 Terraform 配置
cdktf.Testing_ToBeValidTerraform(ccdktf.Testing_FullSynth(stack))

更完整的 Go 测试集成可参考仓库的 test/go/testing-matchers 测试目录。将这类单元测试纳入 CI,可以在不实际调用云厂商的情况下,提前捕获资源配置错误,是 CDKTF 项目推荐的质量保障手段。

常见问题与注意事项

问题 原因与处理
failed to load credentials: ... cdktf-example.json 不存在或不在项目根目录,请确认凭据文件已创建且路径正确
忘记先执行 cdktf get 首次运行前必须先生成绑定代码(或确保预构建绑定已通过 go.mod 引入),否则 google 包无法解析
projectID 未替换 使用占位符 your-google-project-id 部署会失败,务必替换为真实 GCP 项目 ID
匿名访问风险 示例将 roles/run.invoker 授予 allUsers,生产环境建议改为受限主体或启用 Cloud Run 的 IAM 鉴权
区域选择 region 默认 europe-west1,可按需改为其他 GCP 区域(如 asia-east1),zone 会自动拼接 -c 后缀

小结

本示例完整覆盖了 CDKTF Go 工作流的五个核心环节:

  1. go get ./... 安装依赖;
  2. cdktf get 生成/引入 Provider 绑定;
  3. 在 main.go 中用 Go 结构体与构造类声明 Google Provider、Cloud Run 服务、IAM 策略与输出;
  4. cdktf synth 合成 Terraform JSON 配置;
  5. cdktf diff / deploy / destroy 完成变更预览、部署与清理。

通过 examples/go/google-cloudrun/main.go 这个可运行样例,你可以快速掌握在 Go 生态中使用 CDKTF 管理 GCP 资源的全部要点,并将其推广到更复杂的多资源、多栈基础设施场景中。

登录后查看全文
terraform-cdk