Argo CDargocd repocreds完全指南用凭据模板Credential Templates统一管理私有仓库认证【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cdargocd repocreds是 Argo CD CLI 中用于管理仓库凭据模板repository credential templates的命令族它允许你为某个 URL 前缀一次性配置认证信息使同一 Git 服务器或 Helm OCI 仓库下的所有子仓库自动复用该凭据无需逐个添加仓库。读完本文你将掌握argocd repocreds add / list / rm三个子命令的全部参数与用法理解凭据前缀匹配与最长匹配优先规则并能借助源码级别的说明快速定位 CLI 实现与数据结构直接用于生产环境的私有仓库接入配置。什么是仓库凭据模板在 Argo CD 中Application 的spec.source.repoURL通常指向具体仓库如https://github.com/argoproj/argocd-example-apps。传统做法是用 argocd repo 命令逐仓库配置认证。而当你在同一台 Git 服务器或同一组织下有大量仓库时逐条配置显然低效。凭据模板credential templates正是为此设计你只需为一个URL 前缀配置一套凭据Argo CD 会自动将这套凭据应用于所有以该前缀开头的仓库。官方文档 private-repositories.md 中给出了明确的使用条件目标仓库没有配置自己的独立凭据时才会使用凭据模板凭据模板的 URL如https://github.com/argoproj必须作为仓库 URL 的前缀匹配如https://github.com/argoproj/argocd-example-apps匹配采用best match最长匹配优先策略即多个模板同时匹配时URL 最长的模板生效与定义顺序无关这与 v1.4 之前的行为不同。CLI 中管理凭据模板的命令族就是repocredsargocd repocreds [flags]其Short描述为 Manage credential templates for repositories实现位于 cmd/argocd/commands/repocreds.go该命令本身不执行任何操作直接打印帮助信息真正的逻辑在add、list、rm三个子命令中。基础用法速览# 为指定 URL 前缀添加 用户名/密码 认证的凭据 argocd repocreds add URL --username USERNAME --password PASSWORD # 列出所有已配置的仓库凭据 argocd repocreds list # 删除指定 URL 前缀的仓库凭据 argocd repocreds rm URL使用示例同样适用于 Web UI 中的 Save as credential template 场景详见 private-repositories.md# 为 https://github.com/argoproj 前缀下所有仓库配置用户名/密码 argocd repocreds add https://github.com/argoproj --username youruser --password yourpass父级repocreds命令的通用选项在argocd repocreds层级可以直接使用以下选项用于控制 CLI 与 Argo CD API Server 的连接方式选项说明--cluster string使用的 kubeconfig cluster 名称--context string使用的 kubeconfig context 名称-h, --help显示帮助--insecure-skip-tls-verify为 true 时不校验服务器证书有效性会使 HTTPS 连接不安全--kubeconfig stringkubeconfig 路径仅集群外运行时需要-n, --namespace stringCLI 请求的命名空间范围--password string访问 API Server 的基础认证密码--proxy-url string通过指定代理 URL 连接--request-timeout string单个服务器请求超时时间非零值需带时间单位如1s、2m、3h零表示不超时默认0--token stringAPI Server 认证的 Bearer token--user stringkubeconfig 用户名称--username stringAPI Server 基础认证用户名argocd repocreds add添加凭据模板这是最核心的子命令用于为仓库配置连接参数Add git repository connection parametersargocd repocreds add REPOURL [flags]REPOURL是唯一的位置参数对应RepoCreds.URL字段即凭据要匹配的 URL 前缀。CLI 在 cmd/argocd/commands/repocreds.go#L102-L108 处校验参数个数必须为 1并将其写入凭据对象的URL字段。六种认证方式的实战示例1. 用户名/密码HTTPS Basic Auth# 为 https://git.example.com/repos 前缀下所有仓库配置用户名/密码 argocd repocreds add https://git.example.com/repos/ --username git --password secret值得注意的细节在 cmd/argocd/commands/repocreds.go#L171-L175 中如果设置了--username但未通过--password提供密码CLI 会交互式提示输入密码cli.PromptPassword方便安全场景下避免密码出现在命令行历史中。2. Bearer Token如 BitBucket Data Center# 为所有 BitBucket Data Center 仓库配置 bearer token 认证 argocd repocreds add https://bitbucket.example.com/scm/ --bearer-token secret-token提交前 CLI 会执行三项校验repocreds.go#L177-L182--bearer-token与--password不能同时设置bearer token 仅适用于git类型仓库bearer token 仅适用于 HTTPS 仓库 URL。3. SSH 私钥# 为 ssh://gitgit.example.com/repos 前缀下所有仓库配置 SSH 私钥 argocd repocreds add ssh://gitgit.example.com/repos/ --ssh-private-key-path ~/.ssh/id_rsaCLI 会先用git.IsSSHURL判断 URL 是否为 SSH 协议是则读取私钥文件内容存入SSHPrivateKey字段否则直接报错--ssh-private-key-path is only supported for SSH repositories.repocreds.go#L111-L121。4. GitHub App 认证# GitHub.cominstallation-id 可选缺省时由 GitHub API 自动发现 argocd repocreds add https://github.com/repos/ --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem # GitHub Enterprise额外指定 API base URL argocd repocreds add https://ghe.example.com/repos/ --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem --github-app-enterprise-base-url https://ghe.example.com/api/v3GitHub App 私钥路径仅对 HTTPS URL 有效非 HTTPS 时会报错--github-app-private-key-path is only supported for HTTPS repositoriesrepocreds.go#L144-L154。5. Helm OCI 仓库# 让这些 OCI registry 下的仓库无需逐个单独添加 argocd repocreds add localhost:5000/myrepo --enable-oci --type helm注意示例中 OCI 仓库 URL 没有https://前缀配合--enable-oci与--type helm使用。提交前会校验--insecure-oci-force-http仅适用于enable-oci的 helm 类型仓库ValidateInsecureOCIForceHTTPrepocreds.go#L184。6. GCP 与 Azure 云厂商认证# GCP为 Google Cloud Source 下所有仓库配置服务账号 argocd repocreds add https://source.developers.google.com/p/my-google-cloud-project/r/ --gcp-service-account-key-path service-account-key.json # Azure使用 Service Principal 认证Azure 公有云 argocd repocreds add https://dev.azure.com/my-devops-organization --azure-service-principal-client-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-secret test --azure-service-principal-tenant-id 12345678-1234-1234-1234-123456789012 # Azure非公有云环境如德国云时指定 Active Directory 端点 argocd repocreds add https://dev.azure.com/my-devops-organization --azure-service-principal-client-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-secret test --azure-service-principal-tenant-id 12345678-1234-1234-1234-123456789012 --azure-active-directory-endpoint https://login.microsoftonline.deGCP 服务账号 key 同样仅对 HTTPS URL 有效repocreds.go#L156-L166。AzureActiveDirectoryEndpoint为空时默认使用https://login.microsoftonline.com见 repository_types.go 的字段注释。全部可用选项选项说明--azure-active-directory-endpoint string非 Azure 公有云时的 Active Directory 端点如https://login.microsoftonline.de--azure-service-principal-client-id stringAzure Service Principal 的 client id--azure-service-principal-client-secret stringAzure Service Principal 的 client secret--azure-service-principal-tenant-id stringAzure Service Principal 的 tenant id--bearer-token stringGit 仓库的 bearer token--enable-oci是否为此仓库启用 helm-oci 支持--force-http-basic-auth通过 HTTP 连接时是否强制使用 basic auth--gcp-service-account-key-path stringGoogle Cloud Platform 服务账号 key--github-app-enterprise-base-url stringGitHub Enterprise 的 base URL如https://ghe.example.com/api/v3--github-app-id intGitHub Application 的 id--github-app-installation-id intGitHub Application 的 installation id可选缺省时自动发现--github-app-private-key-path stringGitHub Application 的私钥-h, --help显示帮助--insecure-oci-force-http访问 OCI 仓库时使用 http--password string仓库密码--proxy-url string若提供将使用该代理 URL 连接--ssh-private-key-path stringSSH 私钥路径如~/.ssh/id_rsa--tls-client-cert-key-path stringTLS 客户端证书的私钥路径必须为 PEM 格式--tls-client-cert-path stringTLS 客户端证书路径必须为 PEM 格式--type string仓库类型git或helm默认git--upsert即使 spec 不同也覆盖同名已有仓库--use-azure-workload-identity是否使用 Azure Workload Identity 认证--username string仓库用户名关键校验规则源码级add命令在提交前执行一系列防御性校验理解这些规则可以避免踩坑SSH 私钥仅限 SSH URL--ssh-private-key-path只对ssh://开头的 URL 有效否则报错退出repocreds.go#L111-L121TLS 客户端证书必须成对出现--tls-client-cert-path与--tls-client-cert-key-path必须同时指定缺任一都会报错must be specified together且两者仅对 HTTPS URL 有效repocreds.go#L123-L142GitHub App / GCP 私钥仅限 HTTPS URL二者均通过git.IsHTTPSURL校验repocreds.go#L144-L166Bearer token 约束不能与 password 并存、仅限 git 类型、仅限 HTTPS 仓库cmdutil.ValidateBearerTokenAndPasswordCombo/ValidateBearerTokenForGitOnly/ValidateBearerTokenForHTTPSRepoOnlyrepocreds.go#L177-L182。成功添加后 CLI 输出Repository credentials for URL added底层通过 gRPC 调用RepoCredsCreateRequest将凭据写入 Argo CD 后端repocreds.go#L187-L194。argocd repocreds list查看已配置凭据列出所有已配置的仓库凭据List configured repository credentialsargocd repocreds list [flags]# 默认 wide 表格格式输出 argocd repocreds list # JSON 格式 argocd repocreds list -o json # YAML 格式 argocd repocreds list -o yaml # 仅输出 URLurl 格式 argocd repocreds list -o url-o, --output支持的取值json|yaml|wide|url默认wide。实现位于 cmd/argocd/commands/repocreds.go#L279-L319yaml/json调用PrintResourceList打印完整对象url仅逐行输出每个凭据的 URLwide则通过 tabwriter 渲染表格表头为URL PATTERN USERNAME SSH_CREDS TLS_CREDS其中USERNAME为空时显示为-SSH_CREDS、TLS_CREDS为布尔值分别表示该凭据是否配置了 SSH 私钥与 TLS 客户端证书printRepoCredsTable。argocd repocreds rm删除凭据模板删除指定 URL 前缀的仓库凭据Remove repository credentialsargocd repocreds rm CREDSURL [flags]# 删除 URL 为 https://git.example.com/repos 的凭据模板 argocd repocreds rm https://git.example.com/repos/实现要点repocreds.go#L223-L256位置参数不足时会打印帮助并退出支持一次删除多个 URL命令对每个传入的 URL 逐个循环处理每个 URL 都会交互式确认提示Are you sure you want to remove URL? [y/n]确认后才调用DeleteRepositoryCredentials删除否则打印 The command to remove was cancelled.。该确认行为受父命令的--prompts-enabled选项影响通过utils.NewPrompt(clientOpts.PromptsEnabled)创建。删除成功后输出Repository credentials for URL removed。从父命令继承的连接选项add、list、rm三个子命令均继承自argocd根命令的全局选项控制 CLI 与 Argo CD Server / 底层 Kubernetes 的交互方式选项说明--argocd-context string使用的 Argo CD server context 名称--auth-token string认证 token设置此项或环境变量ARGOCD_AUTH_TOKEN--client-crt string客户端证书文件--client-crt-key string客户端证书私钥文件--config stringArgo CD 配置文件路径默认/home/user/.config/argocd/config--controller-name stringApplication controller 名称通过 Helm chart 安装且名称 label 与默认值不同时需设置此项或环境变量ARGOCD_APPLICATION_CONTROLLER_NAME默认argocd-application-controller--core为 true 时 CLI 直接与 Kubernetes 通信而不经过 Argo CD API Server--grpc-web启用 gRPC-web 协议当 Argo CD Server 位于不支持 HTTP2 的代理之后时有用--grpc-web-root-path string启用 gRPC-web 并设置 web root-H, --header strings为所有请求附加额外 header可重复指定也支持逗号分隔多个 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 deployment 名称默认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覆盖在通过 Helm chart 部署、组件名称被修改的集群中正确设置--controller-name、--repo-server-name、--server-name、--redis-name等选项至关重要否则 CLI 可能无法定位后端组件。数据模型与底层原理repocreds命令操作的 CRD 数据类型是RepoCreds完整定义位于 pkg/apis/application/v1alpha1/repository_types.go#L21-L68。其核心字段与 CLI 选项一一对应URL凭据匹配的 URL 前缀必填Username/PasswordHTTPS 基础认证--username/--passwordSSHPrivateKeySSH 私钥内容由--ssh-private-key-path读取文件填充TLSClientCertData/TLSClientCertKeyTLS 客户端证书及其私钥PEM 格式--tls-client-cert-path/--tls-client-cert-key-pathGithubAppPrivateKey/GithubAppId/GithubAppInstallationId/GitHubAppEnterpriseBaseURLGitHub App 认证四件套安装 ID 缺省时自动发现Enterprise base URL 为空时默认https://api.github.comEnableOCI/Type/InsecureOCIForceHttpHelm OCI 仓库支持GCPServiceAccountKeyGCP 服务账号 keyJSON 格式Proxy/ForceHttpBasicAuth/NoProxy代理与强制 basic auth 行为UseAzureWorkloadIdentity/AzureServicePrincipalClientId/AzureServicePrincipalClientSecret/AzureServicePrincipalTenantId/AzureActiveDirectoryEndpointAzure 相关认证AD 端点为空时默认https://login.microsoftonline.comBearerTokenBitBucket Data Center 等场景的 bearer token。从调用链看CLI 通过headless.NewClientOrDie(clientOpts, c).NewRepoCredsClientOrDieWithContext(ctx)建立 gRPC 客户端连接repocreds.go#L168、repocreds.go#L238、repocreds.go#L300分别调用CreateRepositoryCredentials、DeleteRepositoryCredentials、ListRepositoryCredentials三个 API 方法。对应的 gRPC 服务定义与客户端代码位于 pkg/apiclient/repocreds/repocreds.pb.go含 HTTP 网关 repocreds.pb.gw.go。凭据最终由 Argo CD Server 的 repository 服务持久化并在 repo-server 拉取仓库时按 URL 前缀匹配取用。常见问题与最佳实践前缀要写对凭据模板匹配的是 URL前缀因此argocd repocreds add时务必只填前缀 URL如https://github.com/argoproj不要填完整仓库 URL否则其他同级仓库无法复用该凭据最长匹配优先同一仓库 URL 可能命中多个模板Argo CD 采用 best match 策略选择 URL 最长的模板无需担心定义顺序凭据冲突仓库自身配置了凭据时优先使用仓库自身凭据凭据模板仅作为兜底InheritedCreds字段记录凭据是否继承自凭据模板见 repository_types.go敏感信息保护只传--username不传--password时 CLI 会交互式提示输入密码可避免密码落入 shell 历史自动发现 GitHub App 安装 ID--github-app-installation-id可选缺省时 Argo CD 会调用 GitHub API 自动获取简化配置。如需了解更多仓库管理命令可参阅 argocd repo 系列参考文档以及完整的仓库接入说明 private-repositories.md。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考