Argo CD 自定义 TLS 证书 ConfigMap（argocd-tls-certs-cm.yaml）配置指南

Argo CD 自定义 TLS 证书 ConfigMap（argocd-tls-certs-cm.yaml）配置指南

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

本篇技术指南围绕 Argo CD 的argocd-tls-certs-cmConfigMap 展开，说明如何以声明式方式为通过 HTTPS 连接的 Git 仓库配置自定义 TLS 证书（自签名证书或私有 CA 签发的证书），从而让argocd-repo-server能够校验并信任仓库服务器的证书。读完本文，你将掌握该 ConfigMap 的完整 YAML 结构、key/data 映射规则、PEM 证书写入格式、Pod 内的挂载与生效机制，以及与之配套的 CLI、Web UI 管理和常见排错手段，可直接在自己的集群中落地实施。

该 ConfigMap 的用途与适用场景

在 Argo CD 中，argocd-repo-server负责从 Git 仓库拉取清单。当仓库通过 HTTPS 暴露时，客户端（Go 的crypto/tls实现）默认会用系统信任库校验服务器证书。绝大多数公共 Git 服务（GitHub、GitLab、Bitbucket 等）以及使用知名 CA（含 Let's Encrypt）签发的证书都能直接通过校验；但企业内部自建 Git 服务往往使用自签名证书，或使用私有 CA（Custom Certificate Authority）签发的证书，此时默认信任库无法校验服务器，仓库会添加失败，并报出类似x509: certificate signed by unknown authority的错误。

针对这种情况，Argo CD 提供两种思路（详见 docs/user-guide/private-repositories.md）：

1. 跳过校验：在添加仓库时使用--insecure-skip-server-verification标志。这种方式完全不验证服务器证书，容易遭受中间人攻击，官方明确建议仅用于非生产环境。
2. 配置自定义证书：把服务器证书（或其签名 CA 的证书）预先配置进 Argo CD，让它在校验时信任该证书。这是官方推荐、适用于生产环境的做法。

第 2 种方式在声明式（Declarative / GitOps 自管理）安装形态下，就是通过名为argocd-tls-certs-cm的 ConfigMap 实现的，它对应仓库中的示例文件 docs/operator-manual/argocd-tls-certs-cm.yaml。

完整的 argocd-tls-certs-cm.yaml 示例

仓库中的官方示例文件内容如下，一个合法的argocd-tls-certs-cmConfigMap 对象长这样：

apiVersion: v1 kind: ConfigMap metadata: name: argocd-tls-certs-cm namespace: argocd labels: app.kubernetes.io/name: argocd-cm app.kubernetes.io/part-of: argocd data: server.example.com: | -----BEGIN CERTIFICATE----- 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 XWyb96wrUlv+E8I= -----END CERTIFICATE-----

该文件在文档体系中处于承上启下的位置：声明式安装指南 docs/operator-manual/declarative-setup.md 中将其列入核心 ConfigMap 清单（对应表项argocd-tls-certs-cm，类型为 ConfigMap，用途为 "Custom TLS certificates for connecting Git repositories via HTTPS"），而本示例文件本身则由配套页面 docs/operator-manual/argocd-tls-certs-cm-yaml.md 通过 include 方式引用展示。

配置语义详解：key 与 value 的映射规则

以主机名（hostname）作为 key

data部分是一张映射表，key 必须是仓库服务器的主机名部分，而不是完整 URL。例如，当你连接https://server.example.com/repos/my-repo这个仓库时，key 应该写成：

data: server.example.com: | <PEM 证书内容>

这一规则在源码层面同样得到印证：util/db/certificate.go中的getTLSCertificateData()直接以certCM.Data的 key 作为证书的Subject（服务器名），tlsCertificatesToMap()在回写时也是用Subject作为 map 的 key，两者完全对应。

以 PEM 格式证书作为 value

value 是一个或多个 PEM 格式的证书。可以是：

• 服务器自身的证书：适用于自签名证书场景；
• 签发服务器证书的 CA 证书：适用于私有 CA 签发的证书场景。

内容必须包含完整的 PEM 头尾标记，即-----BEGIN CERTIFICATE-----与-----END CERTIFICATE-----以及中间的 Base64 编码正文。

同一服务器可配置多个证书

每个服务器 key 下可以配置多张证书（将多个 PEM 块拼接在同一 value 中）。典型场景是证书轮换（certificate roll-over）：当服务器计划更换证书、且新证书可能由另一个 CA 签发时，可以让旧证书与新证书共存，保证轮换期间连接不被中断。

从源码看，util/cert/cert.go中的ParseTLSCertificatesFromStream()会扫描整个数据流，每遇到一个BEGIN CERTIFICATE与END CERTIFICATE对就切分出一张独立证书，因此同一个 value 里的多张证书都会被解析并纳入信任池；GetCertPoolFromPEMData()则将这些 PEM 证书逐个AppendCertsFromPEM到x509.CertPool，最终用于 TLS 校验。

未配置证书时的默认行为

如果某个仓库服务器没有在argocd-tls-certs-cm中配置专属证书，Argo CD 会回退到系统的默认信任库来校验服务器证书。对于 GitHub、GitLab、Bitbucket 等公共 Git 服务，以及绝大多数使用知名 CA（包括 Let's Encrypt）签发的证书，默认信任库已经足够，通常无需任何额外配置。

挂载与生效机制：/app/config/tls

argocd-tls-certs-cm这个 ConfigMap 会被以卷（volume）的形式挂载到argocd-server与argocd-repo-server两个组件的 Pod 中，挂载路径为/app/config/tls。ConfigMap 中的每个 data key 会对应生成该目录下的一个文件，文件名即 key 本身。以上面的示例为例，最终会在 Pod 内产生文件：

/app/config/tls/server.example.com

该文件内容就是 key 对应的证书数据。

需要特别注意的是：ConfigMap 的变更反映到 Pod 中需要时间。Kubelet 同步 ConfigMap 卷存在一定延迟，具体时长取决于你的 Kubernetes 配置，可能达到数分钟。因此修改证书后应等待传播完成再验证仓库连接。

源码侧的对应逻辑位于util/cert/cert.go：

• GetTLSCertificateDataPath()返回证书数据路径，默认取common.DefaultPathTLSConfig（即/app/config/tls），同时支持通过环境变量ARGOCD_TLS_DATA_PATH覆盖；
• GetCertificateForConnect(serverName)会拼出<数据路径>/<去除端口后的主机名>文件路径，读取并解析其中的 PEM 证书（文件不存在时不视为错误，返回空数据）；
• GetCertBundlePathForRepository(serverName)则供仓库连接流程使用：若该服务器存在有效证书文件，则返回证书 bundle 的完整路径，交由底层 Git/TLS 客户端加载。

这也解释了为什么 key 必须是主机名：它直接决定了证书文件在/app/config/tls下的文件名，而仓库连接时正是按“服务器主机名”去查找对应证书文件的。

结合源码理解证书的管理与校验流程

util/db/certificate.go中定义了数据模型与读写逻辑，理解这些能帮你更准确地使用该 ConfigMap：

• 数据模型：TLSCertificate结构体包含Subject（证书所属服务器名）、Issuer、Data三个字段；ListRepoCertificates()在返回证书列表时，会解析每个 PEM 条目，输出其 X.509Subject（DN 记法）与公钥算法（如rsa、ecdsa），这就是argocd cert list输出中FINGERPRINT/SUBJECT列的数据来源。
• 写入时的校验：CreateRepoCertificate()对 HTTPS 类型的证书会依次做三层校验——主机名合法性（IsValidHostname，支持域名与 IPv6）、PEM 可解析性（至少一个有效 PEM 块）、X.509 可解码性；任一环节失败都会拒绝写入。同一服务器已有证书且未指定upsert时会报错TLS certificate for server '%s' already exists, and upsert was not specified。
• 删除逻辑：RemoveRepoCertificates()支持按主机名模式（HostNamePattern）和证书类型（CertType）选择删除。值得注意的是，删除路径同样会先解析 PEM，如果 ConfigMap 中的数据已损坏、无法解析，则只能通过kubectl直接编辑 ConfigMap 来清理（源码注释中明确指出了这一限制）。
• 主机名匹配：util/cert/cert.go中的MatchHostName()采用文件系统 glob 语义（而非完整正则）进行主机名匹配，因此列表/删除操作中的模式参数支持*、?等通配符。

通过 CLI 与 Web UI 管理 TLS 证书（备选途径）

虽然本文主题是声明式 ConfigMap 配置，但 Argo CD 也提供等价的运行时管理途径，二者操作的是同一份证书数据（CLI/UI 最终也会回写到argocd-tls-certs-cm），了解它们有助于排查与验证。

CLI 方式

列出已配置的 HTTPS 证书：

argocd cert list --cert-type https

输出示例（HOSTNAME / TYPE / SUBTYPE / FINGERPRINT-SUBJECT）：

HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT docker-build https rsa CN=ArgoCD Test CA localhost https rsa CN=localhost

从 PEM 文件添加证书（等价于往 ConfigMap 写入一个 key）：

argocd cert add-tls git.example.com --from ~/myca-cert.pem argocd repo add https://git.example.com/test-repo

添加多张证书（适用于证书轮换），旧证书已存在时需配合--upsert：

cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert

删除证书：

argocd cert rm --cert-type https localhost

两点提醒（来源为 docs/user-guide/private-repositories.md）：

• argocd cert系列命令的变更传播到整个集群同样需要时间（视 Kubernetes 环境而定，最长可达数分钟）；
• 对证书本身无效的情况（如服务器名不匹配、证书已过期），添加 CA 证书也无济于事，此时只能使用--insecure-skip-server-verification连接，官方强烈建议修复服务器证书。

Web UI 方式

在 UI 左侧导航进入 "Settings" → "Certificates" 页面，可以集中查看、添加与删除 TLS 证书和 SSH known hosts 条目。添加 TLS 证书时，只需填写仓库服务器的 FQDN（同样只填主机名而非完整 URL），并将完整 PEM（含BEGIN/END CERTIFICATE行）粘贴到文本域中：

（相关截图位于 docs/assets/cert-management-add-tls.png，同目录下还有证书总览页cert-management-overview.png与删除确认页cert-management-remove.png可供参考。）

常见注意事项与排错

• 错误x509: certificate signed by unknown authority：说明服务器证书不在默认信任库中，需要按上文配置argocd-tls-certs-cm（或使用 CLI/UI 添加）。
• key 一定是主机名，不是 URL：写成https://server.example.com或server.example.com/repos都不会生效，因为证书文件按主机名查找。
• 证书按服务器维度生效：TLS 证书是 per-server（按服务器）配置，而非 per-repository（按仓库）。同一服务器下的多个仓库共享同一份证书配置，配置一次即可。
• PEM 内容必须完整：漏掉BEGIN/END CERTIFICATE标记、截断 Base64 正文，都会导致解析失败；写入 ConfigMap 时数据会经过 PEM 与 X.509 双重校验。
• 注意传播延迟：ConfigMap 卷同步需要时间，改动后不要立即判定未生效，可稍等数分钟后再试。
• 证书轮换期间的平滑过渡：将新旧证书拼接在同一个 value 中（多个 PEM 块），可以让新旧证书并存，避免轮换窗口期的连接失败。
• 声明式与运行时管理的等价性：无论通过 ConfigMap、CLI 还是 UI 配置，底层数据都归一到argocd-tls-certs-cm（TLS）与argocd-ssh-known-hosts-cm（SSH），详见 docs/operator-manual/declarative-setup.md。SSH 场景与 TLS 不同，SSH 公钥必须预配置否则连接直接失败，具体配置方式见同一章节的 "SSH known host public keys" 小节。

小结

argocd-tls-certs-cm是 Argo CD 声明式安装中解决“HTTPS 自签名/私有 CA 仓库连接信任”问题的核心配置载体。掌握它的 key/value 映射规则（主机名 + PEM 证书）、多证书轮换写法、/app/config/tls挂载机制，以及它与 CLI、UI 管理途径的等价关系，你就能在生产环境中稳定接入使用私有证书的 Git 仓库。若需要进一步探索，可直接查阅仓库中的 docs/operator-manual/declarative-setup.md、docs/operator-manual/argocd-tls-certs-cm.yaml，以及底层实现 util/db/certificate.go 与 util/cert/cert.go。

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