使用 CDK for Terraform (Go) 在 Google Cloud Run 上部署容器应用:完整实践指南
使用 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,运行示例前你必须准备两样东西:
- GCP 项目 ID:在
main.go中通过projectID := "your-google-project-id"设置(例如plasma-goblin-123567这样的真实项目 ID); - GCP 服务账号凭据文件:创建一个名为
cdktf-example.json的文件,内容为你的 GCPcredentials(服务账号 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: ®ion,
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: ®ion,
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: ®ion,
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。本示例会依次创建:
- Google Provider 对应的授权上下文;
gcr.io/cloudrun/hello镜像的 Cloud Run 服务(位置europe-west1,服务名gcpcdktfcloudrunsvc2020);- 允许匿名调用的 IAM 策略绑定;
- 输出服务 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 工作流的五个核心环节:
go get ./...安装依赖;cdktf get生成/引入 Provider 绑定;- 在
main.go中用 Go 结构体与构造类声明 Google Provider、Cloud Run 服务、IAM 策略与输出; cdktf synth合成 Terraform JSON 配置;cdktf diff/deploy/destroy完成变更预览、部署与清理。
通过 examples/go/google-cloudrun/main.go 这个可运行样例,你可以快速掌握在 Go 生态中使用 CDKTF 管理 GCP 资源的全部要点,并将其推广到更复杂的多资源、多栈基础设施场景中。