Argo CD 本地环境搭建实战：基于 Kind 快速部署与开发调试

Argo CD 本地环境搭建实战：基于 Kind 快速部署与开发调试

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

本指南以官方文档 docs/try_argo_cd_locally.md 为主体脉络，完整演示如何在本地通过 Kind 创建 Kubernetes 集群、安装 Argo CD、暴露 API Server 并登录 UI 的完整流程；同时结合仓库内的安装清单、Makefile、Procfile 等源码级材料，补充 server-side apply 原理、各核心组件职责、本地开发模式与常见排错手段。读完本文，你将获得一套可直接复制执行、可在任何装有 Docker/Kubectl 的机器上复现的 Argo CD 本地实践方案。

前置条件与基础概念

Argo CD 是 Kubernetes 原生的声明式持续交付工具，在使用它之前，建议先建立对底层技术的认知。官方建议先阅读 docs/understand_the_basics.md 了解 Docker、Kubernetes 以及 Kustomize/Helm 等模板化工具，这些决定了后续如何组织你的应用清单。

本指南假设你已具备：

• 本机安装 Docker（Kind 依赖它运行集群节点容器）；
• 已安装kubectl并拥有可用的 kubeconfig 配置（默认位置~/.kube/config）；
• 了解基本的 Git 与 YAML 清单知识。

整个本地实践分为两条主线：一条面向普通用户——用 Kind 搭建集群并按官方 install.yaml 安装 Argo CD，直接体验 UI 与 CLI；一条面向开发者——用make start/goreman在集群外运行各组件进行源码调试，详见 docs/developer-guide/running-locally.md。本文以第一条为主线，并在最后补充第二条的要点。

第一步：安装 Kind

Kind（Kubernetes in Docker）用于在本地用 Docker 容器模拟多节点集群，是官方推荐的本地方案之一。请按 Kind 官方 quick-start 说明完成安装。安装完成后验证版本：

kind version

Kind 的核心价值在于：创建与销毁成本极低、支持多节点拓扑、与 CI 环境契合，非常适合用来承载 Argo CD 这类以 CRD 与控制器为核心的组件。

第二步：创建 Kind 集群

安装完成后，创建一个命名为argocd-cluster的本地集群：

kind create cluster --name argocd-cluster

执行成功后，Kind 会生成对应的 kubeconfig 上下文（上下文名为kind-argocd-cluster），一个单节点（默认配置）的 Kubernetes 集群随即就绪。如需自定义节点数量或端口映射，可参考 Kind 的配置文件方式创建。

第三步：让 kubectl 指向 Kind 集群

创建集群后，确认kubectl已正确指向新集群：

kubectl cluster-info --context kind-argocd-cluster

该命令会输出集群的 Kubernetes 控制面地址与 CoreDNS 地址，用于验证上下文切换是否成功。之后所有kubectl命令默认都会作用于该 Kind 集群。

第四步：在集群上安装 Argo CD

在集群中创建argocd命名空间，并应用官方安装清单：

kubectl create namespace argocd kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

注意：--server-side --force-conflicts两个标志是必需的，原因在于部分 Argo CD CRD（如 ApplicationSet）的体积超过了 client-sidekubectl apply的 262KB 注解大小限制。更详细的说明见 docs/getting_started.md。

从源码层面理解这两个标志（依据 docs/getting_started.md 的说明）：

• --server-side：将清单合并逻辑交由 API Server 执行，不再存储last-applied-configuration注解，从而绕开注解体积限制；
• --force-conflicts：允许本次 apply 接管此前由其他工具（如 Helm 或之前的 apply）管理的字段。这对全新安装是安全的，也是升级所必需的。需要留意：清单中已定义的字段（如affinity、env、probes）若被你自定义过，会被覆盖；而清单未涉及的字段（如resources资源配额、tolerations）会被保留。

仓库中对应的安装清单位于 manifests/install.yaml（该文件头部注释标明 "This is an auto-generated file. DO NOT EDIT"，由make manifests从 manifests/base 目录下的模板生成）。其内容以applications.argoproj.io等 CRD 开头，随后依次是各组件 Deployment、RBAC、ConfigMap、Service 与 Secret。仓库还提供了多种变体清单：

• manifests/core-install.yaml：仅核心组件，适合不需要 UI、SSO 与多集群功能的场景；
• manifests/namespace-install.yaml：限制在单个命名空间的安装；
• manifests/ha 与*-with-hydrator.yaml：高可用及启用 Hydrator 的变体。

警告：安装清单中包含引用argocd命名空间的ClusterRoleBinding资源，若安装到其他命名空间，务必同步修改其中的命名空间引用。

提示：默认安装中 Redis 使用密码认证，密码存放在argocd命名空间下名为argocd-redis的 Secret 中（key 为auth）。对应清单见 manifests/base/redis/argocd-redis-deployment.yaml：其 initContainer 会调用argocd admin redis-initial-password生成初始密码，主容器则通过--requirepass $(REDIS_PASSWORD)从 Secret 读取。从源码结构看，本地开发脚本 hack/start-redis-with-password.sh 也复用了同样的 Secret 读取逻辑（kubectl get secret argocd-redis ... key=auth），保证本地 Redis 与集群内 Redis 口令一致。

第五步：暴露 Argo CD API Server

默认情况下 Argo CD 的 API Server 不会暴露到集群之外，需要在本地访问 UI，可以使用 kubectl 的端口转发功能：

kubectl port-forward svc/argocd-server -n argocd 8080:443

该命令将本机 8080 端口转发到集群内argocd-server服务的 443 端口（HTTPS，默认使用自签名证书）。转发成功后，浏览器访问 http://localhost:8080 即可打开 Argo CD UI。

除端口转发外，docs/getting_started.md 还列出了另外两种暴露方式，可根据环境选择：

• LoadBalancer：kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'，云环境会分配外部 IP；
• Ingress：按 docs/operator-manual/ingress.md 配置。

第六步：登录 Argo CD UI

打开浏览器访问 http://localhost:8080 后，需要获取默认admin账号的初始密码。密码由安装过程自动生成，并以明文形式存放在argocd-initial-admin-secret中：

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

使用用户名admin与上述密码即可登录。登录后建议立即修改默认密码，并删除初始密码 Secret：

argocd account update-password kubectl delete secret argocd-initial-admin-secret -n argocd

说明：该 Secret 的唯一用途就是存放初始密码明文，删除是安全的；若 Argo CD 需要重新生成 admin 密码，它会按需重建此 Secret（依据 docs/getting_started.md）。

也可使用argocd admin initial-password -n argocd一条命令直接读取初始密码，方便 CLI 场景。

第七步：登录 CLI 并创建第一个应用

下载或安装 Argo CD CLI（Mac/Linux/WSL 可通过brew install argocd），然后登录：

argocd login localhost:8080

如果端口转发未开启或 CLI 无法直连 API Server，可通过环境变量让 CLI 自动使用端口转发：

export ARGOCD_OPTS='--port-forward-namespace argocd'

登录后，可将当前上下文默认命名空间设为argocd，然后创建示例应用（guestbook）：

kubectl config set-context --current --namespace=argocd argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default

查看状态并同步（部署）：

argocd app get guestbook argocd app sync guestbook

首次创建的应用会处于OutOfSync状态，执行argocd app sync后，Argo CD 会从 Git 仓库拉取清单并kubectl apply到目标集群（此处为集群内部地址https://kubernetes.default.svc），随后在 UI 中即可看到应用的资源树、日志、事件与健康状态。详细的分步操作（含 UI 创建应用的方式）见 docs/getting_started.md 的步骤 5～7。

开发者视角：在 Kind 集群上本地运行 Argo CD 源码

如果你要基于当前仓库做二次开发，官方推荐先在集群外运行 Argo CD 各组件（见 docs/developer-guide/running-locally.md），避免每次改动都要重新构建并推送 Docker 镜像。整体思路是：

1. 先把 Argo CD 的资源对象部署进集群（CRD、ConfigMap、RBAC 等），再把所有实例缩容到 0，只保留"配置"：

   kubectl apply -n argocd --server-side --force-conflicts -f manifests/install.yaml kubectl -n argocd scale statefulset/argocd-application-controller --replicas 0 kubectl -n argocd scale deployment/argocd-dex-server --replicas 0 kubectl -n argocd scale deployment/argocd-repo-server --replicas 0 kubectl -n argocd scale deployment/argocd-server --replicas 0 kubectl -n argocd scale deployment/argocd-redis --replicas 0 kubectl -n argocd scale deployment/argocd-applicationset-controller --replicas 0 kubectl -n argocd scale deployment/argocd-notifications-controller --replicas 0

   同时把当前上下文默认命名空间切到argocd（kubectl config set-context --current --namespace=argocd），因为后续启动的本地服务假定 Argo CD 安装在当前命名空间。

2. 在宿主机启动全部本地服务。仓库根目录的 Procfile 定义了完整的进程组，从内容可以看到各组件对应的二进制与关键参数：controller、api-server、dex、redis、repo-server、cmp-server、commit-server、ui、git-server、helm-registry、oci-registry、applicationset-controller、notification等，其中 redis 由 hack/start-redis-with-password.sh 启动。

   使用虚拟化工具链（Docker 内构建）时一条命令即可：

   cd argo-cd make start

   使用 Podman 替代 Docker：DOCKER=podman make start。

   使用本地工具链时有三种方式（均需ARGOCD_GPG_ENABLED=false）：

   make start-local ARGOCD_GPG_ENABLED=false make run ARGOCD_GPG_ENABLED=false ARGOCD_GPG_ENABLED=false && goreman start

   从 Makefile 源码看：start目标实际是在 test-server 容器内调用start-local；start-local会先执行mod-vendor-local dep-ui-local cli-local完成依赖与 CLI 构建，再通过goreman -f $(ARGOCD_PROCFILE) start拉起进程；run则调用 hack/goreman-start.sh。启动后暴露的端口为：

   • Argo CD API Server：8080
   • Argo CD UI（webpack dev server）：4000
   • Helm Registry：5000

   UI 访问 http://localhost:4000，CLI 对接 API 则使用--insecure --plaintext参数访问 http://localhost:8080。为避免每条命令都带参数，可设置环境变量：

   export ARGOCD_SERVER=127.0.0.1:8080 export ARGOCD_OPTS="--plaintext --insecure"

3. 本地登录 CLI。本地模式同样从 Secret 取初始密码后登录：

   kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo dist/argocd login localhost:8080

4. 热更新与回归：修改 UI（.tsx/.scss）会自动热更新到 4000 端口；修改 Go 后端则需要重启对应服务，例如goreman run restart repo-server（服务名见 Procfile）；修改 CLI 代码需重启make start/make start-local会话。测试结束后，可把集群内各 Deployment/StatefulSet 重新 scale 回 1，或按 docs/developer-guide/running-locally.md 的说明构建自定义镜像（设置IMAGE_REGISTRY、IMAGE_NAMESPACE、IMAGE_TAG后执行make image，再用make manifests重新生成包含自定义镜像引用的清单）。

常见问题与排错速查

• UI 首次加载慢：本地模式（4000 端口）首次页面加载需要等待 webpack 打包，可能耗时数秒到数分钟，属正常现象。
• kubectl apply报注解超限：务必使用--server-side --force-conflicts，这与 CRD 体积限制有关（原因见上文）。
• 端口转发不生效：确认argocd-serverService 在argocd命名空间内已就绪：kubectl get svc -n argocd。
• CLI 无法连接 API：检查是否设置了ARGOCD_OPTS='--port-forward-namespace argocd'或正确使用--insecure --plaintext。
• 本地进程未全部启动：goreman run status中未标记*的进程说明启动失败；默认日志级别为 DEBUG，日志过于嘈杂时可编辑仓库根目录 Procfile 中各命令的日志级别参数。
• 架构差异：示例应用（guestbook）可能仅适配 AMD64，ARM 环境下需自行验证镜像兼容性；构建镜像时 Apple 芯片需设置TARGET_ARCH=linux/arm64。

总结

本文从零开始完成了"Kind 建集群 → server-side 安装 Argo CD → 端口转发暴露 UI → 获取初始密码登录 → CLI 创建并同步应用"的完整闭环，并深入解释了--server-side --force-conflicts的底层原因（CRD 注解体积限制）。对开发者而言，docs/developer-guide/running-locally.md 提供了基于 Procfile 与 Makefile 的集群外本地调试方案，可大幅缩短迭代周期。接下来即可进入 docs/getting_started.md 的后续步骤，进一步体验 Argo CD 的 Sync 策略、健康评估与多集群管理等核心能力。

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