企业官网建设流程全解析

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-b2bb2f28eabc

2.1 参数说明

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.542000+00:00", "LastModifiedTime": "2025-05-06T16:14:08.710000+00: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.json：

ListDistributionTenantsByCustomizationRequest ├── 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.json：

ListDistributionTenantsByCustomizationResult ├── NextMarker : string # 分页令牌，用于发起下一次请求 └── DistributionTenantList : list of DistributionTenantSummary

列表元素类型为DistributionTenantSummary，其必填字段（required）包括Id、DistributionId、Name、Arn、Domains、CreatedTime、LastModifiedTime和ETag（见 service-2.json），这与完整DistributionTenant结构（见 service-2.json）一脉相承。两个结构的关键字段语义如下：

其中Customizations内部的关键点：WebAcl.Action可取override（覆盖父级配置）或disable（禁用 Web ACL），这在与 list-distribution-tenants 的输出对比中可以看到两种形态——后者示例中某租户即返回"WebAcl": { "Action": "disable" }，表示该租户显式禁用了 Web ACL。

四、分页机制：Marker / NextMarker / MaxItems

与 CloudFront 大部分列表类 API 一致，该命令支持标准的分页游标模式。分页器定义见 paginators-1.json：

"ListDistributionTenantsByCustomization": { "input_token": "Marker", "output_token": "NextMarker", "limit_key": "MaxItems", "result_key": "DistributionTenantList" }

这意味着：

• 请求侧：通过--marker传入上一轮响应中的NextMarker；通过--max-items限制单页条数；
• 响应侧：若结果被截断，响应中会携带NextMarker，将其作为下一次请求的--marker即可继续翻页；若没有更多数据，则无NextMarker；
• AWS CLI 的自动分页：CLI 底层基于该分页器模型自动把result_key（DistributionTenantList）各页拼接为完整列表，因此大多数情况下你无需手动处理分页，直接拿到全部结果。

需要注意的是，NextMarker与NextToken不同：NextToken出现在 list-distribution-tenants 的示例输出中（如eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAzfQ==这类 base64 令牌），而本命令使用NextMarker作为游标字段，两者语义等价但字段名不同，实际使用时以各自命令的输出为准。

五、常见错误与排错指引

服务模型 service-2.json 中为该 API 声明的错误类型只有三种：

实践建议：

1. 先通过 list-distribution-tenants 确认目标租户确实挂载了你打算过滤的 Web ACL 或证书，避免误判；
2. 确认 ARN 的global段与资源 ID：CloudFront 关联的 WAFv2 Web ACL 属于全局区域资源，ARN 中必须包含global；
3. 若要“反向”查询某个租户当前生效的自定义配置，可直接使用 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 ACL；
• list-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