AWS CLI 中 CloudFront list-distribution-tenants-by-customization 命令的完整指南按 Web ACL 与证书筛选分发租户【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读本文以 aws-cli 官方示例文档为骨架深入讲解aws cloudfront list-distribution-tenants-by-customization命令的用法、请求参数与返回结构。该命令用于在多租户 CloudFront 分发multi-tenant distribution场景下按租户级自定义配置WAF Web ACL 或 ACM 证书筛选出关联的分发租户distribution tenant帮助开发者快速定位“哪些租户正在使用某个特定安全策略或证书”。读完本文你将掌握该命令的完整参数表、分页机制、返回字段语义、常见错误处理以及从仓库 service 模型与分页器源码中印证到的底层实现细节。一、命令概览解决什么问题在多租户 CloudFront 架构中一个多租户分发multi-tenant distribution下挂载着多个分发租户distribution tenant每个租户可以拥有自己的域名、地理限制、WAF Web ACL 和 ACM 证书等自定义配置。当运维或安全团队需要审计“当前哪些租户引用了某个 Web ACL 或某个 ACM 证书”时逐条调用 list-distribution-tenants 再去逐个比对 Customizations 字段显然低效且易错。list-distribution-tenants-by-customization正是为此设计的反向索引查询命令以自定义配置customization为过滤条件返回使用了该自定义的所有分发租户列表。其核心价值在于按 WAF Web ACL ARN 过滤快速发现共享同一安全策略的租户集合按 ACM 证书 ARN 过滤便于统一规划证书续期、轮换或下线返回结果可直接与 create-distribution-tenant、update-distribution-tenant 等命令配合构成“查询—变更—再查询”的完整运维闭环。从仓库中的服务模型 service-2.json 可以看到该 API 的 HTTP 层定义为POST /2020-05-31/distribution-tenants-by-customization响应码 200其官方文档描述为Lists distribution tenants by the customization that you specify. You must specify either theCertificateArnparameter orWebACLArnparameter, but not both in the same request.——这直接确认了两个过滤参数二选一、不可同时给出的使用约束。二、命令语法与示例原文档示例完整继承原文档给出的标准调用方式如下aws cloudfront list-distribution-tenants-by-customization \ --web-acl-arn arn:aws:wafv2:us-east-1:123456789012:global/webacl/CreatedByCloudFront-0273cd2f/a3c19bce-42b5-48a1-a8d4-b2bb2f28eabc2.1 参数说明参数类型是否必填说明--web-acl-arnstring与--certificate-arn二选一要作为过滤条件的 WAF Web ACL 的 ARN。注意示例中该 ARN 使用global段并指向CreatedByCloudFront-*前缀的 Web ACL这是 CloudFront 专用区域为 global的 WAFv2 Web ACL 典型形态--certificate-arnstring与--web-acl-arn二选一要作为过滤条件的 ACM 证书的 ARN--markerstring否分页游标用于获取下一组结果详见第四节--max-itemsinteger否单次请求返回的最大租户数量2.2 示例输出原样保留{ DistributionTenantList: [ { Id: dt_2wjDZi3hD1ivOXf6rpZJOSNE1AB, DistributionId: E1XNX8R2GOAABC, Name: example-tenant-2, Arn: arn:aws:cloudfront::123456789012:distribution-tenant/dt_2wjDZi3hD1ivOXf6rpZJOSNE1AB, Domains: [ { Domain: example.com, Status: inactive } ], ConnectionGroupId: cg_2wjDWTBKTlRB87cAaUQFaakABC, Customizations: { WebAcl: { Action: override, Arn: arn:aws:wafv2:us-east-1:123456789012:global/webacl/CreatedByCloudFront-0273cd2f/a3c19bce-42b5-48a1-a8d4-b2bb2f28eabc }, GeoRestrictions: { RestrictionType: whitelist, Locations: [ AL ] } }, CreatedTime: 2025-05-06T15:42:28.54200000:00, LastModifiedTime: 2025-05-06T16:14:08.71000000:00, ETag: E1F83G8C2ARABC, Enabled: true, Status: Deployed } ] }从输出可以看出该命令返回DistributionTenantList列表命中条件的租户example-tenant-2在其Customizations.WebAcl中明确记录了Action: override以及对应的Arn即它在多租户分发基础上**覆盖override**了父级 Web ACL从而命中本次按该 Web ACL ARN 的查询。注意示例中该租户的Domains状态为inactive说明域名尚未生效但租户仍会被列出——过滤条件是“使用了指定 customization”与域名激活状态无关。三、请求与响应模型源码级拆解3.1 请求结构在服务模型中请求体 shape 定义见 service-2.jsonListDistributionTenantsByCustomizationRequest ├── WebACLArn : string # Filter by the ARN of the associated WAF web ACL. ├── CertificateArn : string # Filter by the ARN of the associated ACM certificate. ├── Marker : string # The marker for the next set of results. └── MaxItems : integer # The maximum number of distribution tenants to return by the specified customization.四个成员均为可选但正如官方文档强调的WebACLArn与CertificateArn必须在请求中指定其一且不能同时出现。这一约束由服务端校验违反时返回InvalidArgument错误。3.2 响应结构响应 shape 见 service-2.jsonListDistributionTenantsByCustomizationResult ├── NextMarker : string # 分页令牌用于发起下一次请求 └── DistributionTenantList : list of DistributionTenantSummary列表元素类型为DistributionTenantSummary其必填字段required包括Id、DistributionId、Name、Arn、Domains、CreatedTime、LastModifiedTime和ETag见 service-2.json这与完整DistributionTenant结构见 service-2.json一脉相承。两个结构的关键字段语义如下字段类型说明Idstring分发租户 ID形如dt_2wjDZi3hD1ivOXf6rpZJOSNE1ABDistributionIdstring所属多租户分发的 ID形如E1XNX8R2GOAABCNamestring租户名称Arnstring租户 ARN形如arn:aws:cloudfront::123456789012:distribution-tenant/idDomainslist与该租户关联的域名列表每个元素含Domain与Statusactive/inactiveConnectionGroupIdstring租户所属连接组 ID未指定时 CloudFront 使用默认连接组Customizationsstructure租户级自定义配置可覆盖或禁用来自多租户分发的 ACM 证书、WAF Web ACL 与地理限制Parametersstructure多租户分发中标记为必填的参数键值对CreatedTimetimestamp租户创建时间LastModifiedTimetimestamp租户最后更新时间ETagstring租户当前版本的 ETag可用于并发控制与后续更新Enabledboolean是否处于启用状态禁用时租户不对外服务流量Statusstring租户状态示例中为Deployed其中Customizations内部的关键点WebAcl.Action可取override覆盖父级配置或disable禁用 Web ACL这在与 list-distribution-tenants 的输出对比中可以看到两种形态——后者示例中某租户即返回WebAcl: { Action: disable }表示该租户显式禁用了 Web ACL。四、分页机制Marker / NextMarker / MaxItems与 CloudFront 大部分列表类 API 一致该命令支持标准的分页游标模式。分页器定义见 paginators-1.jsonListDistributionTenantsByCustomization: { input_token: Marker, output_token: NextMarker, limit_key: MaxItems, result_key: DistributionTenantList }这意味着请求侧通过--marker传入上一轮响应中的NextMarker通过--max-items限制单页条数响应侧若结果被截断响应中会携带NextMarker将其作为下一次请求的--marker即可继续翻页若没有更多数据则无NextMarkerAWS CLI 的自动分页CLI 底层基于该分页器模型自动把result_keyDistributionTenantList各页拼接为完整列表因此大多数情况下你无需手动处理分页直接拿到全部结果。需要注意的是NextMarker与NextToken不同NextToken出现在 list-distribution-tenants 的示例输出中如eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAzfQ这类 base64 令牌而本命令使用NextMarker作为游标字段两者语义等价但字段名不同实际使用时以各自命令的输出为准。五、常见错误与排错指引服务模型 service-2.json 中为该 API 声明的错误类型只有三种错误触发场景AccessDenied调用方 IAM 身份缺少cloudfront:ListDistributionTenantsByCustomization权限或无权访问指定 Web ACL / 证书EntityNotFound指定的WebACLArn或CertificateArn不存在、不属于当前账号或已删除InvalidArgument同时传入了WebACLArn与CertificateArn、参数格式非法如 ARN 语法错误、或MaxItems取值非法实践建议先通过 list-distribution-tenants 确认目标租户确实挂载了你打算过滤的 Web ACL 或证书避免误判确认 ARN 的global段与资源 IDCloudFront 关联的 WAFv2 Web ACL 属于全局区域资源ARN 中必须包含global若要“反向”查询某个租户当前生效的自定义配置可直接使用 get-distribution-tenant 查看单个租户详情与本命令形成互补。六、与周边命令配合的运维场景该命令天然属于 CloudFront 多租户命令族仓库 awscli/examples/cloudfront/ 中与之相邻的示例包括list-distribution-tenants.rst按连接组/分发 ID 列出全部租户无自定义过滤条件时的全量视图create-distribution-tenant.rst 与 update-distribution-tenant.rst创建与更新租户其中可指定 Web ACL / 证书等自定义associate-distribution-tenant-web-acl.rst 与 disassociate-distribution-tenant-web-acl.rst为租户绑定/解绑 Web ACLlist-domain-conflicts.rst 与 list-invalidations-for-distribution-tenant.rst域名冲突检测与失效操作。典型安全审计流程当需要为某个 Web ACL 升级规则或准备下线时先执行本命令按--web-acl-arn找出全部受影响租户再结合get-distribution-tenant逐个确认其Customizations.WebAcl.Action是override还是disable最后通过update-distribution-tenant或disassociate-distribution-tenant-web-acl完成批量变更避免遗漏任何依赖该 Web ACL 的租户。七、使用前提与限制命令版本该命令在较新版本的 AWS CLI 中可用当前仓库的 CloudFront 服务模型 API 版本为2020-05-31使用前请确保aws --version满足要求多租户分发可用性分发租户distribution tenant是 CloudFront 多租户分发multi-tenant distribution能力的一部分该命令仅对多租户场景有效不适用于传统单租户分发过滤互斥--web-acl-arn与--certificate-arn二选一这是服务端强约束违反将返回InvalidArgument权限要求需要 IAM 策略授予cloudfront:ListDistributionTenantsByCustomization操作权限同时需具备对目标 WAF Web ACL / ACM 证书的读取权限。八、小结aws cloudfront list-distribution-tenants-by-customization是以自定义配置为索引的多租户查询利器一条命令即可完成“哪些租户使用了该 Web ACL / 证书”的反向检索。配合本文梳理的请求参数表、DistributionTenantSummary响应字段语义、Marker/NextMarker/MaxItems分页机制以及三类错误码的排查思路你可以高效完成多租户环境下的安全策略审计、证书生命周期管理与批量租户治理。相关服务模型与分页器定义可进一步在 service-2.json 与 paginators-1.json 中查看其余配套命令示例位于 awscli/examples/cloudfront/。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考