Envoy AWS Request Signing 过滤器的凭证提供者链（Credentials Provider Chain）完全指南

Envoy AWS Request Signing 过滤器的凭证提供者链（Credentials Provider Chain）完全指南

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy

导读

在 Envoy 中，AWS Request Signing 过滤器（envoy.filters.http.aws_request_signing）用于为发往 AWS 服务的请求自动计算并注入 SigV4/SigV4A 签名，其签名密钥来源于一套可配置的AWS 凭证提供者链（AWS Credentials Provider Chain）。本文以仓库中的 aws_credentials.rst 为核心，系统讲解该过滤器的凭证获取顺序、各级提供者的实现细节、顺序覆盖与自定义链的配置方法，以及相关统计指标；同时结合 credential_provider.proto 与示例配置，帮助读者在生产环境中准确配置 AWS 请求签名能力。读完本文，你将能够：理解默认凭证链的完整搜索顺序与缓存语义、通过credential_provider字段覆盖或重建凭证链、并为 EC2/ECS/EKS 等容器与实例场景正确落地配置。

凭证获取的总览：默认链与两种介入方式

AWS Request Signing 过滤器使用多种凭证提供者来获取 AWS access key ID、AWS secret access key 与可选的 AWS session token。默认情况下，过滤器按下文描述的固定顺序依次尝试各个提供者，一旦某个提供者返回了 access key ID 和 secret access key（session token 可选），即停止继续向下搜索。

这一默认行为可以通过过滤器配置中的credential_provider字段以两种方式介入：

• 修改默认链（modify）：在custom_credential_provider_chain为false（默认值）时，配置中给出的提供者设置作为对默认凭证提供者链的"修饰器"，用于覆盖默认链中对应提供者的环境变量、凭证参数与文件位置等细节；
• 自定义链（custom）：在custom_credential_provider_chain为true时，创建一个只包含配置中指定提供者设置的全新凭证链，默认链被整体禁用。

上述两个字段定义在 credential_provider.proto 的AwsCredentialProvider消息中，注释明确写道："If set to TRUE, the credential provider chain that is created contains only those set in this credential provider message. If set to FALSE, the settings provided here will act as modifiers to the default credential provider chain. Defaults to FALSE."（设为 TRUE 时仅包含配置中指定的提供者；设为 FALSE 时作为默认链的修饰器；默认 FALSE）。

此外，AwsCredentialProvider还声明了以下可配置的提供者类型（对应 proto 中的字段号）：

注意：proto 中的字段顺序（inline、assume_role_with_web_identity、credentials_file、config、container、environment、instance_profile、assume_role、iam_roles_anywhere）与默认链的搜索顺序并不一致。默认搜索顺序由过滤器内部实现决定，详见下文"默认凭证提供者顺序"一节。

默认凭证链的 6 级搜索顺序

默认情况下，过滤器按下述顺序逐级尝试获取凭证：

1. inline_credentials 内联凭证（最高优先级）

如果配置了inline_credential字段，则不会使用任何其他提供者——整条链被直接短路。在 credential_provider.proto 中注释为："If inline credential is provided, no chain will be created and only the inline credential will be used."

InlineCredentialProvider消息（credential_provider.proto）等价于设置AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY及可选的AWS_SESSION_TOKEN环境变量，其中access_key_id与secret_access_key均要求min_len: 1非空校验，且secret_access_key与session_token被标记为敏感字段（sensitive注解），在日志与调试输出中会被脱敏。

2. credential_provider 字段的覆盖能力

过滤器配置的credential_provider字段（即上文所述的两类介入方式）可以覆盖默认提供者、环境变量、凭证参数与文件位置。当配合custom_credential_provider_chain: true时，将创建仅含指定提供者的自定义链。具体配置示例见 aws-request-signing-filter-credential-provider-config.yaml 与 aws-request-signing-filter-assumeroleprovider.yaml。

3. 环境变量

读取标准 AWS 环境变量AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY与AWS_SESSION_TOKEN。该提供者对应 proto 中的environment_credential_provider（空消息，无任何可配置参数，列出它即可在自定义链中启用）。

4. AWS 凭证文件

• 若设置了AWS_SHARED_CREDENTIALS_FILE与AWS_PROFILE环境变量则优先使用，否则回退到文件~/.aws/credentials与default配置节；
• 使用配置节中定义的aws_access_key_id、aws_secret_access_key、aws_session_token字段；
• 该类凭证缓存 1 小时。

在 proto 中对应credentials_file_provider，额外支持credentials_data_source（从 Envoy DataSource 读取凭证文件）与profile（指定配置节，缺省为 default），详见 credential_provider.proto。注意：当通过watched_directory配置监视目录后，一旦检测到文件移动（file move），凭证文件会被重新读取，实现凭证的滚动更新。

5. AssumeRoleWithWebIdentity（STS Web 身份）

该提供者向 AWS Security Token Service 发起AssumeRoleWithWebIdentityAPI 调用：

• 通过AWS_WEB_IDENTITY_TOKEN_FILE环境变量指向的文件读取WebIdentityToken；
• 通过AWS_ROLE_ARN环境变量读取 role ARN；
• 若配置了credential_provider，则可在assume_role_with_web_identity_provider中直接指定role_arn、web_identity_token_data_source与role_session_name字段，取代环境变量方式；
• 返回结果中提取AccessKeyId、SecretAccessKey、SessionToken字段，凭证缓存 1 小时或直到其过期（取决于返回的Expiration字段）。

文件轮换（token rotation）自动感知：assume_role_with_web_identity_provider会自动监视所配置的 web identity token 文件所在目录（若未显式设置watched_directory，则从 token 文件的目录自动推断），因此当 token 文件被轮换时，新 token 会被拾取。即使发生文件轮换，当前凭证仍会继续使用直到过期，过期后再用新 token 获取新凭证。这一点在 credential_provider.proto 中也有对应说明："This behaviour differs from the standard envoy data source behavior, which does not automatically watch the directory of a file data source."

STS 静态集群：为获取凭证，Envoy 会创建一个名为sts_token_service_internal-<region>的静态集群，指向区域化 AWS Security Token Service。

SigV4A 下的 STS 集群主机选择（signing_algorithm: AWS_SIGV4A时生效）：

• 如果region（来自 profile、环境变量或内联配置）被配置为 SigV4A 区域集（region set）且第一个区域包含通配符：
  • 标准端点：sts.amazonaws.com
  • FIPS 端点：sts-fips.us-east-1.amazonaws.com
• 否则：使用区域端点sts.<first-region>.amazonaws.com

AWS 其他分区（如中国区或 GovCloud）提示：使用 SigV4A 签名时，若需访问中国区（如cn-northwest-1）、GovCloud 等分区，请将第一个 SigV4A 区域设置为不含通配符的具体区域，以便正确选择区域端点。

6. 实例元数据：EC2 / ECS / EKS Pod Identity

最后一级尝试从计算实例的元数据服务获取凭证：

• EC2 instance metadata：使用字段AccessKeyId、SecretAccessKey、Token，凭证缓存 1 小时；
• ECS task metadata：使用字段AccessKeyId、SecretAccessKey、Token，凭证缓存 1 小时或直到过期（依据Expiration字段）；
• EKS Pod Identity：环境变量AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE指向容器内挂载的文件，其中包含发送给 EKS Pod Identity Agent 的Authorization头所需字符串。使用字段AccessKeyId、SecretAccessKey、Token，凭证缓存 1 小时或直到过期。

两种凭证获取方式：当前实现支持两种元数据获取方式——

• HTTP async client（新，推荐）；
• libcurl（legacy 兼容）。

必须配置静态集群：要从 EC2 或 ECS 获取凭证，必须在配置中指定指向凭证提供者的静态集群：

• EC2：集群名ec2_instance_metadata_server_internal
• ECS：集群名ecs_task_metadata_server_internal

这些静态集群自动托管：若 bootstrap 配置中未指定，会自动添加；即使在envoy.reloadable_features.use_http_client_to_fetch_aws_credentials被禁用时也会创建，以确保后续将该 reloadable feature 置为true启用 HTTP client 获取凭证时集群配置已就绪。

默认凭证提供者顺序（Credential Provider Ordering）

默认情况下，凭证提供者按以下顺序被依次搜索：

1. inline_credential（内联凭证）
2. environment_credential_provider（环境变量）
3. credentials_file_provider（凭证文件）
4. assume_role_credential_provider（STS AssumeRole 角色链）
5. assume_role_with_web_identity_provider（Web 身份）
6. container_credential_provider（容器凭证，ECS）
7. instance_profile_credential_provider（实例配置文件，EC2）

通过credential_provider字段，可以只启用部分提供者，或覆盖任意可配置提供者的设置。

assume_role 提供者的特殊性：assume_role_credential_provider是一个特例——它自己拥有一个内嵌的credential_provider字段。原因在于：该提供者本身需要先获得一组凭证来完成sts:AssumeRole调用。默认情况下，其内嵌提供者的搜索顺序与上述默认顺序相同；除非你选择覆盖其中的提供者与设置。相关消息定义见 credential_provider.proto，其中role_arn必填，external_id、role_session_name可选，session_duration的取值范围为 900 秒（5 分钟）至 43200 秒（12 小时），未提供时由 AWS 端按 IAM AssumeRole 默认时长表 决定。另外，内嵌credential_provider的提供者列表中不允许再出现 assume_role 提供者，若出现则会被忽略（防止无限递归的角色链）。

注意：proto 中assume_role_credential_provider在字段编号上是 10 号，而默认链将其排在第 4 位，再次说明"字段编号 ≠ 搜索优先级"，默认顺序以本节的编号 1–7 为准。

从源码实现看，默认链的构建位于 credential_provider_chains.cc，其中通过singletonManager().getTyped<AwsClusterManagerImpl>管理 STS/元数据静态集群（见该文件第 112–115 行附近），并分别创建ContainerCredentialsProvider与InstanceProfileCredentialsProvider（第 324 行、第 356 行附近），与文档描述的容器/实例提供者一一对应。

自定义链配置实操：两份官方示例

示例一：仅使用凭证文件并监视目录变更

以下配置（来自 aws-request-signing-filter-credential-provider-config.yaml）演示了用custom_credential_provider_chain: true关闭默认链、仅启用凭证文件提供者，并通过watched_directory让过滤器在凭证文件变化时自动重载：

http_filters: - name: envoy.filters.http.aws_request_signing typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning credential_provider: custom_credential_provider_chain: true credentials_file_provider: credentials_data_source: filename: /tmp/a watched_directory: path: /tmp service_name: vpc-lattice-svcs region: '*' signing_algorithm: AWS_SIGV4A use_unsigned_payload: true match_excluded_headers: - prefix: x-envoy - prefix: x-forwarded - exact: x-amzn-trace-id

要点解读：

• custom_credential_provider_chain: true：整条默认链被禁用，链中仅包含下面列出的credentials_file_provider；
• credentials_data_source.filename: /tmp/a：从/tmp/a读取 AWS 凭证格式文件；
• watched_directory.path: /tmp：监视/tmp目录，检测到文件移动（如轮换写入）时重新读取凭证文件；
• signing_algorithm: AWS_SIGV4A+region: '*'：使用通配区域集，简化多区域配置。

示例二：通过 AssumeRole 实现角色链

以下配置（来自 aws-request-signing-filter-assumeroleprovider.yaml）演示了 assume_role 提供者及其内嵌凭证链的用法——先以 EC2 实例配置文件凭证签署sts:AssumeRole请求，再以换取的角色凭证对外签名：

http_filters: - name: envoy.filters.http.aws_request_signing typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning credential_provider: custom_credential_provider_chain: true assume_role_credential_provider: role_arn: arn:aws:iam::12345678:role/testassume credential_provider: custom_credential_provider_chain: true instance_profile_credential_provider: {} service_name: vpc-lattice-svcs region: 'ap-southeast-2' signing_algorithm: AWS_SIGV4 use_unsigned_payload: true match_excluded_headers: - prefix: x-envoy - prefix: x-forwarded - exact: x-amzn-trace-id

要点解读：

• 外层assume_role_credential_provider指定目标角色role_arn；
• 其内嵌credential_provider声明仅使用instance_profile_credential_provider（空消息，无参数）来签署 AssumeRole 请求——这正好印证了上文"assume_role 提供者自己拥有内嵌 credential_provider"的特殊设计；
• 若内嵌credential_provider未设置，则按默认链顺序（环境变量 → 凭证文件 → …）获取签署 AssumeRole 请求所需的凭证。

过滤器基础配置速览

在进入统计指标之前，补充过滤器的最简配置（来自 aws-request-signing-filter.yaml），便于对照理解上文各字段的上下文：

http_filters: - name: envoy.filters.http.aws_request_signing typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning service_name: s3 region: us-west-2 use_unsigned_payload: true match_excluded_headers: - prefix: x-envoy - prefix: x-forwarded - exact: x-amzn-trace-id

• service_name：签名所针对的 AWS 服务名（如s3、vpc-lattice-svcs）；
• region：SigV4 目标区域；若使用 SigV4A 则作为区域集（region set），支持逗号分隔与通配符（如us-east-*甚至*）；
• use_unsigned_payload: true：不对请求体缓冲计算 payload hash（适合 S3 等允许 unsigned payload 的服务）；默认为false，此时超过缓冲区限制的请求会收到 413 响应；
• match_excluded_headers：从签名中排除的请求头，常用于排除可能在重试等场景中发生变化的头；x-forwarded-for、x-forwarded-proto、x-amzn-trace-id默认始终被排除。

关于凭证相关的更完整过滤器语义，可进一步阅读 AWS Request Signing 过滤器文档，其中包含：

• 头部修改行为（Header Modification）：authorization头被替换为计算出的 SigV4/SigV4A 值；x-amz-security-token被移除或按 session token 替换；x-amz-date被替换为当前日期；使用 SigV4A 时x-amz-region-set被替换；
• 查询串签名（query string signing）：签名放入查询串而非头部，附带expiration_time（默认 5 秒、最大 3600 秒），URL 在此时间内可重放，建议尽量取小值；
• 上游 HTTP 过滤器用法（upstream filter）：由于签名基于 host/URL/payload 计算，若 Envoy 在签名后还会修改这些字段会导致签名失效，因此可将该过滤器配置在 cluster 的http_filters链中，作为转发前签名的最后一步。

统计指标（Statistics）

凭证相关统计输出在aws.metadata_credentials_provider命名空间下，其中<provider_cluster>为实际的提供者集群名（如 STS 集群sts_token_service_internal-<region>、ec2_instance_metadata_server_internal、ecs_task_metadata_server_internal）：

这些指标与 AWS Request Signing 过滤器自身的统计（http.<stat_prefix>.aws_request_signing.*命名空间下的signing_added、signing_failed、payload_signing_added、payload_signing_failed）互补：前者反映凭证侧的健康度（刷新是否成功），后者反映签名侧的处理结果。

实践要点与排查建议

1. 优先内联、慎用默认链：生产环境若凭证来源单一，推荐用custom_credential_provider_chain: true明确指定提供者，避免默认链在多级元数据服务间反复探测（可能引入延迟与额外 STS 调用）。
2. 容器/实例场景必须配置静态集群：EC2 需集群名ec2_instance_metadata_server_internal、ECS 需集群名ecs_task_metadata_server_internal，虽然未配置时 Envoy 会自动创建，但显式声明有助于你通过统计指标定位问题。
3. 凭证轮换是自动的：凭证文件提供者支持watched_directory监视文件移动；Web 身份 token 目录会被自动监视。轮换发生后，旧凭证会继续用到过期，随后自动用新 token 换发。
4. SigV4A 分区注意：中国区 / GovCloud 等非标准分区请将首个 SigV4A 区域写为无通配符的具体区域名（如cn-northwest-1），确保 STS 端点选择正确。
5. 监控三个刷新指标：重点关注credential_refreshes_failed与metadata_refresh_state是否长期处于 0（初始状态），可快速判断凭证链是否真正生效。

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy