Argo CD 私有仓库接入全指南凭据配置、证书信任与 Helm/OCI 仓库管理【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本文围绕 Argo CDKubernetes 的声明式持续部署工具中私有 Git 仓库的接入与认证展开系统讲解 HTTPS/SSH 凭据、GitHub App、Google Cloud Source、Azure 工作负载身份等主流认证方式以及自签名 TLS 证书、SSH known hosts、凭据模板、Helm/OCI 私有仓库和 Git 子模块等进阶主题。读完本文你将能够为私有仓库场景配置正确的认证方式、解决x509 未知证书颁发机构与unknown SSH host等常见报错并掌握 CLI、Web UI 与声明式Secret/ConfigMap三种配置入口的完整用法。前置须知GitLab 等平台的.git后缀重定向问题在开始配置任何凭据之前先留意一个容易踩坑的细节部分 Git 托管平台尤其是 GitLab以及自托管的 on-premise GitLab 实例要求仓库 URL 必须携带.git后缀否则它们会返回一个指向带.git后缀 URL的 HTTP 301 重定向。Argo CD 不会跟随这类 301 重定向因此如果你添加仓库时省略了.git连接测试会失败。解决办法很简单把仓库 URL 显式写成带.git后缀的形式例如https://gitlab.example.com/group/project.git。凭据Credentials配置总览如果应用清单存放在私有仓库中就必须为 Argo CD 配置仓库凭据。Argo CD 同时支持 HTTPS 与 SSH 两类 Git 凭据覆盖了主流的认证协议。无论使用哪种方式凭据最终都会以 Kubernetes Secret 的形式存储在 Argo CD 的命名空间中由 repo-server 组件在拉取清单时使用。HTTPS 用户名与密码凭据需要用户名和密码认证的私有仓库其 URL 通常以https://开头而非git或ssh://。凭据可以通过 CLI 或 Web UI 两种方式配置。方式一CLI 配置argocd repo add https://github.com/argoproj/argocd-example-apps --username username --password password方式二Web UI 配置导航到Settings/Repositories进入仓库管理页面点击Connect Repo using HTTPS按钮填写仓库 URL 与用户名/密码点击ConnectArgo CD 会先测试连接测试通过后仓库即被添加。使用 Access Token访问令牌除了用户名和密码更推荐使用各托管平台颁发的访问令牌Access Token。请按照你的 Git 托管服务的说明生成令牌GitHubPersonal Access TokenGitLabDeploy Tokens项目级部署令牌Bitbucket ServerPersonal Access TokensAzure ReposPersonal Access Tokens生成令牌后使用任意非空字符串作为用户名将访问令牌值作为密码来连接仓库。这里有几个平台特例需要记住某些服务要求用户名填写你的账户名而不是任意字符串Bitbucket Cloud 与 Bitbucket Data Center 必须将用户名指定为x-token-auth。提示argocd repo add命令在 CLI 层面对参数做了严格校验。从 cmd/argocd/commands/repo.go 的源码可以看到--ssh-private-key-path只允许用于 SSH 仓库、--gcp-service-account-key-path只允许用于 HTTPS 仓库、--tls-client-cert-path与--tls-client-cert-key-path必须成对出现否则命令会直接报错终止避免把无效的凭据组合写入集群。HTTPS 仓库的 TLS 客户端证书如果你的仓库服务器要求使用 TLS 客户端证书mutual TLS进行认证可以为argocd repo add命令添加两个开关分别指定本地文件中存放的客户端证书与其对应的私钥argocd repo add https://repo.example.com/repo.git --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key注意事项--tls-client-cert-path与--tls-client-cert-key-path必须始终一起指定源码中对此有显式校验如果仓库服务器同时要求用户名/密码可与--username、--password开关组合使用证书与私钥数据必须是PEM 格式不支持 PKCS12 等其他格式私钥不能设置密码保护否则 Argo CD 无法使用在 Web UI 中添加 HTTPS 仓库时同样可以粘贴 TLS 客户端证书与私钥但粘贴时务必避免产生多余换行或额外字符。从存储层面看这些证书内容会以tlsClientCertData、tlsClientCertKeyData等键写入仓库 Secret可参考 util/db/repository_secrets.go 中的读写逻辑。SSH 私钥凭据需要 SSH 私钥认证的私有仓库其 URL 通常以git或ssh://开头而非https://。CLI 方式argocd repo add gitgithub.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsaUI 方式导航到Settings/Repositories点击Connect Repo using SSH输入 URL 并粘贴 SSH 私钥点击Connect测试连接并完成添加。两个易错点粘贴私钥时Web UI 文本框中不能有多余换行或额外字符否则私钥解析会失败非标准端口如果 SSH 服务运行在非标准端口必须使用ssh://风格的 URL 来指定端口。scp 风格gityourgit.com:yourrepo的 URL不支持指定端口任何端口号都会被当作仓库路径的一部分。版本兼容提示Argo CD 2.4 起升级到 OpenSSH 8.9而 OpenSSH 8.8 已经移除了对ssh-rsaSHA-1 密钥签名算法的支持。如果你的 SSH 服务器仍依赖旧算法请参考升级指南中关于 SSH 服务器兼容性测试与绕过方案的说明。GitHub App 凭据托管在 GitHub.com 或 GitHub Enterprise 上的私有仓库可以使用 GitHub Application 的凭据访问。请先在 GitHub 上创建应用并确保应用至少拥有仓库Contents的Read-only权限这是最低要求。CLI 方式argocd repo add https://github.com/argoproj/argocd-example-apps.git --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem如果是 GitHub Enterprise 的私有仓库需要额外添加--github-app-enterprise-base-url https://ghe.example.com/api/v3标志--github-app-installation-id标志是可选的。省略时Argo CD 会根据仓库所属组织自动发现 installation ID。UI 方式导航到Settings/Repositories点击Connect Repo using GitHub App选择类型GitHub或GitHub Enterprise输入 URL、App Id、Installation Id可选以及应用的私钥选择GitHub Enterprise类型时还需填写 GitHub Enterprise Base URL点击Connect测试连接。提示在 UI 中粘贴 GitHub App 私钥时同样要确保没有意外换行或多余字符。CLI 命令的完整参数清单可参见 cmd/argocd/commands/repo.go 中的示例githubAppID 等字段会以githubAppID键持久化到仓库 Secret见 util/db/repository_secrets.go。Google Cloud Source托管在 Google Cloud Source 上的私有仓库可以使用 JSON 格式的 Google Cloud 服务账号密钥访问。请先在 Google Cloud 中创建服务账号并确保其至少拥有该 Google Cloud 项目的Source Repository Reader权限最低要求。CLI 方式argocd repo add https://source.developers.google.com/p/my-google-cloud-project/r/my-repo --gcp-service-account-key-path service-account-key.jsonUI 方式导航到Settings/Repositories点击Connect Repo using Google Cloud Source输入 URL 与 JSON 格式的服务账号密钥点击Connect测试连接。Azure Container Registry / Azure ReposAzure Workload IdentityArgo CD 支持使用 Azure Workload Identity 访问 Azure Container RegistryACR与 Azure Repos 中的私有仓库。使用前需要完成以下准备工作为 Pod 打标签给 repo-server 的 Pod 添加azure.workload.identity/use: true标签创建联合身份凭据Federated Identity Credential为 repo-server 的服务账号生成 Azure 联合身份凭据为服务账号添加注解在 repo-server 服务账号上添加azure.workload.identity/client-id: $CLIENT_ID注解CLIENT_ID来自工作负载身份配置 ACR 权限为工作负载身份授予 Azure Container Registry 或 Azure Repos 所需的权限设置 ACR Token 资源变量将 Argo CD repo-server 的环境变量AZURE_ARM_TOKEN_RESOURCE设置为https://containerregistry.azure.netArgo CD 才能请求有效的 ACR 访问令牌。源码佐证该环境变量在 util/helm/creds.go 中被读取env.StringFromEnv(AZURE_ARM_TOKEN_RESOURCE, ...)默认值为https://management.core.windows.net因此对接 ACR 时必须显式覆盖为https://containerregistry.azure.net。CLI 方式Helm OCI 仓库argocd repo add contoso.azurecr.io/charts --type helm --enable-oci --use-azure-workload-identityCLI 方式Azure Reposargocd repo add https://contosodev.azure.com/my-projectcollection/my-project/_git/my-repo --use-azure-workload-identityUI 方式导航到Settings/Repositories点击 Connect Repo在连接页面选择连接方式为VIA HTTPS类型选择git或helm输入仓库 URL如果类型是 helm还需输入 name并在需要时勾选Enable OCI勾选Use Azure Workload Identity点击Connect。Secret 定义方式也可以在仓库 Secret 中通过useAzureWorkloadIdentity: true开启该字段在 util/db/repository_secrets.go 中通过boolOrFalse解析并有对应测试用例验证见 util/db/repository_secrets_test.goapiVersion: v1 kind: Secret metadata: name: helm-private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: type: helm url: contoso.azurecr.io/charts name: contosocharts enableOCI: true useAzureWorkloadIdentity: true --- apiVersion: v1 kind: Secret metadata: name: git-private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: type: git url: https://contosodev.azure.com/my-projectcollection/my-project/_git/my-repo useAzureWorkloadIdentity: trueAzure DevOpsService Principal 服务主体Azure DevOps 仓库也可以使用服务主体Service Principal的凭据访问。请先按照微软官方文档创建服务主体并配置其对 Azure DevOps 的访问权限并确保服务主体至少拥有包含仓库的Project的Project Readers权限最低要求。CLI 方式argocd repo add https://dev.azure.com/my-devops-organization/my-devops-project/_git/my-devops-repo --azure-service-principal-tenant-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-secret test如果使用的是非公有云例如德国云等还需要添加--azure-active-directory-endpoint https://login.microsoftonline.de标志。UI 方式导航到Settings/Repositories点击Connect Repo选择连接方式Via Azure Service Principal输入 URL、Tenant Id、Client Id、Client Secret以及非默认公有云时的 Active Directory Endpoint点击Connect测试连接。凭据模板Credential Templates如果多个仓库共享同一套凭据不必为每个仓库重复配置。Argo CD 支持凭据模板为某个 URL 前缀设置凭据后所有以该前缀开头的仓库且未配置自己的凭据都会自动套用。例如为 URL 前缀https://github.com/argoproj设置凭据模板后https://github.com/argoproj/argocd-example-apps等仓库都会自动使用这套凭据。Web UI 方式在Connect repo using SSH或Connect repo using HTTPS对话框中填写凭据信息但不要点击Connect而是选择Save as credential template。注意Repository URL字段只填前缀 URL如https://github.com/argoproj不要填完整仓库 URL。CLI 方式使用repocreds子命令管理凭据模板# 为 URL 前缀 https://github.com/argoproj 添加用户名/密码模板 argocd repocreds add https://github.com/argoproj --username youruser --password yourpass # 列出与删除凭据模板 argocd repocreds list argocd repocreds rm url-prefix凭据模板要生效必须同时满足两个条件目标仓库要么完全未配置要么已配置但不含任何凭据信息凭据模板的 URL 必须是仓库 URL 的前缀。配套说明与注意事项只有在匹配的仓库凭据模板配置好之后才可以通过 CLI 或 Web UI 在不指定凭据的情况下添加需要认证的仓库前缀匹配遵循best match最长匹配优先原则最长的匹配前缀优先级最高定义的先后顺序不影响结果这与 v1.4 之前的行为不同。下面是一个完整的 CLI 演示会话展示了凭据模板的典型用法# 尝试添加私有仓库但不提供凭据 —— 失败 $ argocd repo add https://docker-build/repos/argocd-example-apps FATA[0000] rpc error: code Unknown desc authentication required # 为 https://docker-build/repos 下的所有仓库建立凭据模板 $ argocd repocreds add https://docker-build/repos --username test --password test repository credentials for https://docker-build/repos added # 再次添加仓库不指定凭据URL 前缀命中模板 —— 成功 $ argocd repo add https://docker-build/repos/argocd-example-apps repository https://docker-build/repos/argocd-example-apps added # 添加同一前缀下的另一个仓库但显式指定了错误凭据 —— 失败自带凭据不再使用模板 $ argocd repo add https://docker-build/repos/example-apps-part-two --username test --password invalid FATA[0000] rpc error: code Unknown desc authentication required从实现上看repo-server 在解析仓库凭据时会先从凭据模板中继承相关字段包括UseAzureWorkloadIdentity等再合并仓库自身配置相关逻辑可见 reposerver/repository/repository.go。自签名与不受信任的 TLS 证书如果目标 HTTPS 仓库服务器使用的是自签名证书或由 Argo CD 不认识的私有 CA 签发出于安全考虑仓库将无法添加典型报错为x509: certificate signed by unknown authority。此时有两种处理方案跳过服务器证书校验使用--insecure-skip-server-verification标志添加仓库。⚠️ 这会使连接暴露于中间人攻击风险仅建议用于非生产环境导入自定义 CA 证书使用argocd cert add-tls命令将服务器证书或其签名 CA 的证书PEM 格式导入 Argo CD。这是推荐的生产级做法。三个重要的补充说明对于无效的服务器证书如服务器名不匹配、证书已过期添加 CA 证书无效唯一办法是使用--insecure-skip-server-verification标志因此强烈建议让仓库服务器使用有效证书TLS 证书是按服务器per-server配置的而非按仓库配置。同一台服务器下的多个仓库证书只需配置一次argocd cert命令的变更传播到整个集群可能需要几分钟具体取决于你的 Kubernetes 环境。使用 CLI 管理 TLS 证书列出已配置的 HTTPS 证书$ argocd cert list --cert-type https HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT docker-build https rsa CNArgoCD Test CA localhost https rsa CNlocalhost以不安全方式添加 HTTPS 仓库不推荐用于生产argocd repo add --insecure-skip-server-verification https://git.example.com/test-repo导入 CA 证书并正常添加仓库推荐argocd cert add-tls git.example.com --from ~/myca-cert.pem argocd repo add https://git.example.com/test-repo同时配置新旧两份证书证书轮换场景可以一次为同一服务器添加多个 PEM将多个 PEM 拼接后输入。如果服务器即将更换证书可能由不同的 CA 签发可以同时保留旧证书与新证书若旧证书已配置使用--upsert标志一次性写入新旧两份cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert提示要替换服务器已有的证书必须给cert add-tls命令加--upsert标志。删除 TLS 证书argocd cert rm --cert-type https localhost使用 Web UI 管理 TLS 证书点击左侧导航栏的Settings在设置菜单中选择Certificates该页面会列出所有已配置的证书并提供添加 TLS 证书或 SSH known hosts 条目的入口点击Add TLS certificate填写数据后点击Create。注意只填写仓库服务器的 FQDN不要写完整 URL并将完整的 PEM 证书包括----BEGIN CERTIFICATE----与----END CERTIFICATE----行完整粘贴到文本框中删除证书时点击证书条目旁的三点按钮选择Remove并在确认对话框中确认。使用声明式配置管理 TLS 证书在自管理declarative的 Argo CD 部署中所有 TLS 证书存放在 ConfigMap 对象argocd-tls-certs-cm中。更多细节可参考操作手册-声明式配置中关于使用自签名 TLS 证书或由自定义 CA 签名的仓库一节。未知 SSH 主机Unknown SSH Hosts如果通过 SSH 访问私有托管的 Git 服务同样有两种方案跳过主机密钥校验使用--insecure-skip-server-verification标志添加仓库。⚠️ 同样仅建议用于非生产环境存在中间人攻击风险导入服务器的 SSH 公钥使用argocd cert add-ssh命令将服务器公钥known_hosts格式导入 Argo CD。这是推荐的生产级做法。可以通过ssh-keyscan工具获取服务器的公钥。注意argocd cert命令的变更传播需要几分钟。另外从known_hosts文件导入时其中的主机名或 IP 地址不能是哈希过的。如果known_hosts文件包含哈希条目|1|...形式则无法作为 CLI 或 UI 的输入源若坚持使用哈希数据只能走声明式配置但这会破坏 CLI 与 UI 的证书管理功能通常不推荐。使用 CLI 管理 SSH Known Hosts列出已配置的 SSH known host 条目$ argocd cert list --cert-type ssh HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT bitbucket.org ssh ssh-rsa SHA256:46OSHA1Rmj8E8ERTC6xkNcmGOw9oFxYr0WF6zWW8l1E github.com ssh ssh-rsa SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s gitlab.com ssh ecdsa-sha2-nistp256 SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw gitlab.com ssh ssh-ed25519 SHA256:eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8 gitlab.com ssh ssh-rsa SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ ssh.dev.azure.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og vs-ssh.visualstudio.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og添加 SSH known host 条目使用argocd cert add-ssh命令可以从文件添加--from file也可以在指定--batch后从stdin读取两种方式输入都必须是 OpenSSH 客户端可识别的known_hosts格式。用ssh-keyscan收集服务器全部公钥并导入ssh-keyscan server.example.com | argocd cert add-ssh --batch直接导入现有known_hosts文件argocd cert add-ssh --batch --from /etc/ssh/ssh_known_hosts删除 SSH known host 条目argocd cert rm bitbucket.org --cert-type ssh如果同一主机存在多种密钥子类型如上例中 gitlab.com 同时有ssh-rsa、ssh-ed25519、ecdsa-sha2-nistp256三种只想删除其中一种时可以用--cert-sub-type进一步缩小范围argocd cert rm gitlab.com --cert-type ssh --cert-sub-type ssh-ed25519使用 Web UI 管理 SSH Known Hosts点击左侧导航栏的Settings选择Certificates在证书管理页面点击Add SSH known hosts将 SSH known hosts 数据粘贴到输入框中。注意粘贴时条目的 key 数据不能有换行然后点击Create删除条目时点击条目旁的三点按钮选择Remove并确认。使用声明式配置管理 SSH Known Hosts在自管理declarative的 Argo CD 部署中所有 SSH 公钥存放在 ConfigMap 对象argocd-ssh-known-hosts-cm中相关写入逻辑可参考 util/settings/settings.go。更多细节请参考操作手册-声明式配置中的SSH Known Host Public Keys一节。受保护的 Helm 仓库与 OCI 私有仓库Helm chart 可以来自受保护的 Helm 仓库或 OCI 私有注册中心。配置方法与普通 Git 仓库类似只需将仓库类型指定为helm针对 HTTPS 仓库。CLI 方式为argocd repo add指定--type标志argocd repo add https://argoproj.github.io/argo-helm --typehelm additional-flagsUI 方式导航到Settings/Repositories点击Connect Repo连接方式选择VIA HTTPS类型Type选择helm点击Connect测试连接。受保护的 OCI 注册中心Helm chart 存放在 OCI 注册中心时需显式声明来源是 OCI 中的 Helm chart。使用 CLI 时指定--enable-oci标志argocd repo add registry-1.docker.io/bitnamicharts --typehelm --enable-ocitrue additional-flags注意引用 OCI 注册中心时应省略oci://协议前缀直接写注册中心地址。UI 方式则是在添加基于 HTTPS 的helm仓库时勾选Enable OCI复选框。需要说明的是在 Secret 定义中enableOCI: true与useAzureWorkloadIdentity: true等布尔字段均有对应的字符串解析逻辑可参考 util/db/repository_secrets.go 中的boolOrFalse实现。自定义 HTTP User-Agent部分 Helm 仓库提供商如 Wikimedia的机器人访问策略要求特定的 User-Agent 请求头。默认情况下Argo CD 会对所有 Helm 仓库请求自动发送argocd-repo-server/version (platform)格式的 User-Agent。如需自定义 User-Agent例如加入组织名或联系方式可在argocd-repo-serverDeployment 上设置ARGOCD_HELM_USER_AGENT环境变量apiVersion: apps/v1 kind: Deployment metadata: name: argocd-repo-server spec: template: spec: containers: - name: argocd-repo-server env: - name: ARGOCD_HELM_USER_AGENT value: my-org/argocd (teamexample.com)该环境变量对所有Helm 仓库请求全局生效。Git 子模块SubmodulesArgo CD 原生支持 Git 子模块且会自动检测并拉取。需要留意的是如果子模块仓库需要认证其凭据必须与父仓库的凭据一致可通过设置环境变量ARGOCD_GIT_MODULES_ENABLEDfalse关闭子模块支持。该环境变量的名称在 common/common.go 中以EnvGitSubmoduleEnabled ARGOCD_GIT_MODULES_ENABLED定义对应 repo-server 的开关。声明式配置入口以上所有仓库与凭据配置在 Argo CD 的自管理declarative部署模式下都可以通过 Kubernetes 原生对象声明仓库与凭据模板使用带argocd.argoproj.io/secret-type: repository标签的 SecretTLS 证书存放在argocd-tls-certs-cmConfigMapSSH known hosts 存放在argocd-ssh-known-hosts-cmConfigMap。完整的字段清单与示例请参考操作手册-声明式配置中的 Repositories 一节这也是 GitOps 模式下将仓库凭据纳入版本管理、实现完全声明化运维的推荐做法。output_article_end【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考