企业官网建设流程全解析

Argo CD 声明式仓库配置全指南：argocd-repositories.yaml 深度解析

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

Argo CD 作为面向 Kubernetes 的声明式持续交付工具，其核心职责之一是持续从 Git、Helm 与 OCI 仓库中拉取应用清单并同步到目标集群。本文以官方示例文件 docs/operator-manual/argocd-repositories.yaml 为骨架，系统讲解如何通过 Kubernetes Secret 以声明式方式（kubectl apply）注册仓库，覆盖 HTTPS、SSH、Helm、OCI 与 Azure Workload Identity 等全部认证场景，并深入源码剖析底层映射机制，帮助你掌握可复制的仓库接入实战方案。

为什么需要声明式配置仓库

Argo CD 的仓库（Repository）既可以通过argocd repo addCLI 命令或 UI 交互式添加，也可以像 Application、AppProject 一样，通过 Kubernetes 清单以声明式方式管理。后者意味着：

• 仓库配置可以纳入 GitOps 代码库进行版本控制与审计；
• 无需在集群外执行 CLI 命令，kubectl apply即可完成配置；
• 与官方 声明式安装与配置 流程无缝衔接，便于实现集群级基础设施即代码。

在 docs/operator-manual/declarative-setup.md 的"Atomic configuration"（原子配置）速查表中，argocd-repositories.yaml正是用于承载示例仓库连接信息的官方样例文件，与argocd-cm、argocd-repo-creds等配置对象并列。

核心机制：每个仓库就是一个 Secret

Argo CD 将仓库信息存储为 Kubernetes Secret，识别方式完全依赖标签（Label）：

labels: argocd.argoproj.io/secret-type: repository

只要 Secret 携带该标签并位于 Argo CD 所在命名空间（默认argocd），Argo CD 的控制器就会自动识别并加载它。这一机制的底层实现在 util/db/repository_secrets.go 的secretToRepository函数中：控制器读取 Secret 的data字段，将url、username、password、sshPrivateKey、insecure、enableLfs、enableOCI等键逐一映射为Repository结构体字段，布尔型字段通过boolOrFalse解析，整数型字段（如githubAppID）通过intOrZero解析。

对应的Repository数据模型定义在 pkg/apis/application/v1alpha1/repository_types.go，其中Repo字段（对应 Secret 的url键）为必填项，其余字段按认证场景可选。从源码结构看，布尔开关在 Secret 中统一使用字符串"true"/"false"表示。

完整示例文件逐块解读

官方示例 docs/operator-manual/argocd-repositories.yaml 在一个 YAML 文件中用---分隔了 7 个 Secret，覆盖了绝大多数实际接入场景。下面逐块展开。

1. HTTPS 私有 Git 仓库（含高级开关）

apiVersion: v1 kind: Secret metadata: name: my-private-https-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: https://github.com/argoproj/argocd-example-apps password: my-password username: my-username bearerToken: my-token project: my-project insecure: "true" # Ignore validity of server's TLS certificate. Defaults to "false" forceHttpBasicAuth: "true" # Skip auth method negotiation and force usage of HTTP basic auth. Defaults to "false" enableLfs: "true" # Enable git-lfs for this repository. Defaults to "false"

要点说明：

• url：必填，仓库地址。注意部分 Git 托管商（尤其 GitLab 及部分自建实例）要求 URL 带.git后缀，否则会返回 HTTP 301 重定向，而 Argo CD 不会跟随此类重定向（详见 declarative-setup.md 的 Repositories 章节），请确保 URL 与服务器要求的规范形式一致。
• username/password：HTTPS 基本认证的用户名与密码（或 Personal Access Token）。
• bearerToken：Bearer 令牌，主要用于 Bitbucket Data Center 等场景的认证（对应Repository结构中的BearerToken字段，注释明确说明用于 Git BitBucket Data Center 认证）。
• project：可选。将仓库凭据限定到指定项目；省略时作为所有未限定项目仓库的默认凭据。
• insecure: "true"：忽略服务端 TLS 证书有效性校验，默认"false"。对应Repository.Insecure字段。
• forceHttpBasicAuth: "true"：跳过认证方式协商，强制使用 HTTP Basic Auth，默认"false"。适合服务器对认证方式协商不友好的场景。
• enableLfs: "true"：为此仓库启用 git-lfs 支持，默认"false"。从 repository_types.go 的IsLFSEnabled()方法可以看出，该开关直接决定 Argo CD 是否以 LFS 模式克隆仓库。

2. SSH 私有 Git 仓库

apiVersion: v1 kind: Secret metadata: name: my-private-ssh-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: ssh://git@github.com/argoproj/argocd-example-apps sshPrivateKey: | -----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY----- insecure: "true" # Do not perform a host key check for the server. Defaults to "false" enableLfs: "true" # Enable git-lfs for this repository. Defaults to "false"

要点说明：

• sshPrivateKey：SSH 私钥的 PEM 内容，作为多行字符串写入。在secretToRepository中直接映射为SSHPrivateKey字段。
• 这里insecure: "true"的语义与 HTTPS 不同——用于跳过 SSH 主机密钥校验，默认"false"。对应源码中InsecureIgnoreHostKey字段（repository_types.go 注释明确说明该字段已被Insecure取代）。
• 注意：使用 SSH 接入前，仓库服务器的主机公钥必须预先配置到argocd-ssh-known-hosts-cmConfigMap 中，否则连接必然失败（详见下文"SSH 主机公钥"一节）。私钥的创建与加密存储可参考 Kubernetes 官方关于"包含私钥的 Secret"的实践，或使用 Sealed Secrets 等工具。

3. 公开 Helm Chart 仓库

apiVersion: v1 kind: Secret metadata: name: istio-helm-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts name: istio.io project: my-project type: helm

要点说明：

• type: helm：声明仓库类型为 Helm Chart 仓库。Repository.Type字段的注释说明可选值为git、helm（留空默认为git）。
• name：仓库显示名称，仅 Helm 仓库使用（对应Repository.Name字段）。
• 对于公开仓库无需提供凭据；此示例同时演示了project字段将仓库归属到指定项目。
• 结合 declarative-setup.md 的说明，从 Helm 仓库创建 Application 时，spec.source必须使用chart属性而非path属性。

4. 私有 Helm Chart 仓库

apiVersion: v1 kind: Secret metadata: name: private-helm-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: https://my-private-chart-repo.internal name: private-repo type: helm password: my-password username: my-username

私有 Helm 仓库与私有 Git 仓库的认证方式一致，通过username/password提供凭据，同时声明type: helm与name。Argo CD 在拉取 Chart 时会将凭据用于 Helm 仓库的基本认证。

5. 无凭据的公开 Git 仓库

apiVersion: v1 kind: Secret metadata: name: private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: https://github.com/argoproj/private-repo

这是最精简的形式：仅提供url，适用于公开仓库或后续通过凭据模板（repo-creds）补充凭据的场景。注意 Secret 的名称（此处private-repo）是任意的，Argo CD 依靠标签与url而非名称来识别仓库——当然，名称仍需在命名空间内唯一。

6. Azure Container Registry（OCI + Azure Workload Identity）

apiVersion: v1 kind: Secret metadata: name: aci-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"

要点说明：

• enableOCI: "true"：启用 Helm OCI 支持，将仓库视为 OCI 注册表（对应Repository.EnableOCI字段）。
• useAzureWorkloadIdentity: "true"：启用 Azure Workload Identity 认证（对应Repository.UseAzureWorkloadIdentity字段），无需在 Secret 中明文存放用户名密码。
• 该场景是"Azure Container Registry / Azure Repos 使用 Azure Workload Identity"的声明式表达，具体前提条件（工作负载身份联邦配置等）可参考 docs/user-guide/private-repositories.md 中的对应章节。

7. 通用私有 OCI 仓库

apiVersion: v1 kind: Secret metadata: name: private-oci-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: username: my-username password: my-password project: myproject type: oci url: oci://my.registry.com/namespace/service

要点说明：

• type: oci：显式声明 OCI 类型仓库。在 repository_types.go 中，RepoCreds.Type的可选值明确为"git"、"helm"或"oci"。
• url使用oci://协议前缀，指向注册表的命名空间与服务路径。
• 通过username/password提供注册表凭据，project限定项目归属。

仓库字段速查表

综合示例文件与 repository_types.go 的数据模型，SecretstringData中常用键如下：

认证方式全览：不止 HTTPS 与 SSH

除示例文件展示的 HTTPS、SSH、Helm、OCI 之外，声明式配置还支持以下认证方式（均写入同一类repositorySecret，详见 declarative-setup.md 的 Repositories 章节）：

GitHub App：在url基础上补充githubAppID、githubAppInstallationID、githubAppPrivateKey三个键；使用 GitHub Enterprise 时追加githubAppEnterpriseBaseUrl: https://ghe.example.com/api/v3。从源码看，GitHub App 认证凭据同样参与HasCredentials()判断，属于受支持的凭据类型。

Google Cloud Source：提供gcpServiceAccountKey，值为服务账号 JSON 密钥的多行内容，用于自动获取 GCP 源仓库的临时凭据。

Azure 服务主体：提供azureServicePrincipalClientId、azureServicePrincipalTenantId、azureServicePrincipalClientSecret，可选azureActiveDirectoryEndpoint指定非公有云环境（如https://login.microsoftonline.de）。

GitHub App / Azure 凭据模板：上述认证信息同样可以放入 repo-creds 模板 Secret（见下节）。

与凭据模板（repo-creds）的配合

示例文件首行注释特别提示：列表中的最后一个示例（OCI 仓库）可改用仓库凭据模板（配置于argocd-repo-creds.yaml）。凭据模板用于"多个仓库共用同一套凭据"的场景，其 Secret 标签为argocd.argoproj.io/secret-type: repo-creds，官方示例见 docs/operator-manual/argocd-repo-creds.yaml，如：

apiVersion: v1 kind: Secret metadata: name: argoproj-https-creds namespace: argocd labels: argocd.argoproj.io/secret-type: repo-creds stringData: url: https://github.com/argoproj type: helm password: my-password username: my-username

模板 URL 按最长前缀最佳匹配原则生效：URL 以https://github.com/argoproj为前缀的仓库，在自身未配置任何凭据（即不含sshPrivateKey、username、password等）时，自动继承该模板的凭据。模板同样支持 SSH 私钥、TLS 客户端证书、GitHub App、Azure 服务主体等全部凭据类型。在 util/db/repository.go 的GetRepository中可以看到，读取仓库时会调用enrichCredsToRepo将匹配的模板凭据补充到仓库对象上，实现运行时凭据注入。

供应链安全：TLS 证书与 SSH 主机公钥

• TLS 自签名/自定义 CA：当仓库使用自签名证书或自定义 CA 签发的证书时，需要在argocd-tls-certs-cmConfigMap 中按"服务器主机名（非完整 URL）→ PEM 证书"的映射配置。例如仓库 URL 为https://server.example.com/repos/my-repo，则键为server.example.com。该 ConfigMap 会被挂载到argocd-server与argocd-repo-server的/app/config/tls目录。未配置专门证书时，Argo CD 使用系统默认信任库校验（足以覆盖 GitHub、GitLab、Bitbucket 等公共托管服务）。
• SSH 主机公钥：SSH 接入必须预先在argocd-ssh-known-hosts-cmConfigMap 的ssh_known_hosts键中配置服务器公钥，否则连接直接失败。格式为每行<服务器名> <密钥类型> <Base64 密钥>，可用 OpenSSH 的ssh-keyscan生成：

for host in bitbucket.org github.com gitlab.com ssh.dev.azure.com vs-ssh.visualstudio.com ; do ssh-keyscan $host 2> /dev/null ; done

代理配置

当 Argo CD 所在网络需要通过代理访问仓库时，可在 Secret 中添加：

stringData: url: https://github.com/argoproj/private-repo proxy: https://proxy-server-url:8888 noProxy: ".internal.example.com,company.org,10.123.0.0/16"

proxy指定代理地址，noProxy列出免代理目标。注意：Argo CD 通过 exec 调用 helm、kustomize 等外部工具，这些工具对noProxy通配符/IP 段的语法支持可能与 Gohttpproxy包不一致，若发现noProxy未生效，建议改用完整域名等通用语法。未配置自定义代理时，Argo CD 会回退使用 repo-server 的标准代理环境变量。

应用与验证

将上述任一 Secret 清单保存为文件后，直接应用即可（前提是已完成 Argo CD 安装，默认命名空间argocd）：

kubectl apply -n argocd -f argocd-repositories.yaml

验证方式：

# 查看已注册的仓库 argocd repo list # 查看 Secret 是否被 Argo CD 正确识别 kubectl -n argocd get secrets -l argocd.argoproj.io/secret-type=repository

几点实操注意：

• Secret 必须位于 Argo CD 安装的命名空间（默认argocd），且标签值必须精确为repository。
• 若使用 Sealed Secrets 等加密方案，注意其会剥离标签，需要按工具要求重新补齐标签后再创建。
• 仓库凭据属于敏感数据，建议优先使用 Sealed Secrets、外部密钥管理或 Workload Identity 等机制，避免明文写入清单。
• 修改已有仓库配置时，直接更新对应 Secret 即可；控制器（repo-server）会感知变化并刷新连接信息。

小结

argocd-repositories.yaml表面上是几个示例 Secret 的合集，实质上是 Argo CD 声明式仓库接入的完整索引：从 HTTPS/SSH 私库、Helm 仓库到 OCI 注册表，从基础认证到 GitHub App、Azure Workload Identity，再到凭据模板复用与 TLS/SSH 信任链配置。理解"Secret + 标签 + url 字段"这一核心机制，再配合 repository_types.go 与 repository_secrets.go 的字段映射逻辑，你就可以将任意组合的仓库接入方案以纯声明式方式固化到 GitOps 仓库中，与 Application、AppProject 一起实现完整的"配置即代码"。

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