Argo CD Getting Started 实战指南从零安装到 GitOps 应用部署【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd本指南基于 Argo CD 官方《Getting Started》文档展开逐步演示如何在本仓库对应的 Argo CD 发行版中完成完整落地创建命名空间并安装 Argo CD、下载并配置 CLI、通过三种方式暴露 API Server、获取初始管理员密码并登录、注册目标集群最后用 CLI 与 UI 两种方式创建并同步一个来自 Git 仓库的 guestbook 示例应用。读完本文你将掌握一套可复现、可上生产的 Argo CD 最小化上手路径并对安装清单中--server-side --force-conflicts的深层原因、初始密码 Secret 的生命周期、集群注册权限模型等底层机制有源码级的理解。前置要求与概念基础正式开始前请确保环境满足以下条件已安装 kubectl 命令行工具并配置好可访问目标 Kubernetes 集群的 kubeconfig 文件默认位置为~/.kube/config。集群内已启用CoreDNS。例如在 microk8s 中可通过microk8s enable dns microk8s stop microk8s start启用。对 Argo CD 所依赖的基础工具Git、Kubernetes 声明式清单、Helm/Kustomize 等有基本认知。官方文档建议先阅读 understand_the_basics.md 了解这些工具再继续本文操作。1. 安装 Argo CD1.1 安装命令与说明执行以下两条命令创建argocd命名空间并安装 Argo CDkubectl create namespace argocd kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yamlinstall.yaml是官方提供的全功能安装清单包含 Argo CD 的 API Server、Repository Server、Application Controller、Redis用于缓存与状态存储、metrics 采集组件、RBAC 资源以及全部 CRDApplication、ApplicationSet 等。对应地本仓库的 manifests/install.yaml 以及目录 manifests/base 下拆分的基础清单就是其同源产物可以在升级或定制时对照查阅。1.2 为什么需要--server-side --force-conflicts这是本步骤最值得理解的两个细节--server-side的必要性部分 Argo CD CRD如 ApplicationSet的 schema 较大在 client-side apply 时会把last-applied-configuration写入 annotation可能超出 Kubernetes 对 annotation 的 262KB 大小限制。server-side apply 不存储该 annotation从而绕开这一限制。--force-conflicts的作用允许本次 apply 接管此前可能由其他工具如 Helm 或先前一次kubectl apply管理的字段。对全新安装是安全的对升级则是必需的。需要注意清单中已明确定义的字段如affinity、env、probes上的自定义修改会被覆盖而清单未涉及的字段如resources的 limits/requests、tolerations会被保留。1.3 安装注意事项[!WARNING] 安装清单中包含引用argocd命名空间的ClusterRoleBinding资源。如果要把 Argo CD 安装到其他命名空间务必同步修改清单中的命名空间引用否则 RBAC 会绑定到错误的命名空间。[!TIP] 如果不需要 Web UI、SSO 和多集群管理能力可以只安装精简的Argo CD Coreheadless 模式。其安装与使用方式见 core.md运行纯 GitOps 引擎、仅暴露Application与ApplicationSet两个 CRD配合argocd login --core让 CLI 在本机临时拉起 API Server 进程完成交互Web UI 则可通过argocd admin dashboard -n argocd在http://localhost:8080本地访问。默认安装使用自签名证书访问前需要额外处理以下三种方式任选其一按照 tls.md 配置正式证书并让客户端 OS 信任它将自签名证书加入客户端 OS 的信任列表在本文后续所有argocdCLI 操作中追加--insecure标志。1.4 默认命名空间与本地 CLI 快捷方式建议把当前 kubectl context 的默认命名空间切到argocd这样后续命令无需反复加-nkubectl config set-context --current --namespaceargocd如果不想与 API Server 走网络交互也可以直接使用argocd login --core配置本地 CLI 访问具体参数含义见 argocd_login.md从而跳过本文的第 35 步。[!NOTE] 默认安装中 Redis 启用了密码认证密码存放在 Argo CD 安装命名空间下的 Kubernetes Secretargocd-redis的auth键中。如果你在 Docker Desktop 或其他本地 Kubernetes 环境运行 Argo CD请参考 running-locally.md 获取针对本地集群的完整安装与配置步骤。2. 下载 Argo CD CLI从官方 Release 页面获取最新版argocdCLI 二进制macOS、Linux 与 WSL 用户可直接用 Homebrew 安装brew install argocdLinux/WSL 用户也可以用 curl 下载并安装指定版本这里以VERSION变量传入例如v3.2.0VERSIONTAG # 从 Release 列表中选择期望的版本号 curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-linux-amd64 sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd rm argocd-linux-amd64更完整的跨平台安装说明Linux、WSL、Intel/Apple Silicon Mac、Windows PowerShell 方式以及自动获取最新 stable 版本的写法见 cli_installation.md。3. 访问 Argo CD默认情况下 Argo CD 不会对外暴露集群外的访问入口可使用以下任一方式打通浏览器或 CLI 到 API Server 的通道3.1 Service Type Load Balancer将argocd-server服务的类型改为LoadBalancerkubectl patch svc argocd-server -n argocd -p {spec: {type: LoadBalancer}}稍等片刻云厂商会为服务分配外部 IP用下面的命令取出kubectl get svc argocd-server -n argocd -ojsonpath{.status.loadBalancer.ingress[0].ip}3.2 Ingress集群内已有 Ingress Controller 时可按 ingress.md 的指引为 Argo CD 配置 Ingress 访问入口含 TLS、SSO 等进阶配置。3.3 Port Forwarding不暴露服务即可连通 API Serverkubectl port-forward svc/argocd-server -n argocd 8080:443随后即可通过https://localhost:8080访问 API Server。[!NOTE] 若 API Server 无法被 CLI 直接访问可让 CLI 借助 port-forward 通道1为每条命令追加--port-forward-namespace argocd或 2设置环境变量export ARGOCD_OPTS--port-forward-namespace argocd。4. 使用 CLI 登录4.1 获取初始管理员密码admin账号的初始密码是自动生成的明文存放在安装命名空间下名为argocd-initial-admin-secret的 Secret 的password字段中可直接用 CLI 取出argocd admin initial-password -n argocd从源码看该命令由 initial_password.go 实现它硬编码了 Secret 名常量initialPasswordSecretName argocd-initial-admin-secret通过 Kubernetes client 读取该 Secret 的Data[password]并打印同时会输出一条提醒——“该密码仅用于首次登录强烈建议用argocd account update-password修改密码”。[!WARNING] 修改密码后建议删除argocd-initial-admin-secret。该 Secret 的唯一用途就是以明文暂存初始密码随时可安全删除若 Argo CD 需要重新生成 admin 密码它会被按需重新创建。4.2 登录与改密使用用户名admin和上一步获取的密码登录argocd login ARGOCD_SERVER登录成功后立即修改密码argocd account update-password5. 注册集群以便部署应用可选本步仅在需要把应用部署到外部集群时才必须执行。如果应用与 Argo CD 运行在同一个集群直接使用https://kubernetes.default.svc作为应用的 Kubernetes API Server 地址即可无需注册。先列出当前 kubeconfig 中所有集群 contextkubectl config get-contexts -o name选择其中一个 context 名并执行例如 docker-desktopargocd cluster add docker-desktop该命令会在目标 kubectl context 的kube-system命名空间中创建一个名为argocd-manager的 ServiceAccount并将其绑定到一个 admin 级别的 ClusterRoleArgo CD 使用该 ServiceAccount 的 token 执行部署与监控等管理任务。从源码看argocd cluster add在 cluster.go 中实现若未显式指定--service-account会默认创建argocd-managerServiceAccount常量ArgoCDManagerServiceAccount且执行前会弹出交互式确认提示将在目标集群创建具有完整权限的 ServiceAccount。[!NOTE]argocd-manager-role的规则可以裁剪比如仅对有限的命名空间、分组、资源种类授予create、update、patch、delete权限但get、list、watch权限必须保持在集群范围否则 Argo CD 无法正常工作。6. 从 Git 仓库创建应用官方提供了一个演示用示例仓库https://github.com/argoproj/argocd-example-apps.git内含 guestbook 示例应用。[!NOTE] 该示例应用可能仅兼容 AMD64 架构。若运行在 ARM64、ARMv7 等其他架构上可能遇到依赖或容器镜像不兼容的问题请验证应用兼容性或自行构建对应架构的镜像。6.1 通过 CLI 创建先把当前 context 的默认命名空间切到argocdkubectl config set-context --current --namespaceargocd然后创建 guestbook 应用argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default各参数含义如下参数说明--repo应用清单所在的 Git 仓库地址--path仓库内清单所在的子目录路径--dest-server目标集群的 Kubernetes API Server 地址同集群部署用https://kubernetes.default.svc--dest-namespace目标命名空间--project应用所属项目默认default本命令未指定使用默认值从源码看argocd app create命令app.go的 Usage 还展示了更多变体例如--helm-chart直接拉取 Helm 仓库中的 chart、--helm-set replicaCount2传 Helm 参数、--kustomize-image指定 Kustomize 镜像覆盖等说明同一个 create 命令支持 Git 清单、Helm、Kustomize、Jsonnet 等多种来源。6.2 通过 UI 创建在浏览器中打开第 3 步获取的 Argo CD 地址并用第 4 步的凭据登录本地环境也可参考 try_argo_cd_locally.md 的本地登录方式然后按以下步骤操作点击 New App按钮应用名填guestbook项目选defaultSync Policy 保持ManualSource 处填写仓库地址https://github.com/argoproj/argocd-example-apps.gitRevision 保持HEADPath 填guestbookDestination 处Cluster URL 填https://kubernetes.default.svcCluster Name 可填in-clusterNamespace 填default点击页面顶部的Create完成创建。6.3 声明式等价物Application 清单UI 与 CLI 创建的应用本质上是同一个argoproj.io/v1alpha1的ApplicationCRD 对象。等价声明式写法可参考 application.yaml核心字段spec.source.repoURL、spec.source.path、spec.source.targetRevision、spec.destination.server、spec.destination.namespace与上述 UI/CLI 参数一一对应该示例还展示了 helm 参数覆盖、valueFiles、releaseName、资源 finalizer级联删除、label 等进阶字段。追求声明式 GitOps 的场景可直接用kubectl apply提交此类清单。7. 同步部署应用7.1 通过 CLI 同步应用创建后先查看其状态$ argocd app get guestbook Name: guestbook Server: https://kubernetes.default.svc Namespace: default URL: https://10.97.164.88/applications/guestbook Repo: https://github.com/argoproj/argocd-example-apps.git Target: Path: guestbook Sync Policy: none Sync Status: OutOfSync from (1ff8a67) Health Status: Missing GROUP KIND NAMESPACE NAME STATUS HEALTH apps Deployment default guestbook-ui OutOfSync Missing Service default guestbook-ui OutOfSync Missing由于应用尚未部署、集群中还没有任何对应资源初始状态为OutOfSync期望状态与集群实际状态不一致。执行同步argocd app sync guestbook该命令会从 Git 仓库拉取清单并执行一次kubectl applyguestbook 随即开始运行。之后便可在 UI 中查看其资源组件、日志、事件与健康状态评估。结合源码补充两点argocd app sync由 app.go 中的NewApplicationSyncCommand实现支持--prune标志argocd app sync guestbook --prune用于删除目标中已不存在的“意外”资源见 app.go--force、--timeout等标志可控制同步行为与等待时长。生产实践上通常会为应用配置自动化同步策略Auto Sync SelfHeal将Sync Policy从none/Manual 升级为 GitOps 全自动闭环。7.2 通过 UI 同步在 Applications 页面点击 guestbook 应用的Sync按钮在弹出的面板中点击Synchronize即可触发同步点击应用本身可以进入详情视图查看资源拓扑树Deployment、Service 及其状态。常见问题与下一步自签名证书导致的 CLI 报错默认安装证书不被信任按第 1.3 节三种方式任选其一处理配置证书 / 信任自签名证书 / CLI 加--insecure。访问 API Server 失败确认第 3 步的暴露方式已生效CLI 无法直连时使用--port-forward-namespace argocd或ARGOCD_OPTS环境变量走 port-forward。argocd app sync后资源被意外删除的风险默认不会删除只有显式加--prune或应用配置了 prune 策略才会清理多余资源。忘记初始密码若argocd-initial-admin-secret已被删除Argo CD 会在需要时重新生成 admin 密码可再次执行argocd admin initial-password获取。完成上述七步后你已经跑通了一条完整的 GitOps 闭环Git 仓库 → Argo CD 拉取与比对 → 集群同步部署 → 状态回看。接下来可以继续深入多集群管理见 cluster-management.md、声明式安装与引导见 declarative-setup.md、应用健康评估机制见 health.md、本地开发调试见 debugging-locally.md。【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考