Vector × AWS Secrets Manager：为 S3 源、CloudWatch 指标与外部 API 统一托管凭证的实战配置指南-平芜编程栈

Vector × AWS Secrets Manager：为 S3 源、CloudWatch 指标与外部 API 统一托管凭证的实战配置指南

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

导读

本文以 Vector 官方示例指南（aws-secrets-manager-example.md）为主线，完整演示如何将 Vector 接入 AWS Secrets Manager，把 S3 访问密钥、数据库口令、外部 API Token、Webhook 校验密钥等敏感配置集中托管，并通过SECRET[backend.key]占位符在配置中安全引用。读完本文你将掌握：创建与读取 Secret 的 AWS 侧操作、最小权限 IAM 策略、secret配置段的完整写法、以及一个同时覆盖 S3 读取、CloudWatch 指标、外部 API 转发、S3 归档、PostgreSQL 指标与 Webhook 签名校验的生产级端到端配置。仓库侧配套的完整集成指南可见 aws-secrets-manager.md。

场景：一条管线、三类凭证、一种托管方式

示例设想的运行场景是：Vector 部署在生产环境，需要同时完成四条任务：

从 Amazon S3 读取应用日志（aws_s3source）；
将内部指标与转换后的日志指标发送到 Amazon CloudWatch（aws_cloudwatch_metricssink）；
把处理后的日志转发给外部 API；
将数据库口令、API Token、Webhook 密钥等敏感值全部存放在 AWS Secrets Manager 中统一管理。

如果不引入 Secrets Manager，上述凭证会以明文形式散落在vector.yaml里，配置文件一旦泄露或进入版本库，全部基础设施的密钥随即失守。接入 Secrets Manager 后，配置文件中只出现SECRET[aws_creds.s3_access_key]这类占位符，真实值在启动与重载时由 Vector 从后端拉取并替换。

前提条件

拥有具备 AWS Secrets Manager 访问权限的 AWS 账号；
已配置 AWS CLI（本文命令基于 AWS CLI）；
已安装 Vector v0.38.0 或更高版本（SECRET[]占位符解析依赖该版本起的功能）；
Vector 需以secrets-aws_secrets_managerfeature 编译。该 feature 在 Cargo.toml 中被纳入默认的secrets特性组，绝大多数发行版默认开启。

第一步：在 AWS Secrets Manager 中创建 Secret

使用 AWS CLI 创建一个包含所有敏感值的 JSON Secret。注意 Secret 必须是"字符串键 + 字符串值"的 JSON 对象（详见下文"Secret 格式"一节）：

aws secretsmanager create-secret \ --name "vector-production-credentials" \ --description "Credentials for Vector production deployment" \ --secret-string '{ "s3_access_key": "AKIA...", "s3_secret_key": "your-s3-secret-key", "external_api_token": "your-external-api-token", "database_password": "your-database-password", "webhook_secret": "your-webhook-secret" }' \ --region us-west-2

记下返回的Secret Name（vector-production-credentials）或Secret ARN，配置 Vector 时需要用到。

第二步：配置 IAM 最小权限

创建如下 IAM 策略并绑定到 Vector 运行所依赖的 IAM 角色或用户。策略同时覆盖三类权限：读取 Secret、读取 S3 日志桶、写入 CloudWatch 指标：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "arn:aws:secretsmanager:us-west-2:123456789012:secret:vector-production-credentials-*" ] }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::your-logs-bucket", "arn:aws:s3:::your-logs-bucket/*" ] }, { "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*" } ] }

说明：

Secrets Manager 的 ARN 末尾-*是 AWS 在 Secret 下挂接版本节点时自动追加的随机后缀，必须保留通配符才能匹配到真实资源；
读取 Secret 仅需secretsmanager:GetSecretValue一个 Action，遵循最小权限原则；
若还需使用aws_s3sink 写入归档桶，需要追加对应桶的s3:PutObject权限。

Vector 自身的 AWS 凭证获取方式

Vector 访问 Secrets Manager 所用的 AWS 凭证，与组件共用同一套凭据链（src/aws/mod.rs 中由AwsAuthentication构建 credentials provider 与 region provider），可按以下任一方式提供：

IAM 角色（推荐，EC2/ECS/EKS 场景）：给计算资源附加 IAM 实例/任务角色；
AWS 凭证文件：在~/.aws/credentials写入aws_access_key_id与aws_secret_access_key；
环境变量：导出AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION。

第三步：Vector 配置——`secret`段与`SECRET[]`占位符

3.1 声明 AWS Secrets Manager 后端

在配置顶部新增secret段声明后端，示例使用aws_creds作为后端名：

secret: aws_creds: type: aws_secrets_manager secret_id: "vector-production-credentials" region: "us-west-2"

各配置项含义如下：

配置项	类型	说明
`type`	string	固定为`aws_secrets_manager`，对应后端组件
`secret_id`	string	必填。Secret 的名称或 ARN
`region`	string	Secret 所在区域；省略时回退到默认区域解析链
`auth.access_key_id`	string	可选。显式指定 AWS Access Key
`auth.secret_access_key`	string	可选。显式指定 AWS Secret Key
`auth.session_token`	string	可选。临时凭证的会话 Token
`auth.assume_role`	string	可选。需要扮演的 IAM 角色 ARN
`auth.external_id`	string	可选。角色扮演时的 External ID
`tls`	object	可选。TLS 配置

从源码看，后端结构体AwsSecretsManagerBackend（src/secrets/aws_secrets_manager.rs）包含secret_id、内联展开的RegionOrEndpoint、AwsAuthentication与可选的tls；region通过RegionOrEndpoint解析，同时支持自定义 endpoint，便于对接兼容 S3 协议的对象存储或本地模拟服务。

3.2 用`SECRET[backend.key]`引用敏感值

占位符语法为SECRET[<backend_name>.<key_name>]，例如SECRET[aws_creds.s3_access_key]。其解析由正则SECRET\[([[:word:]\-]+)\.([[:word:].\-/]+)\]驱动（src/config/loading/secret.rs），规则要点：

后端名只能包含字母、数字、下划线与连字符；
键名可包含字母、数字、点、连字符与斜杠，因此既支持SECRET[aws_creds.external_api_token]，也支持嵌套键如SECRET[aws_creds.a_third.secret_key]或类路径键SECRET[aws_creds.path/to/secret]；
形如SECRET[secret_name]（缺少点分隔）的写法不匹配，会原样保留在配置中。

加载时，Vector 会先扫描配置收集所有占位符（collect_secret_keys），再按后端分组一次性调用retrieve（src/config/loading/secret.rs），最后在配置解析前执行替换（interpolate）。若某占位符找不到对应值，会报Unable to find secret replacement for SECRET[...]并拒绝启动，避免带病运行。

3.3 完整端到端配置

# vector.yaml # 1. 声明 AWS Secrets Manager 后端 secret: aws_creds: type: aws_secrets_manager secret_id: "vector-production-credentials" region: "us-west-2" # 2. 源：从 S3 读取日志，S3 凭证取自 Secret sources: s3_logs: type: aws_s3 region: "us-west-2" bucket: "your-logs-bucket" key_prefix: "application-logs/" auth: access_key_id: "SECRET[aws_creds.s3_access_key]" secret_access_key: "SECRET[aws_creds.s3_secret_key]" # 源：Vector 内部指标 internal_metrics: type: internal_metrics # 3. 转换：解析并富化日志 transforms: parse_logs: type: remap inputs: - s3_logs source: | . = parse_json!(.message) .timestamp = now() .environment = "production" # 转换：从日志生成自定义指标 generate_metrics: type: log_to_metric inputs: - parse_logs metrics: - type: counter field: level name: log_events_total namespace: application tags: level: "{{ level }}" service: "{{ service }}" # 4. 目标：指标发送到 CloudWatch sinks: cloudwatch_metrics: type: aws_cloudwatch_metrics inputs: - internal_metrics - generate_metrics namespace: "Vector/Application" region: "us-west-2" # 目标：转发日志到外部 API，Token 取自 Secret external_api: type: http inputs: - parse_logs uri: "https://logs.example.com/v1/ingest" encoding: codec: json compression: gzip headers: Authorization: "Bearer SECRET[aws_creds.external_api_token]" X-API-Version: "v1" batch: max_bytes: 1048576 # 1MB timeout_secs: 30 # 目标：处理后的日志归档到 S3，复用同一组 Secret 凭证 s3_archive: type: aws_s3 inputs: - parse_logs bucket: "your-archive-bucket" key_prefix: "processed-logs/%Y/%m/%d/" region: "us-west-2" compression: gzip encoding: codec: ndjson auth: access_key_id: "SECRET[aws_creds.s3_access_key]" secret_access_key: "SECRET[aws_creds.s3_secret_key]" # 可选：PostgreSQL 指标源，口令取自 Secret postgres_metrics: type: postgresql_metrics endpoints: - "postgresql://vector:SECRET[aws_creds.database_password]@postgres.internal:5432/metrics" scrape_interval_secs: 60 # 可选：Webhook 接收源 webhook: type: http_server address: "0.0.0.0:8080" decoding: codec: json framing: method: bytes # 5. 转换：校验 Webhook 签名，密钥取自 Secret validate_webhook: type: remap inputs: - webhook source: | expected_signature = hmac_sha256(string!(.message), "SECRET[aws_creds.webhook_secret]") if .headers."x-signature" != expected_signature { abort }

关键点解读：

同一后端多处引用：s3_access_key/s3_secret_key在s3_logs源与s3_archivesink 中被重复引用，Vector 收集占位符时会对每个后端键去重，只向 Secrets Manager 发起一次GetSecretValue调用（src/config/loading/secret.rs），随后统一替换；
占位符可出现在 URL 中：postgresql://vector:SECRET[...]@postgres.internal:5432/metrics说明占位符不仅能用于字段值，也能嵌入连接串，替换发生在配置解析之前，因此对最终组件透明；
占位符可出现在 VRL 脚本中：hmac_sha256(string!(.message), "SECRET[aws_creds.webhook_secret]")表明签名校验等逻辑同样可以引用 Secret——替换发生在 VRL 编译之前，替换结果会作为脚本常量参与后续执行；
注意validate_webhook与webhook之间缺少inputs以外的衔接：webhook源与validate_webhook转换的inputs引用关系在示例中即按上述写法呈现，实际部署时需确保validate_webhook的inputs指向webhook，并将校验后的数据继续接入下游 sink。

第四步：部署 Vector

# 前台运行 vector --config vector.yaml # 或作为 systemd 服务运行 sudo systemctl start vector

启动时 Vector 会完成占位符收集、后端凭证校验与 Secret 拉取，全部成功后才加载拓扑。之后每当 Vector 收到SIGHUP触发配置热重载时，都会重新执行这一流程（src/secrets/mod.rs），因此 Secrets Manager 中轮换后的新值会在下一次重载时生效。

第五步：监控与验证

# 实时查看 Vector 日志 journalctl -u vector -f # 验证指标是否已发送到 CloudWatch aws cloudwatch list-metrics --namespace "Vector/Application" # 检查 S3 归档是否生成 aws s3 ls s3://your-archive-bucket/processed-logs/

排查阶段可临时开启 debug 日志观察 Secret 拉取过程：

log: level: debug

运行vector --config vector.yaml 2>&1 | grep -i secret，可看到Secret placeholders found, retrieving secrets from configured backends.与Retrieving secrets from a backend.等调试信息（相关日志埋点在 src/config/loading/secret.rs）。

底层原理：从占位符到真实凭证的完整链路

结合源码，一次 Secret 解析的完整链路如下：

收集：SecretBackendLoader::prepare读取配置原文，先做环境变量插值，再用COLLECTOR正则扫描出所有SECRET[...]占位符，按后端名 -> 键集合聚合（src/config/loading/secret.rs）；
拉取：retrieve_secrets遍历每个后端，调用SecretBackend::retrieve。AWS 后端通过aws-sdk-secretsmanager构建客户端，调用get_secret_value()获取整份 Secret 字符串（src/secrets/aws_secrets_manager.rs）；
校验：返回内容必须是字符串键值 JSON（HashMap<String, String>）。对请求的每个键，缺键报key '...' does not exist，空值报value for key '...' was empty（src/secrets/aws_secrets_manager.rs），任一失败都会中断启动；
替换：interpolate把占位符替换为backend.key对应的真实值，替换失败（如占位符所指后端未配置）时报Backend "..." is required for secret retrieval but was not found in config.（src/config/loading/secret.rs）并终止加载。

需要说明：AWS 后端与 exec/file/directory 等后端通过enum_dispatch统一抽象为SecretBackends（src/secrets/mod.rs），aws_secrets_manager变体仅在启用secrets-aws_secrets_managerfeature 时编译，这也解释了"未启用该 feature 的构建无法识别type: aws_secrets_manager"的原因。

Secret 格式约束

AWS Secrets Manager 中的 Secret 必须是可以反序列化为字符串键值映射的 JSON 对象：

{ "key1": "value1", "key2": "value2", "database_url": "postgresql://user:pass@host:5432/db", "api_key": "your-secret-api-key" }

Vector 会拉取整份 Secret，再把其中每个键值对以SECRET[backend_name.key_name]的形式对外暴露。值为空字符串或包含非字符串值都会导致解析失败。

安全注意事项

最小权限：只授予 Vector 所需的secretsmanager:GetSecretValue，并将 Resource 限定到具体 Secret；
密钥轮换：利用 AWS Secrets Manager 的自动轮换能力；Vector 在启动与配置重载时获取最新值，轮换后的新值无需重启即可生效；
网络安全：确保 Vector 能访问 Secrets Manager 服务端点，VPC 环境下需配置 VPC Endpoint 或相应路由；
日志安全：控制日志级别，避免 Secret 值被写入 Vector 日志。仓库在 AWS HTTP 客户端层将x-amz-security-token、x-amz-sso_bearer_token、x-aws-ec2-metadata-token等凭证相关请求头标记为敏感头，不外泄到日志（src/aws/mod.rs）；
磁盘缓冲：使用 disk buffer 时 Secret 可能以明文落在磁盘上，请为 Vector 数据目录设置合适的文件权限与磁盘加密。

故障排查速查

错误信息	排查方向
`Backend not found in config`	检查`SECRET[backend.key]`中的后端名与`secret:`段声明的名称是否完全一致
`Key does not exist`	确认键名存在于 Secret 中，且 Secret 是合法 JSON
`Secret could not be retrieved`	检查 AWS 凭证权限、Secret ID/ARN 是否正确、Secret 是否位于指定 region
AWS 认证错误	核对 AWS 凭证配置、IAM 权限与 region 设置
`Unable to find secret replacement for SECRET[...]`	占位符语法不符合`SECRET[backend.key]`正则（如缺少点号），或后端未配置

后续进阶

本示例与仓库中的完整集成指南 aws-secrets-manager.md 互为补充：后者进一步覆盖配置选项表格、Secret 格式、安全最佳实践与更细的故障排查；Vector Secrets 管理的通用机制可参考 src/secrets/mod.rs 与 src/config/loading/secret.rs。将该机制与 AWS 组件共享的凭据链（src/aws/mod.rs）结合，即可在 S3、CloudWatch、PostgreSQL、外部 HTTP API 等场景中建立统一的、不落盘的凭证管理体系。

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Vector × AWS Secrets Manager：为 S3 源、CloudWatch 指标与外部 API 统一托管凭证的实战配置指南