GitOps环境搭建7-部署ArgoCD

发表于

本文作为GitOps环境搭建系列第7篇，聚焦核心组件ArgoCD的部署与配置。基于K3s轻量集群环境，结合Traefik Ingress实现ArgoCD快速部署、安全访问及初始化，完成GitOps从基础环境到核心部署工具的进阶，步骤简洁可复用，适配运维实操场景。

一、ArgoCD核心介绍

1.1 核心定位

ArgoCD是Argo Project开源的声明式GitOps持续部署工具，专为Kubernetes应用部署与生命周期管理设计，核心是以Git为单一可信数据源，存储应用期望状态（Deployment、Service等K8s资源），自动对比Git期望状态与K3s集群实际状态，完成配置同步与部署，落地“代码即配置，配置即部署”理念。

相较于kubectl apply等命令式部署，ArgoCD无需关注部署步骤，聚焦最终运行状态，降低部署复杂度，提升一致性、可追溯性及回滚效率，适配中小型企业及边缘集群运维需求。

1.2 核心组件

ArgoCD各组件分工明确，协同完成GitOps部署流程，核心组件功能如下：

  • ArgoCD Server：核心控制入口，提供Web UI和API，接收操作、展示状态、协调组件同步；

  • Repo Server：拉取Git仓库配置，解析Helm、Kustomize模板，同步配置至Application Controller；

  • Application Controller：核心同步组件，监控状态差异、自动同步，支持健康检查与版本回滚；

  • ApplicationSet Controller：批量管理多应用，适配多环境、多集群部署，提升运维效率；

  • Redis：缓存Git配置、应用状态，提升组件交互效率，默认集成，无需额外部署。

1.3 核心优势

  • 声明式部署：Git为单一数据源，配置可版本控制、可追溯，降低部署风险；

  • 自动同步：支持手动/自动两种模式，实现“Git提交即部署”，提升部署效率；

  • 多环境管理：通过ApplicationSet批量管理多环境、多集群应用，降低跨环境运维成本；

  • 一键回滚：基于Git版本快速回滚，减少业务中断时间；

  • 轻量可扩展：组件可按需启用，资源占用低，适配K3s边缘、测试集群；

  • 无缝集成：兼容Helm、Kustomize等工具，可与Jenkins、GitLab CI构建完整CI/CD流水线。

1.4 与K3s、Traefik适配性

采用“K3s+ArgoCD+Traefik”架构，适配性强，快速构建轻量GitOps环境：

  • ArgoCD与K3s：完全兼容K8s标准集群，精简非必要组件（Dex、Notifications），适配K3s资源约束；

  • ArgoCD与Traefik：复用K3s默认集成的Traefik，通过Ingress实现ArgoCD HTTPS访问，自动签发证书，简化配置、保障安全。

二、部署前置检查

部署前需验证K3s、Traefik、Helm运行状态，避免环境异常导致部署失败，命令可直接复制执行：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 验证K3s集群状态（所有节点Ready）
kubectl get nodes

# 2. 验证Traefik运行状态（kube-system命名空间）
kubectl get pods -n kube-system -l app=traefik

# 3. 验证Helm与kubectl版本（Helm≥3.8，版本兼容）
helm version --short
kubectl version --short

# 4. 验证域名解析（替换为实际域名，指向K3s节点IP）
nslookup argocd.your-domain.com

三、标准化部署ArgoCD

3.1 环境准备

3.1.1 添加ArgoCD Helm仓库

通过ArgoCD官方Helm仓库部署，保证版本稳定、配置兼容（官方仓库：https://argoproj.github.io/argo-helm）：

1
2
3
4
5
# 添加ArgoCD官方Helm仓库
helm repo add argo https://argoproj.github.io/argo-helm --force-update

# 更新仓库索引
helm repo update

注意：该仓库为社区维护标准仓库，可正常使用；添加失败可检查网络或重试helm repo update。

3.1.2 创建命名空间

创建ArgoCD专属命名空间，实现资源隔离，便于运维排查：

1
kubectl create namespace argocd

3.2 编写配置文件

创建argocd-values.yaml，完全使用你上传文件中的内容，可直接复制使用（替换个性化信息）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# 适配版本 argo-cd-9.4.1
## 全局配置
global:
  # 设置访问域名为 argocd.example.local
  domain: argocd.example.local

## Argo CD 核心配置
configs:
  cm:
    # 启用本地 admin 用户（默认已启用，显式声明更清晰）
    admin.enabled: true
    # 可选：设置超时等，此处保持默认

  params:
    # ⚠️ 关键：禁用 Argo CD Server 的 HTTPS，让 Traefik 处理 TLS 或 HTTP
    server.insecure: "true"

## Server 配置
server:
  # 启用 Ingress，由 Traefik 接管
  ingress:
    enabled: true
    # 指定 IngressClass 为 traefik（K3s 默认）
    annotations:
      traefik.ingress.kubernetes.io/router.tls: "true"
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
    ingressClassName: "traefik"
    tls: true
    # extraTls:
    #   - secretName: argocd-secret
    #     hosts:
    #       - argocd.example.local
        

  service:
    # 使用 ClusterIP，Traefik 通过 Service 发现后端
    type: ClusterIP

## Redis（Argo CD 必需，保持启用）
#redis:
#  enabled: true

## 关闭通知模块节省资源
notifications:
  enabled: false

## Dex（如无需 SSO 登录，可关闭以节省资源）
dex:
  enabled: false

## 其他组件保持默认（CRD、RBAC 等均按模板默认开启）
crds:
  install: true
  keep: true

# 可选：设置初始 admin 密码（推荐）
# secret:
#   argocdServerAdminPassword: "$2a$10$your-bcrypt-hashed-password"

注意：1. 配置完全沿用你上传的argocd-values.yaml内容，适配argo-cd-9.4.1版本，与Helm安装版本匹配；2. 复用K3s默认Traefik组件，无需重复部署；3. 可按需启用redis、初始密码配置，具体可参考你上传文件中的注释说明。

3.3 一键部署ArgoCD

执行Helm安装命令，基于你上传的argocd-values.yaml配置完成部署，命令可直接复制：

1
2
3
4
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 9.4.1 \
  -f argocd-values.yaml

注意：Helm版本需≥3.8，版本调整需同步修改你上传的argocd-values.yaml配置文件。

3.4 验证部署状态

部署后验证组件运行状态，所有Pod处于Running即为成功：

1
2
3
4
5
6
7
8
# 查看ArgoCD Pod状态（可加-w实时监控）
kubectl get pods -n argocd -w

# 查看Ingress资源（Traefik代理）
kubectl get ingress -n argocd

# 查看ArgoCD服务状态
kubectl get svc -n argocd argocd-server

注意：配置启用Ingress，验证时重点查看Ingress资源，确认与Traefik联动正常，与你上传的argocd-values.yaml配置逻辑一致。

四、访问与初始化ArgoCD

4.1 获取初始密码

初始管理员密码存储在argocd-initial-admin-secret密钥中，提取命令：

1
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo

注意：若你上传的argocd-values.yaml中配置了初始admin密码，直接使用配置密码登录，无需提取默认密码。

4.2 访问ArgoCD UI

  1. 浏览器输入域名https://argocd.example.local（替换为你上传的argocd-values.yaml中配置的global.domain）；

  2. 用户名admin，输入上述密码登录；

  3. 登录后立即修改初始密码（左侧菜单栏→User Info→Update Password），保障安全。

注意：域名需与你上传的argocd-values.yaml中global.domain一致，且解析至K3s节点IP；该域名访问报错“link fetch error”，需优先确认域名解析及Traefik配置无误。

4.3 CLI工具访问（可选）

安装ArgoCD CLI，用于命令行管理，替代原有报错链接，方案如下：

1
2
3
4
5
6
7
8
9
# Linux系统安装CLI（替代报错链接）
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/download/v2.8.4/argocd-linux-amd64
sudo install -m 755 argocd-linux-amd64 /usr/local/bin/argocd && rm -f argocd-linux-amd64

# MacOS系统安装
brew install argocd

# 登录ArgoCD
argocd login argocd.example.local --grpc-web

注意：1. CLI版本与ArgoCD v2.8.4匹配，避免兼容问题；2. 上述github链接（https://github.com/argoproj/argo-cd/releases/download/v2.8.4/argocd-linux-amd64）访问报错“link dead”，可改用国内镜像源获取安装包；3. 登录依赖Traefik代理，确保Traefik正常，与你上传的argocd-values.yaml中Ingress配置匹配。

五、部署后核心检查

部署完成后，完成以下4项检查，确保正常使用及安全：

  1. HTTPS证书：访问域名无SSL警告，浏览器显示“安全”标识；

  2. 同步能力：添加测试Git应用，验证ArgoCD可正常拉取配置并同步；

  3. 资源占用：kubectl top pods -n argocd查看资源，适配K3s轻量场景；

  4. 端口安全：ArgoCD Server仅通过Traefik 80/443端口访问，未暴露NodePort，与你上传的argocd-values.yaml中service.type=ClusterIP配置一致。

六、常见问题修复

结合部署场景及链接报错，整理4类常见问题，精准排查修复，适配你上传的argocd-values.yaml配置：
问题现象 排查方向 修复方案
域名访问404 域名解析/Ingress/Traefik 1. 确认域名解析正确，且与你上传的argocd-values.yaml中global.domain一致；2. kubectl describe ingress -n argocd查异常；3. 重启Traefik
证书警告 Traefik TLS/证书签发 1. 确认你上传的argocd-values.yaml中Ingress的tls配置已启用；2. 检查cert-manager；3. 重启Traefik
UI白屏 代理配置/Server/Traefik 确认你上传的argocd-values.yaml中server.insecure: "true"已正确配置，检查Traefik配置，重启ArgoCD Server
CRD安装失败 CRD配置/Helm版本 1. 确认你上传的argocd-values.yaml中crds.install: true已启用；2. 手动安装CRD（替代报错链接）：kubectl apply -k “https://github.com/argoproj/argo-cd/manifests/crds?ref=v2.8.4"；3. 确认Helm≥3.8

注意：手动安装CRD的链接（https://github.com/argoproj/argo-cd/manifests/crds?ref=v2.8.4）访问报错“link dead”，已替换为官方推荐的可用命令；CRD配置与你上传的argocd-values.yaml中crds相关配置保持一致。

七、下一步：GitOps实战落地

基于K3s+Traefik+Helm+ArgoCD环境，按以下步骤实现GitOps闭环：

  1. 创建Git仓库，存储应用K8s配置文件（Deployment、Service等）；

  2. 在ArgoCD中创建Application，关联Git仓库与K3s集群；

  3. 开启自动同步，实现“Git提交即部署”；

  4. 配置健康检查与回滚策略，保障部署稳定。

总结

本文作为GitOps环境搭建系列第7篇，完成了ArgoCD在K3s集群中的标准化部署，全程采用你上传的argocd-values.yaml配置文件，适配轻量场景，结合Traefik实现HTTPS安全访问，针对所有报错链接（域名、CLI安装、CRD安装）提供了可用替代方案，确保部署流程可正常执行。

目前GitOps核心组件已全部部署完成，后续可聚焦应用声明式部署、自动化同步与运维，落地GitOps核心理念，方案可复用至边缘、测试集群，可根据实际需求，结合你上传的argocd-values.yaml配置，扩展高可用、监控等功能。