Argo CD ssh_known_hosts 定制：用 Kustomize 注入自定义 SSH 已知主机文件

Argo CD ssh_known_hosts 定制用 Kustomize 注入自定义 SSH 已知主机文件【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cdArgo CD 通过 SSH 协议访问 Git 仓库时默认会校验目标主机指纹Host Key校验依据就是各组件容器内的/etc/ssh/ssh_known_hosts文件。当你的 Git 服务使用非标准端口、私有化部署或尚未收录在默认已知主机列表时就需要自定义该文件。本指南基于仓库中 examples/known-hosts 目录下的完整示例讲解如何用一套 Kustomize 清单为 Argo CD 所有 Deployment 统一注入自定义/etc/ssh/ssh_known_hosts并配套ssh-keyscan获取公钥、ssh-keygen -H哈希化等实操步骤让你能安全地连接自建 Git 仓库而无需全局关闭证书校验。背景为什么 Argo CD 需要自定义 ssh_known_hostsArgo CD 的argocd-repo-server负责拉取 Git 仓库、argocd-server负责 API 与 UI、argocd-application-controller负责应用状态比对三者都可能与 Git 仓库建立连接。使用 SSH URL如gitgit.repo.com:org/repo.git连接仓库时客户端必须校验服务端主机密钥校验数据来自容器内的/etc/ssh/ssh_known_hosts文件。默认安装包已经内置了一份常见 Git 平台的已知主机条目。仓库中的 manifests/base/config/argocd-ssh-known-hosts-cm.yaml 展示了这份默认列表包含github.com、gitlab.com、bitbucket.org、ssh.dev.azure.com、vs-ssh.visualstudio.com以及ssh.github.com:443等多条记录每种主机通常同时列出ecdsa-sha2-nistp256、ssh-ed25519、ssh-rsa多个算法的主机密钥。如果你的 Git 仓库来自这些内置主机之外——例如公司自建 GitLab/Gitea/Gerrit、内网 Git 服务器、或使用非 443 端口的 SSH 服务——默认列表里就没有对应指纹SSH 握手会因主机密钥未知而失败。这时有两种选择在argocd repo add时通过命令行参数临时关闭校验适合测试不推荐生产按本指南的做法用 Kustomize 为所有 Argo CD 组件注入一份包含自建主机指纹的自定义ssh_known_hosts文件以最小改动保留完整的主机密钥校验。注意/etc/ssh/ssh_known_hosts需要同时包含 Git 主机在每个 Argo CD Deploymentrepo-server、server、application-controller以及执行argocd repo add的那台计算机上的记录。README 同时提到在 issue #1514 解决之后实际只有argocd-repo-server一个 Deployment 必须定制但示例仍为三个 Deployment 统一注入以保持一致性和兜底。示例文件结构一览examples/known-hosts 目录共包含 4 个文件文件作用kustomization.yamlKustomize 入口引入 Argo CD 稳定版清单 自定义 ConfigMap并叠加挂载补丁argocd-known-hosts.yaml定义承载自定义known_hosts内容的ConfigMapargocd-known-hosts-mounts.yaml三个 Deployment 的 merge patch注入卷与挂载点README.md用法说明即本文所依据的原始文档这套示例的思路是“官方清单 最小补丁”不重写任何 Deployment而是用 Kustomize 的patches机制在官方稳定版清单之上叠加自定义配置升级 Argo CD 时清单主体由官方stable分支持续提供自定义部分始终独立保留。从默认清单到定制清单三步解析1. 定义承载 known_hosts 内容的 ConfigMapargocd-known-hosts.yaml 定义了一个名为argocd-known-hosts的 ConfigMap--- apiVersion: v1 kind: ConfigMap metadata: name: argocd-known-hosts data: known_hosts: |- known_hosts file content需要替换known_hosts file content为真实的 known_hosts 文件内容。注意 ConfigMap 的 key 是known_hosts而挂载时通过subPath: known_hosts把它映射为容器内的/etc/ssh/ssh_known_hosts文件详见下文。2. 为所有 Deployment 注入挂载点argocd-known-hosts-mounts.yaml 使用 Kubernetes 的 strategic merge patch 语法依次对三个 Deployment 打补丁。以argocd-server为例--- apiVersion: apps/v1 kind: Deployment metadata: name: argocd-server spec: template: spec: containers: - name: argocd-server volumeMounts: - name: known-hosts mountPath: /etc/ssh/ssh_known_hosts subPath: known_hosts volumes: - name: known-hosts configMap: name: argocd-known-hosts同一文件中argocd-repo-server与argocd-application-controller两个 Deployment 的补丁结构完全一致仅替换metadata.name与containers[].name。关键细节volumeMounts.mountPath精确指向/etc/ssh/ssh_known_hosts这是 Argo CD 各组件读取已知主机文件的固定路径subPath: known_hosts将 ConfigMap 中known_hosts这一个 key 单独挂载为文件而不是把整个 ConfigMap 目录挂载进去从而让容器中原有的其他 SSH 配置如私钥挂载不受影响volumes指向名称为argocd-known-hosts的 ConfigMap与第 1 步定义的名字严格对应。3. 用 Kustomize 打包kustomization.yaml 把以上资源串起来apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - github.com/argoproj/argo-cd//manifests/cluster-install?refstable - argocd-known-hosts.yaml patches: - path: argocd-known-hosts-mounts.yamlresources第一行通过 Kustomize 的远程引用语法直接拉取 Argo CD 官方stable分支的 manifests/cluster-install 完整安装清单保证基线始终是最新稳定版resources第二行加入自定义 ConfigMappatches对基线上的 Deployment 应用上一步的挂载补丁。之后执行kubectl apply -k examples/known-hosts或在 CI 中用kustomize build渲染后kubectl apply -f -即可完成部署。自定义端口场景ssh-keyscan 与哈希化known_hosts 文件的每一行由“主机名 密钥类型 密钥数据”组成。对于使用自定义端口非 22的 Git 服务主机名必须写成[主机名]:端口的方括号形式否则指纹无法匹配。README 给出了完整的采集命令ssh-keyscan -p 1234 git.repo.com known_hosts ssh-keygen -Hf known_hosts cat known_hostsssh-keyscan -p 1234 git.repo.com向git.repo.com:1234发起 SSH 连接探测收集该服务端当前公布的公钥并写入known_hosts文件ssh-keygen -Hf known_hosts用-H将文件中的主机名哈希化|1|...格式。哈希化后即使 known_hosts 文件泄露也无法直接还原主机名同时 OpenSSH 客户端依旧能正常匹配校验是 SSH 官方推荐的安全做法cat known_hosts查看处理后的内容将其粘贴到上文 ConfigMap 的known_hostskey 中。对于标准 22 端口的主机ssh-keyscan输出的格式即为git.repo.com ssh-ed25519 AAAA...可直接使用只有在使用自定义端口时才必须带上-p参数并以方括号形式记录。从仓库源码看Argo CD 在 util/cert/cert.go 中实现了对 known_hosts 条目的解析与校验ParseSSHKnownHostsFromData/ParseSSHKnownHostsFromStreamutil/cert/cert.go逐行解析文件内容并通过IsValidSSHKnownHostsEntry过滤掉注释、空行等无效行TokenizeSSHKnownHostsEntryutil/cert/cert.go将每条记录切分为主机名、密钥子类型与密钥数据三段供主机密钥校验使用。因此你写入 ConfigMap 的内容需要是标准 known_hosts 语法包含主机名、密钥类型、base64 密钥三部分注释行与空行会被自动忽略。底层原理Argo CD 如何加载这份文件Argo CD 在代码中把 known_hosts 文件的路径固化为/app/config/ssh/ssh_known_hosts与/etc/ssh/ssh_known_hosts的组合逻辑。相关常量定义在 common/common.goDefaultPathSSHConfig /app/config/sshSSH 配置默认目录DefaultSSHKnownHostsName ssh_known_hosts已知主机文件名环境变量ARGOCD_SSH_DATA_PATHcommon/common.go可覆盖 SSH 数据的存放目录。util/cert/cert.go 中的GetSSHKnownHostsDataPath()会优先读取ARGOCD_SSH_DATA_PATH环境变量未设置时返回默认路径/app/config/ssh/ssh_known_hosts。这正是示例把文件挂载到/etc/ssh/ssh_known_hosts的原因——该路径与 OpenSSH 的标准约定一致Argo CD 组件启动时按此路径读取并加载。在 SSH 握手阶段util/git/client.go 的resolveSSHHostKeyConfig通过skeema/knownhosts库的NewDB(GetSSHKnownHostsDataPath())读取这份文件构造HostKeyCallbackbuildSSHAuth随后把它挂接进 go-git 的 SSH AuthMethod正常模式下主机密钥回调基于 Argo CD 管理的 known_hosts 文件构建而非用户~/.ssh/known_hosts确保校验数据完全由集群内 ConfigMap 控制若在argocd repo add时使用了 insecure 模式如--insecure-skip-server-verification相关开关util/git/client.go 会直接ssh.InsecureIgnoreHostKey()跳过校验——本指南的定制方案正是为了在保留完整校验的前提下替代这种跳过行为校验失败会返回类似 knownhosts: key mismatch 的错误提示主机指纹不匹配。相关测试覆盖在 util/git/client_test.go校验 HostKeyAlgorithms 从 known_hosts 正确填充与 util/cert/cert_test.go解析、校验、切分 known_hosts 数据如需验证自定义文件的格式正确性可参照这些测试的用例组织自己的数据。完整实操从零定制 Argo CD 的 SSH 已知主机前置条件可访问 Git 仓库所在主机的管理权限或至少能执行ssh-keyscan已安装kubectl与 Kustomizekubectl apply -k内置支持目标集群已安装或即将安装 Argo CD本示例会自动拉取stable分支清单。步骤一采集主机指纹以自建 Git 服务器git.repo.com、SSH 端口1234为例ssh-keyscan -p 1234 git.repo.com known_hosts ssh-keygen -Hf known_hosts cat known_hosts输出类似|1|abc123... ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAI... |1|def456... ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...把全部行复制备用。如果服务器返回多个算法如ecdsa-sha2-nistp256、ssh-ed25519、ssh-rsa的密钥建议全部保留以提高与客户端算法的兼容性。步骤二填写 ConfigMap编辑 argocd-known-hosts.yaml把known_hosts file content替换为步骤一采集的内容--- apiVersion: v1 kind: ConfigMap metadata: name: argocd-known-hosts data: known_hosts: |- |1|abc123... ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAI... |1|def456... ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...步骤三部署在仓库根目录执行kubectl apply -k examples/known-hostsKustomize 会依次完成拉取 Argo CD 官方stable清单 → 附加自定义 ConfigMap → 应用三个 Deployment 的挂载补丁 → 提交到集群。应用后建议验证挂载是否生效kubectl exec -n argocd deploy/argocd-repo-server -- cat /etc/ssh/ssh_known_hosts输出应与 ConfigMap 内容一致。步骤四添加仓库在管理机上同样校验在客户端机器上执行argocd repo add前同样要把目标主机指纹加入本地 known_hostsssh-keyscan输出追加到~/.ssh/known_hosts确保 CLI 与集群内组件使用同一套信任数据ssh-keyscan -p 1234 git.repo.com ~/.ssh/known_hosts argocd repo add gitgit.repo.com:org/repo.git --ssh-private-key-path ./id_rsa故障排查出现 knownhosts: key mismatch主机指纹与 known_hosts 记录不一致。重新执行ssh-keyscan并确认端口号、主机名写法正确挂载后文件为空或缺失检查 ConfigMap 名称与补丁中configMap.name是否一致以及subPath: known_hosts是否与 ConfigMap 的 key 拼写相同自定义端口无法匹配确认ssh-keyscan -p指定的端口与仓库 URL 中使用的端口一致且 known_hosts 中主机名以[host]:port形式记录只希望最小化定制如 README 所述issue #1514 之后仅argocd-repo-server必须定制若你的场景中其他组件不会直接访问 Git 仓库可仅保留该 Deployment 的补丁减小改动面。总结通过 examples/known-hosts 提供的这套 Kustomize 示例你可以用“官方清单 两个自定义资源”的组合为 Argo CD 的argocd-server、argocd-repo-server、argocd-application-controller三个组件统一注入自定义/etc/ssh/ssh_known_hosts从而在保留主机密钥校验的前提下安全接入自建 Git 服务或非标准端口仓库。整个方案不修改任何官方 Deployment 定义升级 Argo CD 时只需跟随stable分支基线自定义内容天然与版本解耦值得作为私有化 Git 接入场景的标准做法复用。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考