AWS CLI CodeArtifact 实战:使用 get-domain-permissions-policy 读取与审查域级资源策略

原创2026-09-15 19:56:131,668 阅读
文章标签:开发工具云原生运维

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 参数),同样用于乐观锁控制。删除后域将退回默认的权限状态——仅域所有者可访问。

三命令组合的运维场景

一个典型的域策略维护流程如下:

  1. 读取现状:get-domain-permissions-policy --domain test-domain,记录当前 revision 与 document;
  2. 修改策略:基于读取到的 document 调整 JSON 内容,保存为 policy.json;
  3. 带修订号写入:put-domain-permissions-policy --domain test-domain --policy-document file://policy.json --policy-revision <上一步获取的revision>;
  4. 验证:再次执行 get-domain-permissions-policy 确认策略已生效;
  5. (可选)回退:需要移除策略时执行 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 风格的典型设计。

常见问题与排障建议

  1. 返回 ResourceNotFoundException:说明该域上尚未设置策略。先用 put-domain-permissions-policy 写入,或确认域名拼写无误。
  2. 跨账户读取失败:如果域属于其他账户,必须补充 --domain-owner 参数指定所有者账户 ID,并确保当前凭证具备跨账户访问权限。
  3. 更新策略被拒绝(revision 冲突):说明策略已被他人修改。重新执行 get-domain-permissions-policy 获取最新 revision 后再重试写入。
  4. 想验证客户端登录链路:可运行 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/ 目录下的同名文档。

登录后查看全文
aws-cli