FEATURED · 精选文章

Argo CD 项目角色 Token 创建指南:`argocd proj role create-token` 命令详解与源码解析

发布时间 / 2026/9/14 11:06:04
来源 / 创域科博编辑部
栏目 / 资讯中心
Argo CD 项目角色 Token 创建指南:`argocd proj role create-token` 命令详解与源码解析 Argo CD 项目角色 Token 创建指南argocd proj role create-token命令详解与源码解析【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cdargocd proj role create-token是 Argo CD CLI 中用于为**项目Project角色Role**签发短期或长期 JWT 访问令牌的命令。本文以其命令参考文档docs/user-guide/commands/argocd_proj_role_create-token.md为主体结合 CLI 与服务端源码完整讲解命令语法、全部参数选项、输出字段含义以及 token 从签发、存储到吊销的完整生命周期帮助你在 CI/CD 流水线、脚本和自动化场景中安全地使用项目级访问令牌。命令定位为什么需要项目角色 Token在 Argo CD 的 RBAC 模型中权限以p, sub, res, act, obj, effect策略规则形式存在。除了普通用户外**项目角色Project Role**本身也可以被授予项目内资源的访问策略如projects、applications的 get/list/sync 权限角色还可以绑定来自 SSO/OIDC 的groups声明。当外部系统例如 CI 流水线需要以某个项目角色的身份调用 Argo CD API 时就需要一个可独立签发、可单独吊销、不依赖用户账号的凭据——这就是项目 JWT Token。argocd proj role create-token正是用来签发这种 token 的入口命令它归属于argocd proj role命令组完整命令组见 argocd_proj_role.md。命令语法与位置参数命令的基本形式为argocd proj role create-token PROJECT ROLE-NAME [flags]它接收两个必填位置参数位置参数说明PROJECT目标项目AppProject的名称例如test-projectROLE-NAME该项目下角色的名称例如test-role在源码 cmd/argocd/commands/project_role.go 中命令定义为Use: create-token PROJECT ROLE-NAME执行时若位置参数数量不等于 2CLI 会打印帮助信息并以退出码 1 结束if len(args) ! 2 { c.HelpFunc()(c, args) os.Exit(1) } projName : args[0] roleName : args[1]同时该命令注册了别名token-create即argocd proj role token-create test-project test-role与正式用法等价见 project_role.go。基本用法与输出示例官方文档给出的最简用法如下$ argocd proj role create-token test-project test-role Create token succeeded for proj:test-project:test-role. ID: f316c466-40bd-4cfd-8a8c-1392e92255d4 Issued At: 2023-10-08T15:21:4001:00 Expires At: Never Token: xxx输出包含四部分信息其来源可以在 CLI 源码的打印逻辑中找到project_role.go输出字段含义对应的 JWT ClaimCreate token succeeded for ...成功提示proj:project:role即 token 的 subjectsubIDToken 的唯一标识符jtiJWT IDIssued At签发时间RFC3339 格式iatExpires At过期时间不设置时为NeverexpToken返回的 JWT 令牌本体—CLI 在拿到响应后会解析 JWT 的 payloadjwtgo.ParseMapClaims再通过jwt.IssuedAt(claims)、jwt.Float64Field(claims, exp)、jwt.StringField(claims, jti)提取上述字段用于展示因此即使服务端返回的 token 是无签名解析的原始 JWTCLI 也能正确显示其元信息。Options 详解该命令自身有三个功能性参数定义见 project_role.go加上-h帮助参数参数简写类型默认值说明--expires-in-estring无永不过期Token 的存活时长格式如12h、7d内部会被解析为秒数并下发给服务端--id-istring随机 UUID为 token 指定唯一标识符不指定时由服务端生成随机 UUID--token-only-tboolfalse只输出 token 本身便于在脚本中直接捕获--help-hbool—打印 create-token 命令的帮助信息-e, --expires-in控制令牌有效期这是安全实践中最常用的参数。CLI 在解析时有如下细节project_role.goif expiresIn { expiresIn 0s } duration, err : timeutil.ParseDuration(expiresIn) errors.CheckError(err) tokenResponse, err : projIf.CreateToken(ctx, projectpkg.ProjectTokenCreateRequest{ Project: projName, Role: roleName, ExpiresIn: int64(duration.Seconds()), Id: tokenID, })未指定--expires-in时命令默认按0s处理即永不过期指定的时长会先经ParseDuration校验非法格式直接报错退出再转换为秒数写入 gRPC 请求。对应的expiresIn字段在 server/project/project.proto 中被明确注释为expiresIn represents a duration in seconds。常用示例# 签发 12 小时后过期的 token $ argocd proj role create-token test-project test-role --expires-in 12h # 签发 7 天后过期的 token $ argocd proj role create-token test-project test-role -e 7d-i, --id指定 Token 标识--id用于为 token 指定自定义唯一标识。若留空服务端会调用uuid.NewRandom()生成随机 UUID见下文服务端实现。在批量管理 token 的场景中指定有业务含义的 ID 便于后续在argocd proj role list-tokens/delete-token中定位目标 token。-t, --token-only脚本化输出--token-only会让 CLI 跳过全部美化输出只打印 token 本体一行project_role.goif !outputTokenOnly { fmt.Printf(Create token succeeded for %s.\n, subject) fmt.Printf( ID: %s\n Issued At: %s\n Expires At: %s\n, ...) fmt.Println( Token: tokenResponse.Token) } else { fmt.Println(tokenResponse.Token) }该参数的价值在于脚本直接捕获变量例如# 创建 24 小时有效的 CI 访问令牌 TOKEN$(argocd proj role create-token test-project ci-role --expires-in 24h --token-only) # 之后可将 $TOKEN 用于 argocd 命令或 API 调用 argocd app list --auth-token $TOKEN --server argocd.example.com继承的父命令选项create-token从argocd根命令继承了全部全局选项下表为命令参考文档中的完整列表其中前几个是连接与认证最常使用的选项说明--argocd-context string要使用的 Argo CD 服务端上下文名称--auth-token string认证令牌设置此项或ARGOCD_AUTH_TOKEN环境变量--client-crt string客户端证书文件--client-crt-key string客户端证书私钥文件--config stringArgo CD 配置文件路径默认/home/user/.config/argocd/config--controller-name stringApplication controller 名称当通过 Helm chart 安装且名称标签不同于默认值时设置此项或ARGOCD_APPLICATION_CONTROLLER_NAME默认argocd-application-controller--core为 true 时 CLI 直接与 Kubernetes API 交互而非通过 Argo CD API server--grpc-web启用 gRPC-web 协议当 Argo CD server 位于不支持 HTTP2 的代理之后时有用--grpc-web-root-path string启用 gRPC-web 协议并设置 web 根路径-H, --header strings为所有请求附加额外的 header可重复指定多个也支持逗号分隔--http-retry-max int建立到 Argo CD server 的 HTTP 连接时的最大重试次数--insecure跳过服务端证书与域名校验--kube-context string指定使用的 kube-context--logformat string日志格式json或text默认json--loglevel string日志级别debug、info、warn、error默认info--plaintext禁用 TLS--port-forward通过端口转发连接到随机 argocd-server 端口--port-forward-namespace string端口转发使用的命名空间--prompts-enabled强制启用或禁用交互式提示覆盖本地配置未指定时使用本地配置值默认false--redis-compress string当 application controller 启用了 redis 压缩时启用可选值gzip、none默认gzip--redis-haproxy-name stringRedis HA Proxy 名称默认argocd-redis-ha-haproxy可通过ARGOCD_REDIS_HAPROXY_NAME覆盖--redis-name stringRedis 部署名称默认argocd-redis可通过ARGOCD_REDIS_NAME覆盖--repo-server-name stringRepo server 名称默认argocd-repo-server可通过ARGOCD_REPO_SERVER_NAME覆盖--server stringArgo CD server 地址--server-crt string服务端证书文件--server-name stringArgo CD API server 名称默认argocd-server可通过ARGOCD_SERVER_NAME覆盖其中与本次操作强相关的连接参数组合示例# 通过端口转发创建 token适用于本地调试 $ argocd proj role create-token test-project test-role --port-forward # 指定服务端地址并跳过 TLS 校验 $ argocd proj role create-token test-project test-role --server argocd.example.com --insecure # 使用已有的管理员令牌完成签发 $ ARGOCD_AUTH_TOKENxxxx argocd proj role create-token test-project test-role服务端实现原理token 是如何签发与存储的CLI 通过 gRPC 调用ProjectService.CreateToken请求结构为ProjectTokenCreateRequest{project, role, expiresIn(秒), id}响应为ProjectTokenResponse{token}定义见 project.proto。服务端处理逻辑位于 server/project/project.go 的createToken方法其关键步骤依次为加载并校验项目从集群中 Get 对应名称的AppProject资源并执行validateProject校验加锁防并发通过s.projectLock.Lock(q.Project)对同一项目的 token 写入串行化避免并发更新导致的状态覆盖确认角色存在调用prj.GetRoleByName(q.Role)角色不存在时返回 gRPCNotFound错误project x does not have role yRBAC 鉴权调用s.enf.EnforceErr校验当前调用者是否有projects资源的update权限若调用者不是项目管理员只要其用户声明claims命中了该角色绑定的groups同样被允许签发校验并生成 Token ID通过prj.ValidateJWTTokenID(q.Role, q.Id)校验 ID 唯一性未指定时生成随机 UUID签发 JWT以proj:project:role为 subject即JWTTokenSubFormat调用s.sessionMgr.Create(subject, q.ExpiresIn, id)生成签名 JWT记录元数据将{IssuedAt, ExpiresAt, ID}三元组追加写入prj.Status.JWTTokensByRole[q.Role]并调用prj.NormalizeJWTTokens()清理过期条目持久化与事件将更新后的 AppProject 写回集群Update并记录created token事件。从该流程可以看出项目 token 的元数据签发时间、过期时间、ID是作为 AppProject 资源status的一部分落库保存的而 token 本体是标准的签名 JWT。这意味着即使不依赖任何外部数据库Argo CD 也能在argocd proj role get、list-tokens时还原全部 token 列表并在鉴权时校验jti是否仍有效。JWT token 元数据在类型定义 pkg/apis/application/v1alpha1/app_project_types.go 中以JWTTokensByRole按角色分组的JWTToken{IssuedAt, ExpiresAt, ID}列表形式存在NormalizeJWTTokens()负责在读写时剔除已过期的 token 记录。配套命令token 的查看与吊销创建 token 只是生命周期的一环完整的项目角色 token 管理还包括查看角色及 token 列表argocd proj role get PROJECT ROLE-NAME输出角色绑定的策略Policies和全部 JWT tokenID、签发时间、过期时间列出某角色的 tokenargocd proj role list-tokens PROJECT ROLE-NAME表格化输出ID / ISSUED AT / EXPIRES AT支持--unixtime输出时间戳便于管道处理吊销 tokenargocd proj role delete-token PROJECT ROLE-NAME ISSUED-AT其中ISSUED-AT取自list-tokens/get输出的签发时间详见 argocd_proj_role_delete-token.md。三者协同的典型流程参考 delete-token 命令源码中的完整示例# 1. 创建项目与角色 $ argocd proj create test-project $ argocd proj role create test-project test-role # 2. 为角色签发 token $ argocd proj role create-token test-project test-role # 3. 查看该角色的全部 token记录 ISSUED-AT 以便吊销 $ argocd proj role get test-project test-role # 4. 吊销指定 token以签发时间为标识 $ argocd proj role delete-token test-project test-role 1696769937实战建议与注意事项优先使用短期 tokenCI 凭据泄露是常见安全事故建议始终通过--expires-in设置存活时长如1h、12h仅在明确需要时签发永不过期的 token脚本中务必使用--token-only它保证输出只有一行 token可直接赋值给环境变量或文件避免解析额外文本按角色最小化授权为不同流水线创建独立角色并只绑定所需策略如仅applications, gettoken 失窃时只影响该角色的权限范围定期审计与吊销结合argocd proj role list-tokens巡检存量 token对可疑或废弃的 token 用argocd proj role delete-token及时吊销token 不会再次完整展示签发时服务端只返回 token 本体一次后续查询仅能得到 ID 与时间信息请将 token 安全保存如 secret 管理工具认证方式执行签发操作本身需要管理员或该角色组成员身份可通过--auth-token、ARGOCD_AUTH_TOKEN环境变量或argocd login建立的本地会话完成认证。通过本文你可以完整掌握argocd proj role create-token的语法、参数、输出与底层实现并能在 CI 流水线中安全地签发、使用和回收项目角色访问令牌。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
RELATED — 相关阅读

相关资讯

LATEST — 最新资讯

最新发布

TODAY — 本日精选

新闻

WEEKLY — 本周精选

新闻

MONTHLY — 本月精选

新闻