AWS CLI 实战:使用 get-repository-permissions-policy 读取 CodeArtifact 仓库资源策略
AWS CLI 实战:使用 get-repository-permissions-policy 读取 CodeArtifact 仓库资源策略
导读
本文围绕 AWS CLI 的 codeartifact get-repository-permissions-policy 命令展开,讲解如何读取 CodeArtifact 域下某个仓库当前生效的资源策略(Resource Policy),并基于命令返回结果理解策略文档的结构与语义。读完本文,你将掌握该命令的完整用法、输出字段含义、常见错误处理方式,并能结合配套的 put-repository-permissions-policy 与 delete-repository-permissions-policy 命令完成仓库策略的"查看—设置—删除"全生命周期管理。
命令概述:读取仓库策略的入口
CodeArtifact 是 AWS 提供的托管制品仓库服务,兼容 npm、Maven、pip、NuGet 等主流包管理器。在 CodeArtifact 中,域(Domain) 是逻辑组织单元,仓库(Repository) 存放实际的包版本,而权限控制则通过附加在域、仓库或包上的资源策略实现。
get-repository-permissions-policy 命令的作用正是返回附加在指定仓库上的资源策略文档。在 service-2.json 的 API 定义中,该操作对应 HTTP GET /v1/repository/permissions/policy,官方文档描述为"Returns the resource policy that is set on a repository"。
该命令要求至少提供两个参数,从请求模型的 required 字段可见(service-2.json):
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
--domain |
String | 是 | 包含目标仓库的域名称 |
--domain-owner |
String | 否 | 拥有该域的 12 位 AWS 账号 ID(不含连字符或空格)。仅当域不属于当前账号时需要显式指定 |
--repository |
String | 是 | 要读取策略的仓库名称 |
三个参数在底层都以 querystring 形式传递(domain、domain-owner、repository),这意味着该操作是一个纯读取性质的 GET 请求,不会对仓库状态产生任何副作用。
基本用法与完整示例
以下是官方示例文档 get-repository-permissions-policy.rst 提供的标准调用方式——读取名为 test-repo 的仓库策略:
aws codeartifact get-repository-permissions-policy \
--domain test-domain \
--repository test-repo
执行成功后的返回结果(示例输出):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": [
"codeartifact:DescribePackageVersion",
"codeartifact:DescribeRepository",
"codeartifact:GetPackageVersionReadme",
"codeartifact:GetRepositoryEndpoint",
"codeartifact:ListPackages",
"codeartifact:ListPackageVersions",
"codeartifact:ListPackageVersionAssets",
"codeartifact:ListPackageVersionDependencies",
"codeartifact:ReadFromRepository"
],
"Resource": "*"
}
]
}
注意:命令实际返回的结构是 {"policy": {...}} 包装对象(详见下文"返回值结构"),示例输出直接展示了 policy.document 字段中的策略文档内容,即标准的 AWS IAM 策略 JSON,其核心要素包括:
- Version:策略语法版本,示例中使用
2012-10-17,这也是目前 IAM 策略的标准版本; - Statement:策略语句列表,每条语句描述一组权限规则;
- Effect:效果为
Allow(允许)或Deny(拒绝); - Principal:被授权主体,示例为
arn:aws:iam::111122223333:root,表示授权给指定 AWS 账号的根用户; - Action:允许执行的 CodeArtifact 操作列表,示例策略覆盖了描述、列出、读取包版本资产等只读类操作;
- Resource:策略作用的资源范围,示例为
*,表示仓库内全部资源。
从策略内容可以看出,这是一个典型的"只读访问"仓库策略:它允许指定账号读取包版本描述、仓库描述、包 README、仓库端点、包列表、包版本列表及资产等,但不包含 PutPackageMetadata、UpdatePackageVersionsStatus 等写操作权限。
返回值结构:policy 包装对象
根据 API 响应模型 GetRepositoryPermissionsPolicyResult(service-2.json),该命令返回 policy 字段,其类型为 ResourcePolicy。ResourcePolicy 结构(service-2.json)包含三个成员:
| 字段 | 说明 |
|---|---|
resourceArn |
与该资源策略关联的资源 ARN,形如 arn:aws:codeartifact:region-id:111122223333:repository/test-domain/test-repo |
revision |
资源策略的当前修订版本号,形如 MQlyyTQRASRU3HB58gBtSDHXG7Q3hvxxxxxxx=,用于乐观并发控制(见下文) |
document |
以 JSON 字符串形式存放的完整策略文档 |
也就是说,如果需要以编程方式解析策略内容,应当先读取 policy.document 字段并将其反序列化为 JSON 后再解析,而不是直接把整个命令输出当作策略文档。
关联命令:设置与删除策略
要理解读取命令的价值,不妨将它与同目录下的配套命令对照使用:
put-repository-permissions-policy:为仓库附加策略,见 put-repository-permissions-policy.rst。例如:
aws codeartifact put-repository-permissions-policy \
--domain test-domain \
--repository test-repo \
--policy-document file://PATH/TO/policy.json
其输出中的 policy.revision 字段(如 MQlyyTQRASRU3HB58gBtSDHXG7Q3hvxxxxxxx=)即为策略版本标识;再次调用 get-repository-permissions-policy 时,返回的 revision 可用于确认策略是否被他人修改过。
delete-repository-permissions-policy:删除仓库策略,见 delete-repository-permissions-policy.rst:
aws codeartifact delete-repository-permissions-policy \
--domain test-domain \
--repository test-repo
删除成功后若再次执行 get 命令,且仓库没有其他策略时,通常会收到 ResourceNotFoundException。
对照阅读:域级策略
仓库策略之外,CodeArtifact 还支持域级策略。可参考 get-domain-permissions-policy.rst 中的 get-domain-permissions-policy 命令,其用法类似,但只需指定 --domain:
aws codeartifact get-domain-permissions-policy \
--domain test-domain
示例输出展示了一个典型的域基础策略(Sid 为 BasicDomainPolicy),允许账号根用户执行 GetDomainPermissionsPolicy、ListRepositoriesInDomain、GetAuthorizationToken、CreateRepository 等域级操作。域策略与仓库策略是两层独立的授权模型,实际权限判定时二者叠加生效,理解这一层级关系有助于排查权限问题。
深入源码:底层调用链与模型约束
API 定义与请求序列化
从 service-2.json 可以看到该操作的完整服务端契约:
- HTTP 方法:
GET,请求路径:/v1/repository/permissions/policy; - 请求模型要求
domain与repository必填; - 错误类型包括:
AccessDeniedException(权限不足)、InternalServerException(服务端内部错误)、ResourceNotFoundException(资源不存在)、ThrottlingException(请求限流)、ValidationException(参数校验失败)。
这些定义由 botocore 的模型加载机制解析,最终驱动 AWS CLI 生成对应的命令行参数、参数校验与请求签名,是理解命令行为与错误输出的底层依据。
参数约束
仓库与域名称在服务端模型中存在长度约束(如 DomainName、RepositoryName 均带 min/max 限制),命令行传入的超长名称会由 botocore 在序列化阶段校验并抛出 ParamValidationError。这意味着参数校验在请求发出前即已完成,遇到校验错误时无需怀疑网络或服务端问题。
常见错误与排查建议
| 场景 | 预期错误 | 排查方向 |
|---|---|---|
| 域或仓库名称拼写错误、资源不存在 | ResourceNotFoundException |
先用 list-domains、list-repositories 核对名称 |
发起调用的 IAM 身份缺少 codeartifact:GetRepositoryPermissionsPolicy 权限 |
AccessDeniedException |
检查调用者 IAM 策略是否包含对应 Action |
| 请求频率过高触发限流 | ThrottlingException |
结合 AWS CLI 重试机制,适当降低调用频率 |
| 参数类型或长度不合法 | ValidationException(服务端)或 ParamValidationError(本地校验) |
检查参数拼写、名称长度与格式 |
小结
aws codeartifact get-repository-permissions-policy --domain <domain> --repository <repo>用于读取仓库资源策略;- 返回的
policy.document是策略 JSON 文本,policy.revision用于并发控制与变更追踪; - 与
put-repository-permissions-policy、delete-repository-permissions-policy组合即可完成仓库策略的完整生命周期管理; - 底层契约定义在 service-2.json,所有参数、错误与返回结构均以该模型为准。
更多仓库策略操作示例见 awscli/examples/codeartifact 目录下的 put-repository-permissions-policy.rst、delete-repository-permissions-policy.rst 与 get-domain-permissions-policy.rst,可对照学习完整的 CodeArtifact 权限管理实践。