Argo CD 从零到一手把手教你搭建 GitOps 工作流上一篇文章我们聊了 Argo CD 的架构和原理这篇直接上硬货——从零开始搭建一套完整的 Argo CD 环境包括安装、配置 Git 仓库、连接集群、创建应用、设置自动同步以及常见问题排查保你一次跑通。目录准备工作安装 Argo CD访问 Argo CD 控制台配置 Git 仓库与凭据添加目标 Kubernetes 集群创建你的第一个 Application开启自动同步与自愈实战App of Apps 模式部署多应用常见问题与排错指南总结1. 准备工作开始前请确保你拥有以下环境一个可用的 Kubernetes 集群版本 ≥1.21可使用 minikube、kind、k3s 或云厂商托管集群。本地安装kubectl并配置好 kubeconfig可以正常操作集群。安装 Argo CD CLI可选但强烈推荐方便后续操作。一个 Git 仓库如 GitHub、GitLab用于存放应用配置。验证集群连通性bashkubectl cluster-info2. 安装 Argo CDArgo CD 官方提供了一份标准的安装清单直接 apply 即可在集群中部署。bash# 创建 argocd 命名空间 kubectl create namespace argocd # 安装 Argo CD推荐稳定版 kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml该清单会在argocd命名空间下部署以下核心组件argocd-serverAPI 服务器和 Web UIargocd-repo-server仓库服务器argocd-application-controller应用控制器argocd-redis缓存服务查看 Pod 状态bashkubectl get pods -n argocd -w等待所有 Pod 变为Running状态。3. 访问 Argo CD 控制台Argo CD 默认使用自签名证书通过端口转发即可在本地访问 Web UI。3.1 获取初始管理员密码bashkubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath{.data.password} | base64 -d复制输出的密码。3.2 端口转发bashkubectl port-forward svc/argocd-server -n argocd 8080:443打开浏览器访问https://localhost:8080忽略证书警告使用用户名admin和刚才获取的密码登录。4. 配置 Git 仓库与凭据为了让 Argo CD 能够拉取你的私有 Git 仓库需要添加凭据。4.1 通过 CLI 添加仓库推荐bashargocd login localhost:8080 --username admin --password your-password --insecure添加 Git 仓库以 HTTPS 为例bashargocd repo add https://github.com/your-org/your-repo.git \ --username your-github-user \ --password personal-access-token4.2 通过 UI 添加仓库登录 Web UI →Settings→Repositories→Connect Repo输入仓库 URL 和凭据即可。5. 添加目标 Kubernetes 集群默认情况下Argo CD 已经连接了自己所在的集群https://kubernetes.default.svc。若需管理外部集群需要添加目标集群。5.1 列出当前已连接的集群bashargocd cluster list5.2 添加外部集群假设外部集群的 kubeconfig 文件为external-cluster.yamlbashargocd cluster add external-context --kubeconfig external-cluster.yaml其中external-context是 kubeconfig 中配置的 context 名称。添加成功后在 UI 的Settings → Clusters中可看到所有集群。6. 创建你的第一个 Application现在我们来部署一个示例应用。假设仓库https://github.com/your-org/your-repo.git中有一个guestbook目录包含 Kubernetes 资源 YAML 文件。6.1 通过 CLI 创建bashargocd app create guestbook \ --repo https://github.com/your-org/your-repo.git \ --path guestbook \ --dest-server https://kubernetes.default.svc \ --dest-namespace guestbook \ --sync-policy none--repoGit 仓库地址--path应用配置所在的目录相对于仓库根目录--dest-server目标集群的 API Server 地址默认集群使用https://kubernetes.default.svc--dest-namespace部署到的命名空间需提前创建或开启自动创建--sync-policy稍后设置自动同步这里先设为none6.2 通过 YAML 创建yaml# guestbook-app.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: guestbook namespace: argocd spec: project: default source: repoURL: https://github.com/your-org/your-repo.git targetRevision: HEAD path: guestbook destination: server: https://kubernetes.default.svc namespace: guestbook syncPolicy: syncOptions: - CreateNamespacetrue # 自动创建命名空间然后 applybashkubectl apply -f guestbook-app.yaml此时 Argo CD 会立即从 Git 拉取配置并对比集群状态UI 中显示OutOfSync因为尚未部署。7. 开启自动同步与自愈为了让集群状态自动跟随 Git 仓库变化需要在 Application 中配置自动化同步策略。7.1 通过 CLI 设置自动同步bashargocd app set guestbook --sync-policy automated --auto-prune --self-heal--auto-prune仓库中删除的资源也会从集群中删除--self-heal集群中手动修改会被自动回滚到 Git 定义7.2 通过 YAML 补全在 Application YAML 中补充yamlsyncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespacetrue更新后bashargocd app sync guestbook应用状态将变为Synced和Healthy。验证自愈效果手动修改集群中的 Deployment 副本数bashkubectl scale deployment guestbook-ui -n guestbook --replicas5几秒钟后Argo CD 会自动将其恢复为 Git 中定义的副本数。8. 实战App of Apps 模式部署多应用当需要管理几十上百个应用时推荐使用App of Apps模式。8.1 准备仓库结构textargocd-apps/ ├── app-of-apps.yaml ├── team-a/ │ ├── frontend-app.yaml │ └── backend-app.yaml └── team-b/ └── api-app.yaml其中frontend-app.yaml和backend-app.yaml等文件本身就是 Argo CD 的 Application 对象描述子应用。8.2 定义根 Applicationyaml# app-of-apps.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: app-of-apps namespace: argocd spec: project: default source: repoURL: https://github.com/your-org/argocd-apps.git path: . targetRevision: HEAD destination: server: https://kubernetes.default.svc namespace: argocd syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespacetrue注意根应用的path指向仓库根目录.它会递归发现目录下的所有 Application 资源。8.3 部署根应用bashargocd app create app-of-apps \ --repo https://github.com/your-org/argocd-apps.git \ --path . \ --dest-server https://kubernetes.default.svc \ --dest-namespace argocd \ --sync-policy automated \ --auto-prune \ --self-heal几分钟后所有子应用将自动创建并开始同步各自的资源。9. 常见问题与排错指南9.1 无法连接 Git 仓库确认凭据是否正确用户名/密码、Token。如果是自签名证书的 Git 服务器需在 Argo CD 中配置tlsClientConfig跳过验证或添加 CA。9.2 应用始终 OutOfSync检查repo/path是否正确仓库中是否存在期望的 YAML 文件。使用argocd app diff app-name查看具体差异。检查目标命名空间是否存在或开启CreateNamespacetrue。9.3 同步失败提示资源已存在可能是资源已由其他方式创建需要先删除或通过 Argo CD 接管。可在 Application 中配置syncPolicy.syncOptions如Replacetrue或ApplyOutOfSyncOnlytrue。9.4 自愈不生效检查 Application 的syncPolicy.automated.selfHeal是否为true。查看 controller 日志kubectl logs -n argocd deployment/argocd-application-controller。9.5 Webhook 未触发同步确保 Git 仓库配置的 Webhook URL 可达Argo CD 的 Service 需暴露或使用 Ingress。查看argocd-server日志是否有 Webhook 请求记录。10. 总结通过以上步骤你已经成功搭建了 Argo CD实现了从 Git 仓库自动同步应用到 Kubernetes 集群的完整 GitOps 工作流。回顾核心流程安装 Argo CD 到集群配置 Git 仓库访问凭据创建 Application 指向目标配置开启自动同步、自愈和清理通过 App of Apps 扩展至大规模管理下一步你可以尝试集成 Sealed Secrets 管理密钥、使用 Image Updater 自动更新镜像版本或与 Argo Rollouts 结合实现渐进式交付。GitOps 的大门已经敞开动手实践就是最好的学习方式。这篇文章带你从零搭建了 Argo CD如果解决了你的问题欢迎点赞、收藏。有任何踩坑经验评论区等你分享
Argo CD 从零到一手把手教你搭建 GitOps 工作流上一篇文章我们聊了 Argo CD 的架构和原理这篇直接上硬货——从零开始搭建一套完整的 Argo CD 环境包括安装、配置 Git 仓库、连接集群、创建应用、设置自动同步以及常见问题排查保你一次跑通。目录准备工作安装 Argo CD访问 Argo CD 控制台配置 Git 仓库与凭据添加目标 Kubernetes 集群创建你的第一个 Application开启自动同步与自愈实战App of Apps 模式部署多应用常见问题与排错指南总结1. 准备工作开始前请确保你拥有以下环境一个可用的 Kubernetes 集群版本 ≥1.21可使用 minikube、kind、k3s 或云厂商托管集群。本地安装kubectl并配置好 kubeconfig可以正常操作集群。安装 Argo CD CLI可选但强烈推荐方便后续操作。一个 Git 仓库如 GitHub、GitLab用于存放应用配置。验证集群连通性bashkubectl cluster-info2. 安装 Argo CDArgo CD 官方提供了一份标准的安装清单直接 apply 即可在集群中部署。bash# 创建 argocd 命名空间 kubectl create namespace argocd # 安装 Argo CD推荐稳定版 kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml该清单会在argocd命名空间下部署以下核心组件argocd-serverAPI 服务器和 Web UIargocd-repo-server仓库服务器argocd-application-controller应用控制器argocd-redis缓存服务查看 Pod 状态bashkubectl get pods -n argocd -w等待所有 Pod 变为Running状态。3. 访问 Argo CD 控制台Argo CD 默认使用自签名证书通过端口转发即可在本地访问 Web UI。3.1 获取初始管理员密码bashkubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath{.data.password} | base64 -d复制输出的密码。3.2 端口转发bashkubectl port-forward svc/argocd-server -n argocd 8080:443打开浏览器访问https://localhost:8080忽略证书警告使用用户名admin和刚才获取的密码登录。4. 配置 Git 仓库与凭据为了让 Argo CD 能够拉取你的私有 Git 仓库需要添加凭据。4.1 通过 CLI 添加仓库推荐bashargocd login localhost:8080 --username admin --password your-password --insecure添加 Git 仓库以 HTTPS 为例bashargocd repo add https://github.com/your-org/your-repo.git \ --username your-github-user \ --password personal-access-token4.2 通过 UI 添加仓库登录 Web UI →Settings→Repositories→Connect Repo输入仓库 URL 和凭据即可。5. 添加目标 Kubernetes 集群默认情况下Argo CD 已经连接了自己所在的集群https://kubernetes.default.svc。若需管理外部集群需要添加目标集群。5.1 列出当前已连接的集群bashargocd cluster list5.2 添加外部集群假设外部集群的 kubeconfig 文件为external-cluster.yamlbashargocd cluster add external-context --kubeconfig external-cluster.yaml其中external-context是 kubeconfig 中配置的 context 名称。添加成功后在 UI 的Settings → Clusters中可看到所有集群。6. 创建你的第一个 Application现在我们来部署一个示例应用。假设仓库https://github.com/your-org/your-repo.git中有一个guestbook目录包含 Kubernetes 资源 YAML 文件。6.1 通过 CLI 创建bashargocd app create guestbook \ --repo https://github.com/your-org/your-repo.git \ --path guestbook \ --dest-server https://kubernetes.default.svc \ --dest-namespace guestbook \ --sync-policy none--repoGit 仓库地址--path应用配置所在的目录相对于仓库根目录--dest-server目标集群的 API Server 地址默认集群使用https://kubernetes.default.svc--dest-namespace部署到的命名空间需提前创建或开启自动创建--sync-policy稍后设置自动同步这里先设为none6.2 通过 YAML 创建yaml# guestbook-app.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: guestbook namespace: argocd spec: project: default source: repoURL: https://github.com/your-org/your-repo.git targetRevision: HEAD path: guestbook destination: server: https://kubernetes.default.svc namespace: guestbook syncPolicy: syncOptions: - CreateNamespacetrue # 自动创建命名空间然后 applybashkubectl apply -f guestbook-app.yaml此时 Argo CD 会立即从 Git 拉取配置并对比集群状态UI 中显示OutOfSync因为尚未部署。7. 开启自动同步与自愈为了让集群状态自动跟随 Git 仓库变化需要在 Application 中配置自动化同步策略。7.1 通过 CLI 设置自动同步bashargocd app set guestbook --sync-policy automated --auto-prune --self-heal--auto-prune仓库中删除的资源也会从集群中删除--self-heal集群中手动修改会被自动回滚到 Git 定义7.2 通过 YAML 补全在 Application YAML 中补充yamlsyncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespacetrue更新后bashargocd app sync guestbook应用状态将变为Synced和Healthy。验证自愈效果手动修改集群中的 Deployment 副本数bashkubectl scale deployment guestbook-ui -n guestbook --replicas5几秒钟后Argo CD 会自动将其恢复为 Git 中定义的副本数。8. 实战App of Apps 模式部署多应用当需要管理几十上百个应用时推荐使用App of Apps模式。8.1 准备仓库结构textargocd-apps/ ├── app-of-apps.yaml ├── team-a/ │ ├── frontend-app.yaml │ └── backend-app.yaml └── team-b/ └── api-app.yaml其中frontend-app.yaml和backend-app.yaml等文件本身就是 Argo CD 的 Application 对象描述子应用。8.2 定义根 Applicationyaml# app-of-apps.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: app-of-apps namespace: argocd spec: project: default source: repoURL: https://github.com/your-org/argocd-apps.git path: . targetRevision: HEAD destination: server: https://kubernetes.default.svc namespace: argocd syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespacetrue注意根应用的path指向仓库根目录.它会递归发现目录下的所有 Application 资源。8.3 部署根应用bashargocd app create app-of-apps \ --repo https://github.com/your-org/argocd-apps.git \ --path . \ --dest-server https://kubernetes.default.svc \ --dest-namespace argocd \ --sync-policy automated \ --auto-prune \ --self-heal几分钟后所有子应用将自动创建并开始同步各自的资源。9. 常见问题与排错指南9.1 无法连接 Git 仓库确认凭据是否正确用户名/密码、Token。如果是自签名证书的 Git 服务器需在 Argo CD 中配置tlsClientConfig跳过验证或添加 CA。9.2 应用始终 OutOfSync检查repo/path是否正确仓库中是否存在期望的 YAML 文件。使用argocd app diff app-name查看具体差异。检查目标命名空间是否存在或开启CreateNamespacetrue。9.3 同步失败提示资源已存在可能是资源已由其他方式创建需要先删除或通过 Argo CD 接管。可在 Application 中配置syncPolicy.syncOptions如Replacetrue或ApplyOutOfSyncOnlytrue。9.4 自愈不生效检查 Application 的syncPolicy.automated.selfHeal是否为true。查看 controller 日志kubectl logs -n argocd deployment/argocd-application-controller。9.5 Webhook 未触发同步确保 Git 仓库配置的 Webhook URL 可达Argo CD 的 Service 需暴露或使用 Ingress。查看argocd-server日志是否有 Webhook 请求记录。10. 总结通过以上步骤你已经成功搭建了 Argo CD实现了从 Git 仓库自动同步应用到 Kubernetes 集群的完整 GitOps 工作流。回顾核心流程安装 Argo CD 到集群配置 Git 仓库访问凭据创建 Application 指向目标配置开启自动同步、自愈和清理通过 App of Apps 扩展至大规模管理下一步你可以尝试集成 Sealed Secrets 管理密钥、使用 Image Updater 自动更新镜像版本或与 Argo Rollouts 结合实现渐进式交付。GitOps 的大门已经敞开动手实践就是最好的学习方式。这篇文章带你从零搭建了 Argo CD如果解决了你的问题欢迎点赞、收藏。有任何踩坑经验评论区等你分享
