企业官网建设流程全解析

Argo CDargocd gpg list命令详解：查询已配置的 GPG 公钥

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

argocd gpg list是 Argo CD CLI 中用于列出服务器上已配置 GPG 公钥的子命令，属于argocd gpg命令族（用于"管理签名验证所用的 GPG 密钥"）。本文以该命令的官方参考文档为主体，结合仓库内 CLI 与服务端源码、测试用例，讲解其语法、输出格式、底层调用链，以及它在 Argo CD Git 提交签名验证工作流中的实际定位与使用注意事项。读完本文，你将能熟练使用该命令完成密钥清单查询，并理解其返回字段的语义与来源。

命令概览

argocd gpg list用于列出 Argo CD 服务器上已配置的全部 GPG 公钥。所谓"已配置"，指的是已导入 Argo CD GnuPG 密钥环（keyring）并被信任的公钥——这些公钥随后会被用于校验 Git 仓库中的提交签名。

该命令是argocd gpg命令族（父命令，见 argocd gpg）的四个子命令之一，与 argocd gpg add（导入公钥）、argocd gpg get（按 KeyID 查询单把公钥）、argocd gpg rm（删除公钥）共同构成密钥环管理的完整闭环。

argocd gpg list [flags]

使用示例

原文档提供了三种典型的调用方式，分别对应默认表格输出、JSON 输出与 YAML 输出：

# 以 wide 格式（默认）列出所有已配置的 GPG 公钥。 argocd gpg list # 以 JSON 格式列出所有已配置的 GPG 公钥。 argocd gpg list -o json # 以 YAML 格式列出所有已配置的 GPG 公钥。 argocd gpg list -o yaml

三种输出方式覆盖了从"人眼快速浏览"到"脚本/工具消费结构化数据"的全部场景：表格适合日常巡检，JSON/YAML 适合与jq、yq等工具链结合做自动化处理。

输出格式详解

wide 表格格式（默认）

不带-o参数时，命令通过tabwriter输出一张对齐的表格，表头固定为三列：

对应的实现位于 cmd/argocd/commands/gpg.go 的printKeyTable函数：

func printKeyTable(keys []appsv1.GnuPGPublicKey) { w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0) fmt.Fprint(w, "KEYID\tTYPE\tIDENTITY\n") for _, k := range keys { fmt.Fprintf(w, "%s\t%s\t%s\n", k.KeyID, strings.ToUpper(k.SubType), k.Owner) } _ = w.Flush() }

SubType字段在输出前会被strings.ToUpper统一转为大写（如rsa4096显示为RSA4096），该行为在 cmd/argocd/commands/gpg_test.go 的Test_printKeyTable_*系列测试中有明确断言（assert.Equal(t, "RSA4096", row[1]) // subtype upper-cased）。测试同时覆盖了空列表（仅输出表头）与多密钥场景。

JSON / YAML 格式

指定-o json或-o yaml时，命令对GnuPGPublicKeyList.Items调用PrintResourceList进行序列化输出。与表格格式不同，结构化输出会携带密钥对象的完整字段。GnuPGPublicKey的类型定义位于 pkg/apis/application/v1alpha1/repository_types.go：

// GnuPGPublicKey is a representation of a GnuPG public key type GnuPGPublicKey struct { // KeyID specifies the key ID, in hexadecimal string format KeyID string `json:"keyID" protobuf:"bytes,1,opt,name=keyID"` // Fingerprint is the fingerprint of the key Fingerprint string `json:"fingerprint,omitempty" protobuf:"bytes,2,opt,name=fingerprint"` // Owner holds the owner identification, e.g. a name and e-mail address Owner string `json:"owner,omitempty" protobuf:"bytes,3,opt,name=owner"` // Trust holds the level of trust assigned to this key Trust string `json:"trust,omitempty" protobuf:"bytes,4,opt,name=trust"` // SubType holds the key's subtype (e.g. rsa4096) SubType string `json:"subType,omitempty" protobuf:"bytes,5,opt,name=subType"` // KeyData holds the raw key data, in base64 encoded format KeyData string `json:"keyData,omitempty" protobuf:"bytes,6,opt,name=keyData"` }

各字段语义：

• keyID：密钥 ID，十六进制字符串（即公钥 Key ID）。
• fingerprint：密钥的完整指纹。
• owner：密钥所有者标识（如姓名与邮箱）。
• trust：分配给该密钥的信任级别（unknown/never/marginal/full/ultimate，对应常量定义见 util/sourceintegrity/gpg.go）。
• subType：密钥子类型（如rsa4096）。
• keyData：原始密钥数据（base64 编码）。

需要注意：argocd gpg list的列表响应中keyData字段会被服务端主动置空——这是服务端为节省响应体积而做的裁剪（详见下文"底层调用链"一节）。若需要查看密钥的完整数据，请改用argocd gpg get KEYID。

非法输出格式的处理

CLI 实现中对-o参数做了白名单校验（见 cmd/argocd/commands/gpg.go）：

switch output { case "yaml", "json": err := PrintResourceList(keys.Items, output, false) errors.CheckError(err) case "wide", "": printKeyTable(keys.Items) default: errors.CheckError(fmt.Errorf("unknown output format: %s", output)) }

传入json|yaml|wide之外的取值会直接报错unknown output format: <value>并以非零状态退出，这有助于在 CI 脚本中尽早发现拼写错误。

参数详解

list 子命令专属选项

该选项在源码中通过command.Flags().StringVarP(&output, "output", "o", "wide", "Output format. One of: json|yaml|wide")注册，默认值wide与文档描述一致。

从父命令继承的全局选项

argocd gpg list完整继承自argocd根命令及argocd gpg父命令的全局参数。下面按用途分类说明：

连接与认证相关

组件名称覆盖（Helm Chart 安装时）

当组件通过 Helm Chart 部署且名称标签与默认值不同时，可通过以下选项或对应环境变量覆盖：

其他

此外，argocd gpg父命令还提供 kubeconfig 相关选项（--cluster、--context、--kubeconfig、-n/--namespace、--user）、认证选项（--username、--password、--token）、网络选项（--proxy-url、--request-timeout、--insecure-skip-tls-verify），完整清单见 argocd gpg。

底层调用链：从 CLI 到服务器

argocd gpg list的执行路径清晰地体现了 Argo CD 客户端/服务器（Client-Server）架构：

1. 建立 gRPC 连接：CLI 通过headless.NewClientOrDie(clientOpts, c).NewGPGKeyClientOrDieWithContext(ctx)创建到 API 服务器的 GPGKey 服务客户端，详见 cmd/argocd/commands/gpg.go。
2. 发起 List 请求：客户端调用gpgIf.List(ctx, &gpgkeypkg.GnuPGPublicKeyQuery{})，请求类型GnuPGPublicKeyQuery定义于 pkg/apiclient/gpgkey/gpgkey.pb.go，其中KeyID字段留空即表示"列出全部密钥"。
3. 服务端响应：服务端实现位于 server/gpgkey/gpgkey.go：

// List a list of GnuPG public keys in the configuration func (s *Server) List(ctx context.Context, _ *gpgkeypkg.GnuPGPublicKeyQuery) (*appsv1.GnuPGPublicKeyList, error) { if err := s.enf.EnforceErr(ctx.Value("claims"), rbac.ResourceGPGKeys, rbac.ActionGet, ""); err != nil { return nil, err } keys, err := s.db.ListConfiguredGPGPublicKeys(ctx) if err != nil { return nil, err } keyList := &appsv1.GnuPGPublicKeyList{} for _, v := range keys { // Remove key's data from list result to save some bytes v.KeyData = "" keyList.Items = append(keyList.Items, *v) } return keyList, nil }

从上述实现可以看到两个关键事实：

• RBAC 鉴权：每次list都要求调用方具备gpgkeys资源上的get权限。该命令的 RBAC 资源名称为gpgkeys，动作（action）为get。要在自定义角色role:myrole上放开该权限，需在 RBAC policy CSV 中配置p, role:myrole, gpgkeys, get, *, allow（详见 source-integrity-git-gpg.md 的"Keyring RBAC rules"一节）。
• 列表响应精简：服务端在返回列表前将每把密钥的KeyData（原始密钥数据）置空，以节省响应体积；因此list输出中不包含完整密钥内容，查看完整密钥请使用argocd gpg get KEYID。

4. 本地渲染：CLI 根据-o参数选择printKeyTable或PrintResourceList渲染输出。

值得一提的是，argocd gpg get服务端实现会先通过 util/sourceintegrity/gpg.go 的KeyID()工具函数对参数做合法性校验——支持 16 位短 Key ID 与 40 位长 Key ID（完整指纹），非法值会返回'<value>' is not a valid GnuPG key ID错误。

与argocd gpg其他子命令配合使用

argocd gpg list通常与命令族的其他成员配合完成密钥生命周期管理：

1. 导入密钥：argocd gpg add --from /path/to/keyfile，支持二进制或 ASCII-armored 格式的公钥文件（见 argocd gpg add）。导入时若密钥已存在，服务端会跳过重复项，CLI 会输出Created N key(s) from input file, and M key(s) were skipped because they exist already.之类的汇总信息。
2. 查询单个密钥：argocd gpg get KEYID，输出该密钥的 Key ID、指纹、子类型、所有者及完整密钥数据（见 argocd gpg get）。
3. 列出全部密钥：argocd gpg list，本文主角，用于整体巡检与核对。
4. 删除密钥：argocd gpg rm KEYID，删除前会有Are you sure you want to remove '<KEYID>'? [y/n]的交互确认（见 argocd gpg rm）。

典型巡检示例——用 JSON 输出配合jq只提取 KeyID 列表：

argocd gpg list -o json | jq -r '.items[].keyID'

在签名验证工作流中的定位

Argo CD 使用 GnuPG 校验 Git 仓库提交签名：只有使用密钥环中受信任公钥签名的提交，才会被允许同步。argocd gpg list的价值在于对"服务器信任了哪些公钥"提供全局可见性，是排查"提交已签名却无法同步"类问题的第一步。

需要特别注意的是版本与配置形态的演进（依据 source-integrity-git-gpg.md 与 gpg-verification.md）：

• 旧版（自 Argo CD v1.7 起）通过 AppProject 的.spec.signatureKeys配置项目级签名密钥约束；
• 新版（自 Argo CD 3.5 起）支持通过.spec.sourceIntegrity.git.policies配置更灵活的"源码完整性（Source Integrity）"策略，其中gpg.mode支持none、head、strict三档验证强度；
• 官方已声明旧的 GPG 签名验证机制将被废弃并在下一个大版本移除（见 gpg-verification.md 的告警），signatureKeys与sourceIntegrity不能同时使用；
• 无论采用哪种策略形态，受信任公钥本身都统一维护在 Argo CD 的 GnuPG 密钥环中，argocd gpg list查询的正是这一密钥环。

因此，使用argocd gpg list时请结合自身版本确认其服务对象（旧式signatureKeys或新式sourceIntegrity），并在条件允许时规划向 Source Integrity Verification 迁移。

使用注意事项

• 密钥传播延迟：导入新密钥后，密钥在集群内的传播可能需要一些时间，即使argocd gpg list已显示该密钥"已配置"，签名提交仍可能暂时无法同步。若持续无法同步，参见 source-integrity-git-gpg.md 的故障排查章节。
• 密钥环的实际载体：密钥环由argocd-repo-server的 Pod 维护，并与argocd-gpg-keys-cmConfigMap（以密钥 ID 为 key、ASCII-armored 密钥数据为 value）保持同步；Pod 内的密钥环是瞬态的，重启时会从配置重建，切勿在 Pod 内手工增删密钥。
• 权限要求：执行list需要gpgkeys资源的get权限（RBAC 规则形如p, role:myrole, gpgkeys, get, *, allow）；无权限时服务端会返回鉴权错误。
• 功能开关：可通过将ARGOCD_GPG_ENABLED=false环境变量设置到argocd-server、argocd-repo-server、argocd-application-controller、argocd-applicationset-controller的 Pod 模板来整体禁用 GnuPG 功能，禁用后相关命令将不再可用。
• 信任模型：Argo CD 采用极简信任模型——密钥一旦导入即被信任，不支持 Web of Trust 等复杂信任链，也无需（也不可能）对导入的公钥进行签名（见 source-integrity-git-gpg.md）。

关联文档与源码索引

• 命令参考（本文主体）：docs/user-guide/commands/argocd_gpg_list.md
• 父命令与兄弟命令：argocd gpg、argocd gpg add、argocd gpg get、argocd gpg rm
• CLI 实现与测试：cmd/argocd/commands/gpg.go、cmd/argocd/commands/gpg_test.go
• 服务端实现：server/gpgkey/gpgkey.go
• API 类型定义：pkg/apis/application/v1alpha1/repository_types.go、pkg/apiclient/gpgkey/gpgkey.pb.go
• KeyID 校验与信任级别常量：util/sourceintegrity/gpg.go
• 签名验证功能上下文：source-integrity-git-gpg.md、source-integrity.md、gpg-verification.md

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd