K3s部署ArgoCD

在Kubernetes生态中，ArgoCD作为主流的声明式GitOps工具，能够实现应用的自动化部署、同步与管理，而K3s作为轻量级Kubernetes发行版，凭借低资源占用、快速部署的优势，广泛应用于边缘计算、小集群场景。Traefik作为K3s默认集成的Ingress Controller，具备自动发现、动态配置、SSL证书自动签发等特性，是实现ArgoCD外部访问的最优代理方案之一。

本文将综合梳理K3s环境下，通过Helm工具部署ArgoCD，并利用Traefik实现反向代理的完整流程，重点解决“配置一体化”“HTTPS访问”“轻量适配”三大核心需求，同时提供常见问题排查方案，适用于运维工程师、开发人员快速落地GitOps实践。

一、前置条件准备

在开始部署前，需确保环境满足以下条件，避免因依赖缺失导致部署失败：

1. K3s集群正常运行：已完成K3s集群部署（单节点或多节点均可），且集群状态健康。K3s默认集成Traefik v2+，无需额外安装Ingress Controller，可通过kubectl get pods -n kube-system -l app=traefik验证Traefik是否正常运行。

2. 工具环境就绪：本地已安装Helm 3.8+和kubectl工具，且kubectl已配置好K3s集群的访问权限（可通过复制K3s节点的/etc/rancher/k3s/k3s.yaml文件到本地~/.kube/config实现）。

3. 域名与端口配置：拥有一个可解析的域名（如argocd.your-domain.com），并将域名A记录指向K3s节点的公网IP（多节点集群建议指向负载均衡IP）；同时开放K3s节点的80/443端口（云服务器需配置安全组，物理机需开放防火墙规则）。

二、核心部署思路

本次部署采用“Helm一键部署+values.yaml统一配置”的方案，核心思路如下：

1. 通过Helm添加ArgoCD官方仓库，确保获取稳定的Chart版本；

2. 编写统一的values.yaml文件，整合ArgoCD基础配置（轻量适配、服务类型）与Traefik代理配置（IngressRoute、HTTPS重定向、SSL证书）；

3. 利用Helm的extraObjects特性，在部署ArgoCD的同时，自动注入Traefik所需的Middleware和IngressRoute资源，实现配置一体化；

4. 验证部署状态，配置ArgoCD访问权限，完成GitOps工具链的落地。

该方案的优势在于，无需单独创建Ingress配置文件，后续升级、重装ArgoCD时，仅需维护一份values.yaml，大幅提升运维效率，同时符合Kubernetes声明式管理的核心理念。

三、详细部署步骤

3.1 添加ArgoCD Helm仓库

首先添加ArgoCD官方Helm仓库，并更新本地仓库索引，确保获取最新的Chart版本（本次选用稳定版5.46.7，对应ArgoCD v2.8.4，兼容性最优）：

# 添加ArgoCD官方Helm仓库
helm repo add argo https://argoproj.github.io/argo-helm

# 更新本地仓库索引，同步最新Chart信息
helm repo update

3.2 创建ArgoCD独立命名空间

为了便于资源隔离和管理，建议将ArgoCD部署在独立的命名空间（argocd）中，执行以下命令创建命名空间：

kubectl create namespace argocd

3.3 编写核心values.yaml配置文件

创建argocd-values.yaml文件，该文件是本次部署的核心，整合了ArgoCD基础配置、Traefik代理配置、SSL证书自动签发配置，关键部分已添加详细注释，只需替换域名和邮箱即可直接使用：

# ==============================================
# ArgoCD 基础配置（适配K3s轻量环境）
# ==============================================
# 全局配置，指定ArgoCD版本，避免版本兼容问题
global:
  image:
    tag: v2.8.4

# ArgoCD Server核心配置（关键：设置为ClusterIP，由Traefik代理）
server:
  service:
    type: ClusterIP # 禁止暴露NodePort，避免直接对外暴露端口
    ports:
      http: 80
      https: 443
  insecure: false # 开启HTTPS，ArgoCD Server默认监听443端口
  ingress:
    enabled: false # 关闭官方默认的传统Ingress，改用Traefik IngressRoute

# 轻量配置：单副本部署，适配K3s资源有限的场景
controller:
  replicas: 1
repoServer:
  replicas: 1
applicationSet:
  controller:
    replicas: 1

# 禁用不必要组件，进一步降低资源占用（按需选择）
notifications:
  enabled: false # 禁用通知组件，无需邮件/钉钉通知可关闭
dex:
  enabled: false # 禁用dex认证，无需多租户管理可关闭
redis:
  ha:
    enabled: false # 单副本Redis，避免高可用配置占用过多资源

# ==============================================
# Traefik 代理配置（核心：注入IngressRoute和中间件）
# ==============================================
extraObjects:
  # 中间件：HTTP请求301永久重定向到HTTPS，提升安全性和SEO友好度
  - apiVersion: traefik.containo.us/v1alpha1
    kind: Middleware
    metadata:
      name: argocd-redirect-https
      namespace: argocd
    spec:
      redirectScheme:
        scheme: https
        permanent: true

  # IngressRoute：HTTP 80端口，匹配域名并跳转到HTTPS
  - apiVersion: traefik.containo.us/v1alpha1
    kind: IngressRoute
    metadata:
      name: argocd-ingressroute-http
      namespace: argocd
      annotations:
        kubernetes.io/ingress.class: traefik # 指定Traefik作为Ingress控制器
    spec:
      entryPoints:
        - web # 对应Traefik的80端口入口
      routes:
        - match: Host(`argocd.your-domain.com`) # 替换为你的ArgoCD访问域名
          kind: Rule
          priority: 10
          services:
            - name: argocd-server
              port: 80
          middlewares:
            - name: argocd-redirect-https # 引用重定向中间件

  # IngressRoute：HTTPS 443端口，核心代理配置
  - apiVersion: traefik.containo.us/v1alpha1
    kind: IngressRoute
    metadata:
      name: argocd-ingressroute-https
      namespace: argocd
      annotations:
        kubernetes.io/ingress.class: traefik
    spec:
      entryPoints:
        - websecure # 对应Traefik的443端口入口
      routes:
        - match: Host(`argocd.your-domain.com`) # 替换为你的ArgoCD访问域名
          kind: Rule
          priority: 10
          services:
            - name: argocd-server
              port: 443
              scheme: https # 关键：指定代理协议为HTTPS
              tls:
                insecureSkipVerify: true # 跳过ArgoCD自签证书验证（外部用正式证书）
      tls:
        certResolver: default # 引用Traefik的Let's Encrypt证书解析器

# ==============================================
# Traefik SSL证书配置（自动签发Let's Encrypt免费证书）
# 若已配置过Traefik的certResolver，可删除此部分
# ==============================================
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: traefik
      namespace: kube-system
      labels:
        app: traefik
    data:
      traefik.yaml: |
        api:
          insecure: false
        entryPoints:
          web:
            address: :80
          websecure:
            address: :443
        providers:
          kubernetesCRD:
            enabled: true # 启用Traefik CRD支持（IngressRoute依赖）
          kubernetesIngress:
            enabled: true
        http:
          tls:
            certResolver:
              default:
                acme:
                  email: your-email@xxx.com # 替换为你的有效邮箱（证书过期提醒）
                  storage: /data/acme.json # 证书存储路径
                  httpChallenge:
                    entryPoint: web # HTTP-01挑战，无需开放额外端口

关键配置说明

• server.service.type: ClusterIP：核心配置，将ArgoCD Server的服务类型设为ClusterIP，避免直接暴露端口，由Traefik统一代理，提升安全性；

• extraObjects：Helm的通用特性，用于注入Chart未内置的Kubernetes资源，此处注入Traefik的Middleware（重定向）和IngressRoute（代理规则），实现配置一体化；

• scheme: https + insecureSkipVerify: true：ArgoCD Server默认使用自签证书监听443端口，Traefik代理时需指定HTTPS协议，并跳过自签证书验证，而外部用户访问的是Traefik签发的Let’s Encrypt正式证书，无安全警告；

• Traefik ACME配置：自动签发免费SSL证书，无需手动上传证书，HTTP-01挑战方式无需开放额外端口，适配大多数场景。

3.4 Helm一键部署ArgoCD

执行以下命令，基于编写好的values.yaml文件部署ArgoCD，全程无需额外执行kubectl apply配置Ingress：

helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 5.46.7 \ # 与values.yaml中的ArgoCD版本匹配
  -f argocd-values.yaml

部署完成后，等待所有Pod启动，可通过以下命令监控部署状态（全部显示Running即为部署成功）：

# 查看ArgoCD命名空间下的Pod状态
kubectl get pods -n argocd -w

# 查看Traefik注入的Middleware和IngressRoute资源
kubectl get middleware -n argocd
kubectl get ingressroute -n argocd

3.5 配置ArgoCD访问权限并登录

3.5.1 提取初始管理员密码

ArgoCD部署后，会自动生成初始管理员密码，存储在argocd-initial-admin-secret这个Secret中，执行以下命令解码获取：

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

3.5.2 浏览器访问ArgoCD UI

在浏览器中输入配置的域名（如https://argocd.your-domain.com），出现ArgoCD登录页面后，输入以下信息登录：

• 用户名：admin（固定初始用户名）；

• 密码：上述步骤提取的初始密码。

⚠️ 重要提醒：登录成功后，务必立即修改初始密码（左侧菜单栏→User Info→Update Password），避免密码泄露导致集群安全风险。

3.5.3 ArgoCD CLI通过Traefik代理访问（可选）

若需要通过CLI工具操作ArgoCD，可安装ArgoCD CLI并通过Traefik代理的域名登录，核心是添加--grpc-web参数（适配Traefik的gRPC代理）：

# Linux系统安装ArgoCD CLI
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 755 argocd-linux-amd64 /usr/local/bin/argocd
rm -f argocd-linux-amd64

# MacOS系统安装
brew install argocd

# 通过Traefik代理的域名登录
argocd login argocd.your-domain.com --grpc-web

登录成功后，即可通过CLI执行应用同步、集群管理等操作，实现命令行与UI双端管理。

四、后续维护与升级

4.1 配置修改与重装

若需要修改ArgoCD或Traefik的配置，只需编辑argocd-values.yaml文件，然后执行以下命令更新部署：

helm upgrade argocd argo/argo-cd -n argocd -f argocd-values.yaml --version 5.46.7

若需重装ArgoCD，先卸载现有部署，再重新执行安装命令：

# 卸载ArgoCD
helm uninstall argocd -n argocd

# 重新安装
helm install argocd argo/argo-cd -n argocd -f argocd-values.yaml --version 5.46.7

4.2 证书维护

Let’s Encrypt证书默认有效期为90天，Traefik会自动完成证书续期，无需手动操作。若证书出现异常，可通过以下命令重启Traefik Pod，强制重新签发证书：

kubectl delete pod -n kube-system -l app=traefik

五、常见问题排查

5.1 域名访问404/503错误

• 检查values.yaml中的域名是否与实际访问的域名一致，域名A记录是否正确解析到K3s节点IP；

• 检查ArgoCD Server Pod是否正常运行，可通过kubectl logs -n argocd argocd-server-xxx查看日志；

• 检查K3s节点的80/443端口是否开放，云服务器需确认安全组规则是否放行；

• 查看IngressRoute状态，通过kubectl describe ingressroute argocd-ingressroute-https -n argocd排查代理规则是否配置正确。

5.2 HTTPS证书无效/安全警告

• 等待1-2分钟，Let’s Encrypt证书签发需要一定时间，刷新页面即可；

• 检查values.yaml中的邮箱是否有效，域名是否完成解析，HTTP-01挑战是否成功；

• 重启Traefik Pod，强制重新加载证书配置。

5.3 ArgoCD UI登录后白屏/加载失败

• 确认values.yaml中IngressRoute的scheme: https和insecureSkipVerify: true已配置，避免代理协议不匹配；

• 检查argocd-server的端口是否为443，而非80；

• 清除浏览器缓存，或使用无痕模式访问，避免缓存导致的加载异常。

5.4 extraObjects注入资源失败

• 检查values.yaml的YAML语法是否正确，可使用yamllint argocd-values.yaml工具验证；

• 确认K3s集群已安装Traefik CRD，可通过kubectl get crd | grep traefik.containo.us查看，若缺失可执行以下命令安装：

kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v2.10/docs/content/reference/dynamic-configuration/kubernetes-crd-definitions.yaml

六、总结

本文实现了K3s环境下ArgoCD的Helm部署与Traefik反向代理的一体化配置，核心亮点在于通过values.yaml整合所有配置，无需额外编写Ingress文件，既适配了K3s的轻量特性，又保证了部署的便捷性和可维护性。

通过本次实践，可快速搭建一套基于GitOps理念的应用部署平台，实现应用的自动化同步与管理，同时借助Traefik的反向代理和SSL证书自动签发功能，保障ArgoCD的安全访问。该方案适用于边缘计算、小型集群、测试环境等场景，也可根据生产环境需求，调整副本数、开启高可用、配置多租户认证等，进一步优化部署架构。

后续可基于ArgoCD实现应用的GitOps部署，将应用配置存储在Git仓库中，实现“代码即配置”，大幅提升应用部署的一致性和可追溯性，降低运维成本。

（注：文档部分内容可能由 AI 生成）