ArgoCD 是一款专门为 Kubernetes 设计的 GitOps 持续交付工具。它的核心思路并不复杂：把 Git 仓库中的 YAML 文件视为期望状态，ArgoCD 会周期性地比较仓库内容与集群中实际运行的资源，一旦发现差异就提示 OutOfSync，并可以自动把集群纠正到与 Git 一致的状态。相比传统的手工 kubectl apply 或 CI 脚本直接操作集群，ArgoCD 将部署动作收敛到一个控制平面内，每一次变更都有 Git 提交记录可以追溯，回滚也只需把 Git 指针切回上一个提交。
部署 ArgoCD 本身并不需要复杂的外部依赖，官方提供了单个 install.yaml 文件，一条 kubectl apply 命令就可以把核心组件装进 argocd 命名空间。不过，要把这套组件用好，还需要理解它由哪些部分组成、如何暴露服务、如何配置 Git 仓库凭据，以及如何创建第一个 Application。下面按步骤展开。
一、部署前的环境准备与资源规划
开始安装之前，需要确保本地有可用的 Kubernetes 集群和 kubectl 命令，并且当前用户对集群具备创建命名空间、部署 Deployment、Service、ConfigMap 等资源的权限。如果没有管理员权限，也可以用受限的命名空间管理员账号，但需要预先创建好命名空间并分配 RBAC 规则。
ArgoCD 官方推荐将所有组件安装到独立的 argocd 命名空间中。这样做的好处是资源边界清晰，后续升级、卸载或排查问题时不会影响到业务应用所在的命名空间。ArgoCD 安装后会创建多个 Deployment，包括 argocd-server、argocd-repo-server、argocd-application-controller、argocd-redis 以及 argocd-dex-server 等。对于测试环境，默认的资源请求通常足够；如果计划在生产环境中使用，建议至少为 argocd-application-controller 和 argocd-repo-server 预留 256Mi 以上的内存，并监控 Redis 的使用情况。
网络规划方面，如果只需要本机访问控制台，可以使用 kubectl port-forward 临时转发流量。如果希望团队成员都能访问，则可以选择把 argocd-server 服务改为 NodePort，或在集群已有 Ingress Controller 的前提下创建 Ingress 资源。ArgoCD 默认使用 HTTPS 并生成自签名证书，首次访问时需要跳过浏览器警告。
二、使用官方 YAML 安装 ArgoCD
安装步骤最直接的方式是使用官方仓库中的 stable 清单。先创建命名空间，然后应用 install.yaml 文件：
kubectl create namespace argocd kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
第一条命令创建 argocd 命名空间，第二条命令从官方 GitHub 仓库拉取 stable 分支的安装清单并应用。stable 分支通常指向最新的稳定版本，适合大多数场景。如果企业内部网络无法直接访问 GitHub，可以先把 install.yaml 下载到本地，再通过内网文件服务器或本地路径执行 kubectl apply -n argocd -f install.yaml。
安装完成后，需要等待所有 Pod 进入 Running 状态。可以使用下面的命令持续观察 Pod 状态，直到全部就绪：
kubectl get pods -n argocd -w
正常情况下会看到 argocd-application-controller、argocd-repo-server、argocd-server 和 argocd-redis 等 Pod 先后启动。首次拉取镜像可能需要几分钟，如果长时间处于 ImagePullBackOff，需要检查集群节点是否能访问镜像仓库，或者是否配置了私有镜像加速器。
ArgoCD 安装后会自动生成一个初始管理员账号 admin，密码存放在名为 argocd-initial-admin-secret 的 Secret 中。获取密码的命令如下：
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
执行后终端会输出一串随机生成的密码。建议登录后立即修改，避免使用默认密码。修改密码可以通过 ArgoCD 控制台完成，也可以使用 ArgoCD CLI 登录后执行 argocd account update-password。
三、暴露 ArgoCD 服务并登录控制台
ArgoCD 控制台由 argocd-server 服务提供，默认类型为 ClusterIP，只能在集群内部访问。最简单的访问方式是使用端口转发，把本机 8080 端口转发到服务的 443 端口：
kubectl port-forward svc/argocd-server -n argocd 8080:443
命令执行后不要关闭终端，浏览器访问 https://localhost:8080 即可打开登录页面。由于证书是自签名，浏览器会提示连接不安全，点击继续访问即可。使用 admin 和刚才获取的初始密码登录。
如果需要将服务暴露给集群外部的其他机器，可以把 argocd-server 临时改成 NodePort 类型：
kubectl patch svc argocd-server -n argocd -p '{"spec":{"type":"NodePort"}}'
kubectl get svc argocd-server -n argocd -o jsonpath="{.spec.ports[0].nodePort}"; echo
执行后会得到一个随机 NodePort 端口，使用集群任意节点 IP 加该端口即可访问。但 NodePort 方式不利于统一管理，生产环境更推荐使用 Ingress。下面给出一个 Nginx Ingress 的配置示例，其中 ssl-passthrough 注解可以让 ArgoCD 自身的 TLS 证书继续生效：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: argocd-server
namespace: argocd
annotations:
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
ingressClassName: nginx
rules:
- host: argocd.ipipp.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: argocd-server
port:
number: 443
应用这个 Ingress 之前，需要确保集群已经安装了 Nginx Ingress Controller，并且 DNS 将 argocd.ipipp.com 解析到 Ingress 入口地址。如果不想处理证书问题，也可以去掉 ssl-passthrough 注解，由 Ingress Controller 提供新的 TLS 证书，但需要额外配置证书 Secret。
四、创建第一个 Application 并体验 GitOps 同步
ArgoCD 的核心对象是 Application，它描述了一组 Kubernetes 资源从哪里来、部署到哪里、以及如何同步。假设 Git 仓库中有一个 overlays/dev 目录，里面包含 Deployment 和 Service 的 YAML 文件，可以创建如下 Application：
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: demo-app
namespace: argocd
spec:
project: default
source:
repoURL: https://git.ipipp.com/team/demo.git
targetRevision: HEAD
path: overlays/dev
destination:
server: https://kubernetes.default.svc
namespace: demo
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
这个 Application 的含义是：从 git.ipipp.com/team/demo.git 仓库的 HEAD 提交中读取 overlays/dev 目录下的 YAML，将它们部署到当前 Kubernetes 集群的 demo 命名空间。如果 demo 命名空间不存在，CreateNamespace=true 会自动创建它。自动同步策略中，prune: true 表示删除 Git 中已经移除的资源，selfHeal: true 表示当集群状态偏离 Git 时自动修正。
将上述内容保存为 application.yaml 并执行 kubectl apply -f application.yaml，ArgoCD 的 application-controller 就会监听到这个新资源，开始从 Git 仓库拉取配置并渲染 Kubernetes 对象。等待片刻后，可以在控制台看到 demo-app 的同步状态。如果显示 Synced 且 Health 为 Healthy，说明部署成功；如果显示 OutOfSync，可以点击 Diff 查看具体差异。
命令行同样可以查看同步状态和日志。使用 argocd app list 可以列出所有应用，使用 argocd app sync demo-app 可以手动触发同步。ArgoCD 还支持设置同步窗口、禁用自动同步等策略，这些可以在后期根据团队流程调整。
五、私有仓库凭据与常见问题排查
如果 Git 仓库是私有的，直接使用 Application 会因认证失败而无法拉取代码。ArgoCD 支持通过 Secret 存储仓库凭据。最简单的方式是在 argocd 命名空间创建一个带有特定标签的 Secret：
kubectl create secret generic private-repo -n argocd \ --from-literal=type=git \ --from-literal=url=https://git.ipipp.com/team/private.git \ --from-literal=username=git \ --from-literal=password=your-token kubectl label secret private-repo -n argocd argocd.argoproj.io/secret-type=repository
创建完成后，ArgoCD 会自动识别该 Secret，并在拉取对应仓库时使用其中的用户名和密码。也可以使用 ArgoCD CLI 的 argocd repo add 命令完成同样的配置，它会把 Secret 写入集群。需要注意的是，密码或 Token 应以 Secret 形式保存，避免明文写入 Application 的 YAML 文件。
部署过程中最容易遇到的问题集中在三类：一是 Git 仓库认证失败，控制台 Repo 页面显示 authentication required，此时需要检查 Secret 中的 URL 是否与 Application 中的 repoURL 完全一致，包括路径末尾是否带 .git；二是应用一直显示 Progressing，可能是 Deployment 的镜像拉取失败或健康检查未通过，可先通过 kubectl describe pod 查看 Pod 事件；三是同步时报 namespace not found，需要确认 syncOptions 中是否添加了 CreateNamespace=true。查看 ArgoCD 组件日志也是定位问题的有效手段：
kubectl logs -n argocd deployment/argocd-repo-server -f kubectl logs -n argocd deployment/argocd-application-controller -f
其中 repo-server 日志适合排查 Git 拉取和 Helm 渲染错误，application-controller 日志适合排查同步状态计算和资源应用错误。定位到具体错误信息后，再结合 Kubernetes 原生事件处理，往往能快速恢复。
六、生产环境使用建议与安全加固
生产环境部署 ArgoCD 时，不建议长期使用初始 admin 账号和自签名证书。ArgoCD 支持通过 Dex 接入 OIDC、LDAP 等企业身份系统，可以在 argocd-cm ConfigMap 中配置 SSO，并配合 RBAC 策略限制不同用户对项目的操作权限。例如可以只允许开发团队同步 dev 项目，禁止修改 prod 项目。
此外，建议把 ArgoCD 自身的配置也纳入 Git 管理。可以使用 argocd-cm、argocd-rbac-cm、argocd-secret 等对象保存配置，并通过声明式的方式备份到仓库。升级 ArgoCD 前，先备份这些配置和所有 Application 资源，再按官方升级路径逐个版本升级，避免跨版本导致 CRD 不兼容。对于高可用要求较高的场景，可以研究 ArgoCD 的 HA 部署模式，它会对 argocd-server、argocd-application-controller 等组件做多副本和故障转移。
最后需要理解，ArgoCD 的自动同步默认采用定时轮询机制，而不是 Git push 实时触发。如果希望代码合并后立即同步，可以配置 Git webhook 通知 ArgoCD，或者使用 argocd app sync 手动触发。合理的同步策略、清晰的目录结构和严格的 Git 分支保护，是让 ArgoCD 在 Kubernetes 集群中稳定运行的关键。
ArgoCDKubernetesGitOps修改时间：2026-09-20 15:40:03