GCP 云日志导出到 Pub/Sub 的 Terraform 配置指南——为 Loki 生态Promtail准备云上日志源【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki导读本指南以 Loki 仓库 tools/gcplog 目录下的 Terraform 工程为核心讲解如何通过基础设施即代码IaC方式将 Google CloudGCP中的云服务日志App Engine、HTTP 负载均衡器等按需过滤后持续导出到 Pub/Sub 主题与订阅中从而让日志采集端如 Promtail 的 GCP Pub/Sub target能够订阅消费这些日志并最终写入 Loki。读完本文你将掌握 GCP 日志路由Log Router/Sink的配置原理、日志过滤器Log Filter的书写方式、Terraform 变量化交付的完整流程以及 IAM 权限与发布者身份的自动绑定机制。一、方案概述为什么需要 Terraform 为 GCP 日志开闸放水GCP 自身的日志默认停留在 Cloud Logging 内部。要让日志离开 Google Cloud 进入 Loki 生态标准做法是借助Log Router日志路由中的 Sink接收器把满足条件的日志转发到下游目标——Pub/Sub 是其中最常用的一种。之后Loki 侧的采集端如 promtail 的 GCP 日志采集配置通过订阅 Pub/Sub即可将云上日志拉取回来并写入 Loki。tools/gcplog正是 Loki 官方仓库中为此准备的GCP 侧一体化配置模块它用一份 main.tf 同时完成四件事创建 Pub/SubTopic主题作为日志的汇聚出口创建 LoggingSink接收器把符合过滤条件的日志写入该 Topic创建 Pub/SubSubscription订阅供消费端promtail拉取通过 IAM Binding把 Sink 的 writer identity 授权为 Topic 的发布者publisher打通日志服务 → 主题的写权限闭环。整个工程只有 README.md 与 main.tf 两个文件逻辑清晰、开箱即用。二、日志过滤器Log Filter决定导哪些日志文档明确指出要选择从 Google Cloud 导出哪些日志我们使用日志过滤器log filters。日志过滤器本质上是普通的 GCP Logging 查询语句只是其目标是从一组特定的 GCP 云资源中导出日志。2.1 过滤器基本语法过滤器遵循 GCP Logging 查询语法核心字段包括resource.type资源类型、severity日志级别、httpRequest.statusHTTP 状态码等多个条件用AND/OR组合支持换行书写。2.2 官方示例一导出 App Engine 的错误日志将 App Engine 上所有severity ERROR的日志导出resource.typegae_app AND severityERROR2.3 官方示例二导出 HTTP 负载均衡器的 5xx 日志将 HTTP 负载均衡器http_load_balancer上所有 HTTP 状态码不低于 500 的请求日志导出resource.typehttp_load_balancer AND httpRequest.status5002.4 过滤器的实际落点这两个过滤器正是 main.tf 中inclusion_filter变量的用途Sink 资源的filter字段直接引用该变量见resource google_logging_project_sink main中的filter var.inclusion_filter。也就是说你在 Terraform 变量里写的任何合法 GCP 日志查询都会被原样应用到 Sink 上决定最终进入 Pub/Sub 的日志范围。GCP 官方提供了完整的查询库文档可按资源类型、日志级别等检索更多过滤器写法。三、前置条件Prerequisite在开始之前需要确认两件事前置项要求Terraform 版本 0.14.5GCP 服务账号凭证需要具有以下角色的凭据文件JSON•roles/pubsub.editor— 管理 Pub/Sub 主题与订阅•roles/logging.configWriter— 创建和管理日志 Sink说明roles/pubsub.editor覆盖 Topic / Subscription 的创建与授权roles/logging.configWriter用于配置 Log Router 中的 Sink。凭证文件路径通过credentials_file变量传入main.tf 中 provider 的credentials file(var.credentials_file)会读取该文件内容完成认证。四、使用流程Usage该 Terraform 工程遵循标准的 Terraform 工作流三步即可完成资源创建4.1 初始化terraform initinit会按 main.tf 顶部的required_providers声明自动下载 Google Providerhashicorp/google版本7.46.1source 为hashicorp/google。4.2 预览变更terraform planplan会展示将要创建的四个资源及其属性便于在真正执行前核对过滤条件与命名是否正确。4.3 应用配置terraform applyapply执行实际资源创建。首次执行时Terraform 会提示输入工程中定义的变量未提供默认值的项。4.4 变量清单与说明文档明确列出 Terraform 会提示的 7 个变量与 main.tf 末尾的variable声明一一对应#变量名含义默认值1credentials_file具备前述权限的 ServiceAccount 凭据文件路径无必填2zoneGCP 可用区如us-central1-b无必填3regionGCP 区域如us-central1无必填4projectGCP 项目 ID无必填5name用于创建 Pub/Sub Topic、Log RouterSink和 Pub/Sub Subscription 的名称cloud-logs6inclusion_filter包含过滤器决定导出哪些云资源的日志即上文 2.2/2.3 的过滤器空字符串默认不导出任何日志7exclusions排除列表在包含过滤的基础上忽略指定日志元素含name与filter两个字段[]空列表值得注意的两点设计inclusion_filter默认值为空字符串注释明确写着 default no logs should be ingested即默认不导出任何日志。这是刻意的安全设计——防止误配导致把全量日志灌入 Pub/Sub 产生巨额费用必须显式指定过滤条件才会真正导出。exclusions是一个对象列表其类型定义如下由dynamic exclusions块在 Sink 资源上逐条展开为 GCP 的排除规则variable exclusions { default [] description Logs exclusion filter that tells what kind of logs should be ignored type list(object({ name string filter string })) }4.5 通过 CLI 传参的实战示例变量有多种传入方式-var命令行参数、terraform.tfvars文件、环境变量等。文档给出了 CLI 传参的完整示例terraform apply \ -varcredentials_file./permissions.json \ -varzoneus-central1-b \ -varregionus-central1 \ -varprojectgrafanalabs-dev \ -varlognamecloud-logs注意示例命令中出现的-varlogname...是变量名的不严谨写法工程实际定义的变量名为name见 main.tf 中variable name应写为-varnamecloud-logs。更多变量赋值方式如 tfvars 文件、环境变量、默认值覆盖等可参考 Terraform 官方变量赋值文档。五、源码级拆解main.tf 的资源编排逻辑Terraform 工程本体 是理解这套方案的最佳材料其资源编排遵循主题 → 接收器 → 订阅 → 授权的依赖链5.1 Provider 配置terraform { required_providers { google { source hashicorp/google version 7.46.1 } } } provider google { credentials file(var.credentials_file) project var.project zone var.zone region var.region }5.2 第一步创建 Pub/Sub Topicresource google_pubsub_topic cloud-logs { name var.name }Topic 是日志出口所有被 Sink 选中的日志都会发布到这里。5.3 第二步创建 Logging Sink日志接收器resource google_logging_project_sink main { name var.name destination pubsub.googleapis.com/projects/${var.project}/topics/${var.name} filter var.inclusion_filter dynamic exclusions { for_each var.exclusions content { name exclusions.value.name filter exclusions.value.filter } } unique_writer_identity true }关键点解读destination指向第一步创建的 Topic使用 GCP 标准的pubsub.googleapis.com/projects/{project}/topics/{topic}格式filter直接接收inclusion_filter变量即文档 2.2/2.3 节演示的日志过滤器exclusions通过dynamic块动态展开支持多条排除规则unique_writer_identity true是打通权限的关键开关它让 Sink 获得一个独立的 writer identity便于后续精确授权见 5.5。5.4 第三步创建 Pub/Sub Subscriptionresource google_pubsub_subscription main { name var.name topic google_pubsub_topic.cloud-logs.name }Subscription 绑定到 Topic 上采集端如 promtail 的 GCP 目标通过订阅 ID 拉取日志。5.5 第四步IAM 授权——打通日志 → 主题写权限resource google_pubsub_topic_iam_binding log-writer { topic google_pubsub_topic.cloud-logs.name role roles/pubsub.publisher members [ google_logging_project_sink.main.writer_identity, ] }这一步将 Sink 的writer_identity绑定到 Topic 的roles/pubsub.publisher角色上使日志路由服务有权限把日志发布到该 Topic。如果缺少这一步即使 Sink 创建成功日志也不会被写入 Pub/Sub——这是实践中最容易遗漏的坑而本工程已内置处理。5.6 资源依赖关系小结从源码结构可以推断整个工程形成了清晰的依赖链google_pubsub_topic cloud-logs主题 │ ├── google_logging_project_sink main接收器destination 引用主题 │ └── 依赖其 writer_identity ├── google_pubsub_subscription main订阅引用主题名 └── google_pubsub_topic_iam_binding log-writer授权 Sink 可发布到主题Terraform 会自动根据资源间的引用关系推导执行顺序确保 Topic 先于 Sink / Subscription / IAM Binding 创建。六、对接 Loki 生态配置完成后的下一步Terraform 应用成功后你将得到一个名为name的 Pub/Sub Topic一个名为name的 Pub/Sub Subscription一个名为name的 Logging Sink已按inclusion_filter/exclusions决定日志流向。接下来在日志消费端Promtail配置 GCP Pub/Sub 目标填入订阅 ID、项目 ID 与订阅所需的凭证即可开始把 GCP 云日志拉入 Loki。采集端的具体配置方式请参考 Loki 官方文档中 Promtail 的 GCP 采集章节本仓库的 tools/gcplog 只负责 GCP 侧的日志导出准备工作。七、实践注意事项务必显式指定inclusion_filter默认值为空意味着不导出任何日志。若忘记配置Sink 虽创建成功但不会转发任何日志排查时容易误判为采集端问题。确认凭据角色齐全缺少roles/logging.configWriter会导致 Sink 创建失败缺少roles/pubsub.editor会导致主题/订阅创建失败。unique_writer_identity与 IAM 绑定配套使用不要手工改 Sink 的 writer identity 模式否则 IAM 绑定可能失效。合理使用exclusions当包含过滤条件过宽例如severityWARNING时用exclusions精确排除高噪声资源如健康检查日志可显著降低日志量与成本。凭据文件不要提交到版本库credentials_file指向的 JSON 包含高权限密钥建议通过.gitignore排除或使用 Terraform 的变量文件机制注入。结语tools/gcplog用一份不到 80 行的 Terraform 配置完整覆盖了GCP 日志导出到 Pub/Sub所需的全部资源与权限闭环日志过滤器控制范围、Sink 负责转发、Topic/Subscription 提供传输通道、IAM 绑定打通写权限。作为 Loki 生态在 Google Cloud 上的前置引流闸门它与采集端的配合让云上日志 → Loki的全链路变得可声明、可审计、可复现。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GCP 云日志导出到 Pub/Sub 的 Terraform 配置指南——为 Loki 生态（Promtail）准备云上日志源
GCP 云日志导出到 Pub/Sub 的 Terraform 配置指南——为 Loki 生态Promtail准备云上日志源【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki导读本指南以 Loki 仓库 tools/gcplog 目录下的 Terraform 工程为核心讲解如何通过基础设施即代码IaC方式将 Google CloudGCP中的云服务日志App Engine、HTTP 负载均衡器等按需过滤后持续导出到 Pub/Sub 主题与订阅中从而让日志采集端如 Promtail 的 GCP Pub/Sub target能够订阅消费这些日志并最终写入 Loki。读完本文你将掌握 GCP 日志路由Log Router/Sink的配置原理、日志过滤器Log Filter的书写方式、Terraform 变量化交付的完整流程以及 IAM 权限与发布者身份的自动绑定机制。一、方案概述为什么需要 Terraform 为 GCP 日志开闸放水GCP 自身的日志默认停留在 Cloud Logging 内部。要让日志离开 Google Cloud 进入 Loki 生态标准做法是借助Log Router日志路由中的 Sink接收器把满足条件的日志转发到下游目标——Pub/Sub 是其中最常用的一种。之后Loki 侧的采集端如 promtail 的 GCP 日志采集配置通过订阅 Pub/Sub即可将云上日志拉取回来并写入 Loki。tools/gcplog正是 Loki 官方仓库中为此准备的GCP 侧一体化配置模块它用一份 main.tf 同时完成四件事创建 Pub/SubTopic主题作为日志的汇聚出口创建 LoggingSink接收器把符合过滤条件的日志写入该 Topic创建 Pub/SubSubscription订阅供消费端promtail拉取通过 IAM Binding把 Sink 的 writer identity 授权为 Topic 的发布者publisher打通日志服务 → 主题的写权限闭环。整个工程只有 README.md 与 main.tf 两个文件逻辑清晰、开箱即用。二、日志过滤器Log Filter决定导哪些日志文档明确指出要选择从 Google Cloud 导出哪些日志我们使用日志过滤器log filters。日志过滤器本质上是普通的 GCP Logging 查询语句只是其目标是从一组特定的 GCP 云资源中导出日志。2.1 过滤器基本语法过滤器遵循 GCP Logging 查询语法核心字段包括resource.type资源类型、severity日志级别、httpRequest.statusHTTP 状态码等多个条件用AND/OR组合支持换行书写。2.2 官方示例一导出 App Engine 的错误日志将 App Engine 上所有severity ERROR的日志导出resource.typegae_app AND severityERROR2.3 官方示例二导出 HTTP 负载均衡器的 5xx 日志将 HTTP 负载均衡器http_load_balancer上所有 HTTP 状态码不低于 500 的请求日志导出resource.typehttp_load_balancer AND httpRequest.status5002.4 过滤器的实际落点这两个过滤器正是 main.tf 中inclusion_filter变量的用途Sink 资源的filter字段直接引用该变量见resource google_logging_project_sink main中的filter var.inclusion_filter。也就是说你在 Terraform 变量里写的任何合法 GCP 日志查询都会被原样应用到 Sink 上决定最终进入 Pub/Sub 的日志范围。GCP 官方提供了完整的查询库文档可按资源类型、日志级别等检索更多过滤器写法。三、前置条件Prerequisite在开始之前需要确认两件事前置项要求Terraform 版本 0.14.5GCP 服务账号凭证需要具有以下角色的凭据文件JSON•roles/pubsub.editor— 管理 Pub/Sub 主题与订阅•roles/logging.configWriter— 创建和管理日志 Sink说明roles/pubsub.editor覆盖 Topic / Subscription 的创建与授权roles/logging.configWriter用于配置 Log Router 中的 Sink。凭证文件路径通过credentials_file变量传入main.tf 中 provider 的credentials file(var.credentials_file)会读取该文件内容完成认证。四、使用流程Usage该 Terraform 工程遵循标准的 Terraform 工作流三步即可完成资源创建4.1 初始化terraform initinit会按 main.tf 顶部的required_providers声明自动下载 Google Providerhashicorp/google版本7.46.1source 为hashicorp/google。4.2 预览变更terraform planplan会展示将要创建的四个资源及其属性便于在真正执行前核对过滤条件与命名是否正确。4.3 应用配置terraform applyapply执行实际资源创建。首次执行时Terraform 会提示输入工程中定义的变量未提供默认值的项。4.4 变量清单与说明文档明确列出 Terraform 会提示的 7 个变量与 main.tf 末尾的variable声明一一对应#变量名含义默认值1credentials_file具备前述权限的 ServiceAccount 凭据文件路径无必填2zoneGCP 可用区如us-central1-b无必填3regionGCP 区域如us-central1无必填4projectGCP 项目 ID无必填5name用于创建 Pub/Sub Topic、Log RouterSink和 Pub/Sub Subscription 的名称cloud-logs6inclusion_filter包含过滤器决定导出哪些云资源的日志即上文 2.2/2.3 的过滤器空字符串默认不导出任何日志7exclusions排除列表在包含过滤的基础上忽略指定日志元素含name与filter两个字段[]空列表值得注意的两点设计inclusion_filter默认值为空字符串注释明确写着 default no logs should be ingested即默认不导出任何日志。这是刻意的安全设计——防止误配导致把全量日志灌入 Pub/Sub 产生巨额费用必须显式指定过滤条件才会真正导出。exclusions是一个对象列表其类型定义如下由dynamic exclusions块在 Sink 资源上逐条展开为 GCP 的排除规则variable exclusions { default [] description Logs exclusion filter that tells what kind of logs should be ignored type list(object({ name string filter string })) }4.5 通过 CLI 传参的实战示例变量有多种传入方式-var命令行参数、terraform.tfvars文件、环境变量等。文档给出了 CLI 传参的完整示例terraform apply \ -varcredentials_file./permissions.json \ -varzoneus-central1-b \ -varregionus-central1 \ -varprojectgrafanalabs-dev \ -varlognamecloud-logs注意示例命令中出现的-varlogname...是变量名的不严谨写法工程实际定义的变量名为name见 main.tf 中variable name应写为-varnamecloud-logs。更多变量赋值方式如 tfvars 文件、环境变量、默认值覆盖等可参考 Terraform 官方变量赋值文档。五、源码级拆解main.tf 的资源编排逻辑Terraform 工程本体 是理解这套方案的最佳材料其资源编排遵循主题 → 接收器 → 订阅 → 授权的依赖链5.1 Provider 配置terraform { required_providers { google { source hashicorp/google version 7.46.1 } } } provider google { credentials file(var.credentials_file) project var.project zone var.zone region var.region }5.2 第一步创建 Pub/Sub Topicresource google_pubsub_topic cloud-logs { name var.name }Topic 是日志出口所有被 Sink 选中的日志都会发布到这里。5.3 第二步创建 Logging Sink日志接收器resource google_logging_project_sink main { name var.name destination pubsub.googleapis.com/projects/${var.project}/topics/${var.name} filter var.inclusion_filter dynamic exclusions { for_each var.exclusions content { name exclusions.value.name filter exclusions.value.filter } } unique_writer_identity true }关键点解读destination指向第一步创建的 Topic使用 GCP 标准的pubsub.googleapis.com/projects/{project}/topics/{topic}格式filter直接接收inclusion_filter变量即文档 2.2/2.3 节演示的日志过滤器exclusions通过dynamic块动态展开支持多条排除规则unique_writer_identity true是打通权限的关键开关它让 Sink 获得一个独立的 writer identity便于后续精确授权见 5.5。5.4 第三步创建 Pub/Sub Subscriptionresource google_pubsub_subscription main { name var.name topic google_pubsub_topic.cloud-logs.name }Subscription 绑定到 Topic 上采集端如 promtail 的 GCP 目标通过订阅 ID 拉取日志。5.5 第四步IAM 授权——打通日志 → 主题写权限resource google_pubsub_topic_iam_binding log-writer { topic google_pubsub_topic.cloud-logs.name role roles/pubsub.publisher members [ google_logging_project_sink.main.writer_identity, ] }这一步将 Sink 的writer_identity绑定到 Topic 的roles/pubsub.publisher角色上使日志路由服务有权限把日志发布到该 Topic。如果缺少这一步即使 Sink 创建成功日志也不会被写入 Pub/Sub——这是实践中最容易遗漏的坑而本工程已内置处理。5.6 资源依赖关系小结从源码结构可以推断整个工程形成了清晰的依赖链google_pubsub_topic cloud-logs主题 │ ├── google_logging_project_sink main接收器destination 引用主题 │ └── 依赖其 writer_identity ├── google_pubsub_subscription main订阅引用主题名 └── google_pubsub_topic_iam_binding log-writer授权 Sink 可发布到主题Terraform 会自动根据资源间的引用关系推导执行顺序确保 Topic 先于 Sink / Subscription / IAM Binding 创建。六、对接 Loki 生态配置完成后的下一步Terraform 应用成功后你将得到一个名为name的 Pub/Sub Topic一个名为name的 Pub/Sub Subscription一个名为name的 Logging Sink已按inclusion_filter/exclusions决定日志流向。接下来在日志消费端Promtail配置 GCP Pub/Sub 目标填入订阅 ID、项目 ID 与订阅所需的凭证即可开始把 GCP 云日志拉入 Loki。采集端的具体配置方式请参考 Loki 官方文档中 Promtail 的 GCP 采集章节本仓库的 tools/gcplog 只负责 GCP 侧的日志导出准备工作。七、实践注意事项务必显式指定inclusion_filter默认值为空意味着不导出任何日志。若忘记配置Sink 虽创建成功但不会转发任何日志排查时容易误判为采集端问题。确认凭据角色齐全缺少roles/logging.configWriter会导致 Sink 创建失败缺少roles/pubsub.editor会导致主题/订阅创建失败。unique_writer_identity与 IAM 绑定配套使用不要手工改 Sink 的 writer identity 模式否则 IAM 绑定可能失效。合理使用exclusions当包含过滤条件过宽例如severityWARNING时用exclusions精确排除高噪声资源如健康检查日志可显著降低日志量与成本。凭据文件不要提交到版本库credentials_file指向的 JSON 包含高权限密钥建议通过.gitignore排除或使用 Terraform 的变量文件机制注入。结语tools/gcplog用一份不到 80 行的 Terraform 配置完整覆盖了GCP 日志导出到 Pub/Sub所需的全部资源与权限闭环日志过滤器控制范围、Sink 负责转发、Topic/Subscription 提供传输通道、IAM 绑定打通写权限。作为 Loki 生态在 Google Cloud 上的前置引流闸门它与采集端的配合让云上日志 → Loki的全链路变得可声明、可审计、可复现。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考