AWS CLI CodeArtifact 实战:使用 get-domain-permissions-policy 读取与审查域级资源策略
AWS CLI CodeArtifact 实战:使用 get-domain-permissions-policy 读取与审查域级资源策略
导读
本文围绕 AWS CLI 的 aws codeartifact get-domain-permissions-policy 命令,完整讲解如何读取 CodeArtifact 域(Domain)上挂载的资源策略(Resource Policy),包括命令用法、返回结构解析、与 put/delete 配套命令的联动,以及底层 API 与模型定义。读完本文,你将掌握在命令行中审计 CodeArtifact 域权限配置的完整方法,并能结合 AWS CLI 官方示例文件与 botocore 服务模型进行验证与排障。
命令概览:get-domain-permissions-policy 解决什么问题
在 AWS CodeArtifact 中,域(Domain) 是包仓库(Repository)的逻辑容器,用于管理组织内的包命名空间与共享配置。域的访问控制通过**资源策略(Resource Policy)**实现——这是一份基于资源的 IAM 策略(resource-based policy,而非 identity-based policy),直接附加在域资源上,控制哪些主体(Principal)可以对域及其下的仓库执行哪些操作。
get-domain-permissions-policy 的作用就是读取当前附加在指定域上的这份策略文档。它本身不修改任何配置,是审计、验证和排障时的核心只读命令。
该命令的官方示例位于 awscli/examples/codeartifact/get-domain-permissions-policy.rst,与其配套的写操作示例见 put-domain-permissions-policy.rst 与 delete-domain-permissions-policy.rst,三者构成域策略「读—写—删」的完整操作闭环。
基本用法与参数说明
最小调用形式
读取名为 test-domain 的域的策略,只需提供域名:
aws codeartifact get-domain-permissions-policy \
--domain test-domain
完整参数列表
根据 botocore 服务模型 awscli/botocore/data/codeartifact/2018-09-22/service-2.json 中 GetDomainPermissionsPolicyRequest 的定义,该命令支持两个参数:
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
--domain |
是 | string | 要读取资源策略的域名称 |
--domain-owner |
否 | string | 拥有该域的 AWS 账户 12 位账号 ID(不含连字符或空格)。当你的凭证所属账户并非域所有者时(例如跨账户共享域),需要显式指定 |
模型中对 domainOwner 的文档描述为「拥有该域的 AWS 账户的 12 位数字账号」,位于请求结构体中是可选的 querystring 参数。只有当域属于其他账户时才需要传入,否则 AWS CLI 默认使用当前凭证对应的账户。
底层 HTTP 请求
从模型 GetDomainPermissionsPolicy 操作的 http 定义可以看到,该命令底层发起的是对 CodeArtifact 服务端点的 GET /v1/domain/permissions/policy 请求,domain 与 domain-owner 均作为查询字符串参数传递。也就是说,这个命令是纯读取操作,不会产生任何副作用。
解析返回的域策略文档
官方示例输出
按照 get-domain-permissions-policy.rst 中的示例,对 test-domain 执行读取命令后,返回内容是一个标准的 IAM 策略 JSON:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BasicDomainPolicy",
"Action": [
"codeartifact:GetDomainPermissionsPolicy",
"codeartifact:ListRepositoriesInDomain",
"codeartifact:GetAuthorizationToken",
"codeartifact:CreateRepository"
],
"Effect": "Allow",
"Resource": "*",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
}
}
]
}
策略逐字段解读
这是一个典型的「域基础策略」(BasicDomainPolicy),各字段含义如下:
Version:策略语法版本,2012-10-17是 IAM 策略的现行通用版本。Sid:语句标识符,用于在同一策略中区分多个 Statement,便于审计与排障。Action:允许执行的具体 CodeArtifact 操作。本例中授权了四类操作:codeartifact:GetDomainPermissionsPolicy:读取域策略(即本文命令对应的 API 权限);codeartifact:ListRepositoriesInDomain:列出域内所有仓库;codeartifact:GetAuthorizationToken:获取访问仓库所需的临时授权令牌;codeartifact:CreateRepository:在域中创建新仓库。
Effect:Allow,表示对列出的操作放行。Resource:*,表示策略作用于该域下的所有资源(域本身及其仓库)。Principal:被授权的主体。arn:aws:iam::111122223333:root表示整个111122223333账户的所有 IAM 用户与角色都继承了该域的基础访问权限。
需要特别指出的是,从服务模型 GetDomainPermissionsPolicyResult 的定义看,API 返回结构实际包含的是 policy 字段(类型为 ResourcePolicy),其中 document 字段才是上述 JSON 策略文本。AWSCLI 在文本输出时会将其展开为人类可读的 JSON 格式。ResourcePolicy 结构还包含两个重要元数据字段:
resourceArn:策略所关联资源的 ARN,形如arn:aws:codeartifact:region-id:111122223333:domain/test-domain;revision:策略的当前修订版本号(哈希字符串),用于并发控制与乐观锁。
配合 jq 提取关键信息
当策略较长时,可直接用 --query 或管道到 jq 提取指定字段:
aws codeartifact get-domain-permissions-policy \
--domain test-domain \
--query "policy.document" --output text
域策略的完整生命周期:读、写、删
写入策略(put-domain-permissions-policy)
域策略不会凭空存在,通常先用 put-domain-permissions-policy 写入。官方示例 put-domain-permissions-policy.rst 展示了从本地文件加载策略:
aws codeartifact put-domain-permissions-policy \
--domain test-domain \
--policy-document file://PATH/TO/policy.json
返回值结构为:
{
"policy": {
"resourceArn": "arn:aws:codeartifact:region-id:111122223333:domain/test-domain",
"document": "{ ...policy document content...}",
"revision": "MQlyyTQRASRU3HB58gBtSDHXG7Q3hvxxxxxxx="
}
}
从服务模型 PutDomainPermissionsPolicyRequest 看,写入操作除必填的 domain 与 policyDocument 外,还支持可选参数 policyRevision——用于乐观锁(optimistic locking),即要求你提供的修订号与当前策略修订号一致时才允许覆盖,防止多人并发操作互相覆盖。因此,先 get-domain-permissions-policy 拿到当前 revision,再带上该 revision 执行更新,是安全的更新流程。
删除策略(delete-domain-permissions-policy)
官方示例 delete-domain-permissions-policy.rst 展示了删除操作:
aws codeartifact delete-domain-permissions-policy \
--domain test-domain
删除接口同样支持可选的 --policy-revision 参数(模型 DeleteDomainPermissionsPolicyRequest 中定义为 querystring 参数),同样用于乐观锁控制。删除后域将退回默认的权限状态——仅域所有者可访问。
三命令组合的运维场景
一个典型的域策略维护流程如下:
- 读取现状:
get-domain-permissions-policy --domain test-domain,记录当前revision与document; - 修改策略:基于读取到的
document调整 JSON 内容,保存为policy.json; - 带修订号写入:
put-domain-permissions-policy --domain test-domain --policy-document file://policy.json --policy-revision <上一步获取的revision>; - 验证:再次执行
get-domain-permissions-policy确认策略已生效; - (可选)回退:需要移除策略时执行
delete-domain-permissions-policy。
权限模型与底层源码佐证
读取域策略需要什么权限
读取域策略本身需要调用方具备 codeartifact:GetDomainPermissionsPolicy 权限(这恰好也是基础域策略中默认授予的 Action 之一,形成自举:有策略读取权限才能读取策略)。此外,如果域策略限制了对域内仓库的访问,那么后续取令牌、列仓库等操作还需对应的 codeartifact:GetAuthorizationToken、codeartifact:ListRepositoriesInDomain 等权限。
授权令牌与域策略的关系
域策略中频繁出现的 codeartifact:GetAuthorizationToken 是 CodeArtifact 访问模型的关键:客户端工具(npm、pip、twine、nuget、swift 等)访问仓库时,都需要通过 aws codeartifact login 或直接调用 get-authorization-token 获取 12 小时有效的临时令牌。
在 awscli/customizations/codeartifact/login.py 中,CodeArtifactLogin._get_authorization_token 方法(约 L849-L862)展示了该调用的实现:它基于 domain 与可选的 domainOwner、durationSeconds 参数调用 codeartifact_client.get_authorization_token,并将返回的 authorizationToken 与 expiration 透传给各类包管理工具的登录适配器(NpmLogin、PipLogin、TwineLogin、NuGetLogin 等,见 TOOL_MAP 定义)。这意味着:
- 域策略控制的是「谁能获取访问该域下仓库的令牌」;
login命令拿到令牌后,负责把令牌写入.npmrc、.pypirc、NuGet.Config、.netrc等客户端配置文件。
从模型源码验证命令行为
所有上述参数、返回结构、HTTP 方法与权限语义,均可直接在 service-2.json 的以下定义中交叉验证:
GetDomainPermissionsPolicy:GET /v1/domain/permissions/policy;PutDomainPermissionsPolicy:PUT /v1/domain/permissions/policy;DeleteDomainPermissionsPolicy:DELETE /v1/domain/permissions/policy;GetAuthorizationToken:POST /v1/authorization-token;ResourcePolicy:包含resourceArn、revision、document三个字段。
可以看到,三个策略操作共用一个路径 /v1/domain/permissions/policy,通过 HTTP 方法(GET/PUT/DELETE)区分语义,这也是 REST 风格的典型设计。
常见问题与排障建议
- 返回
ResourceNotFoundException:说明该域上尚未设置策略。先用put-domain-permissions-policy写入,或确认域名拼写无误。 - 跨账户读取失败:如果域属于其他账户,必须补充
--domain-owner参数指定所有者账户 ID,并确保当前凭证具备跨账户访问权限。 - 更新策略被拒绝(revision 冲突):说明策略已被他人修改。重新执行
get-domain-permissions-policy获取最新revision后再重试写入。 - 想验证客户端登录链路:可运行
aws codeartifact login --tool npm --domain test-domain --repository my-repo(--dry-run可预览将要写入的配置而不实际修改),结合域策略中是否包含codeartifact:GetAuthorizationToken判断问题是否出在策略层。
小结
get-domain-permissions-policy 是 CodeArtifact 域权限治理的入口命令:它负责把域上挂载的资源策略原样读出来,供你审计、存档或作为更新前置步骤。结合 put-domain-permissions-policy(含 policy-revision 乐观锁)与 delete-domain-permissions-policy,即可在 AWS CLI 中完成域策略的完整生命周期管理。所有参数与返回结构的权威依据都沉淀在 service-2.json 服务模型中,示例可随时参考 awscli/examples/codeartifact/ 目录下的同名文档。