基于K3s搭建GitOps环境7-部署ArgoCD

发表于 更新于

一、核心定位

本文作为GitOps环境搭建系列的第七篇，聚焦核心组件ArgoCD的部署与配置。ArgoCD是Argo Project开源的声明式GitOps持续部署工具，专为Kubernetes应用部署与生命周期管理设计。

在GitOps环境中，ArgoCD扮演”部署自动化中枢”角色，作为GitOps流程的核心执行引擎，实现”Git为单一可信数据源”的理念。ArgoCD自动对比Git仓库中的期望状态与K3s集群中的实际状态，完成配置同步与部署，实现从代码到部署的完整自动化。

二、部署前置检查

部署前需验证K3s集群状态及前序组件运行情况：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证Traefik运行状态
kubectl get pods -n kube-system -l app=traefik

# 3. 验证cert-manager运行状态
kubectl get pods -n cert-manager

# 4. 验证Gitea运行状态
kubectl get pods -n gitea

# 5. 验证Helm可用性
helm version --short

# 6. 验证域名解析
nslookup argocd.example.io

前置条件检查清单：

  • K3s集群运行正常
  • Traefik反向代理可用
  • cert-manager证书管理可用
  • Gitea代码仓库可用（可选，用于测试）
  • 域名argocd.example.io已解析至K3s节点IP
  • Helm工具可用

三、标准化部署ArgoCD

3.1 环境准备

3.1.1 添加ArgoCD Helm仓库

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

3.1.2 创建命名空间

1
2
# 创建ArgoCD专属命名空间
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
# argocd-values.yaml
# 参考：https://gitee.com/Chemmy/kube-template/blob/master/devops/ArgoCD/argocd-values.yaml

## 全局配置
global:
  # 设置访问域名为 argocd.example.io
  domain: argocd.example.io

## Argo CD 核心配置
configs:
  cm:
    # 启用本地 admin 用户
    admin.enabled: true

  params:
    # 禁用 Argo CD Server 的 HTTPS，让 Traefik 处理 TLS
    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"
    hosts:
      - argocd.example.io

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

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

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

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

## 其他组件保持默认
crds:
  install: true
  keep: true

3.3 一键部署ArgoCD

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 部署ArgoCD
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 9.4.1 \
  -f argocd-values.yaml

# 或使用在线配置
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 9.4.1 \
  --set global.domain=argocd.example.io \
  --set server.ingress.enabled=true \
  --set server.ingress.ingressClassName=traefik \
  --set server.ingress.hosts[0]=argocd.example.io \
  --set server.insecure=true \
  --set notifications.enabled=false \
  --set dex.enabled=false

3.4 验证部署状态

1
2
3
4
5
6
7
8
9
10
11
# 查看ArgoCD Pod状态
kubectl get pods -n argocd -w

# 查看Ingress资源
kubectl get ingress -n argocd

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

# 查看部署完成状态
kubectl wait --for=condition=Ready pods -l app.kubernetes.io/name=argocd-server -n argocd --timeout=300s

四、配置HTTPS访问

4.1 创建ArgoCD证书

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# argocd-certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: argocd-cert
  namespace: argocd
spec:
  secretName: argocd-tls-secret
  issuerRef:
    name: selfsigned-cluster-issuer
    kind: ClusterIssuer
  commonName: argocd.example.io
  dnsNames:
  - argocd.example.io
  duration: 2160h
  renewBefore: 360h
  privateKey:
    algorithm: RSA
    size: 2048
  usages:
  - server auth

4.2 配置IngressRoute

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# argocd-ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: argocd-websecure
  namespace: argocd
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`argocd.example.io`) && PathPrefix(`/`)
      kind: Rule
      services:
        - name: argocd-server
          passHostHeader: true
          port: 80
  tls:
    secretName: argocd-tls-secret

4.3 应用HTTPS配置

1
2
3
4
5
6
7
# 应用证书和路由配置
kubectl apply -f argocd-certificate.yaml
kubectl apply -f argocd-ingressroute.yaml

# 验证证书状态
kubectl get certificate -n argocd
kubectl describe certificate argocd-cert -n argocd

五、访问与初始化ArgoCD

5.1 获取初始密码

1
2
3
4
5
6
# 获取初始管理员密码
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo

# 或使用更安全的方式
ARGOCD_PASSWORD=$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d)
echo "ArgoCD初始密码: $ARGOCD_PASSWORD"

5.2 访问ArgoCD Web UI

  1. 浏览器访问：https://argocd.example.io
  2. 用户名：admin
  3. 密码：使用上述获取的初始密码
  4. 首次登录后立即修改密码（User Info → Update Password）

5.3 CLI工具安装与配置（可选）

1
2
3
4
5
6
7
8
9
10
11
12
13
# 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

# 验证安装
argocd version --client

# 登录ArgoCD
argocd login argocd.example.io --grpc-web --username admin --password $ARGOCD_PASSWORD

# 或使用token登录（更安全）
argocd account generate-token --account admin

六、验证部署结果

6.1 验证组件状态

1
2
3
4
5
6
7
8
9
10
11
# 查看所有ArgoCD组件状态
kubectl get all -n argocd

# 查看证书和路由状态
kubectl get certificate,ingressroute -n argocd

# 查看ArgoCD日志
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server --tail=50

# 测试HTTPS访问
curl -k https://argocd.example.io

6.2 测试GitOps功能

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
# 创建测试应用（使用Gitea仓库）
cat > test-application.yaml << EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: test-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitea.example.io/gitea_admin/test-repo.git
    targetRevision: HEAD
    path: k8s/
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF

# 应用测试配置
kubectl apply -f test-application.yaml

# 查看应用状态
kubectl get application -n argocd
argocd app get test-app

6.3 清理测试资源

1
2
# 清理测试应用
kubectl delete -f test-application.yaml

七、生产环境配置建议

7.1 安全加固

1
2
3
4
5
6
7
8
9
10
# 在argocd-values.yaml中添加安全配置
server:
  extraArgs:
    - --insecure
    - --disable-auth
    - --rootpath=/argocd
  ingress:
    annotations:
      traefik.ingress.kubernetes.io/whitelist-source-range: "192.168.0.0/16,10.0.0.0/8"
      traefik.ingress.kubernetes.io/rate-limit: "10"

7.2 资源优化

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
# 调整资源限制
controller:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

server:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

repoServer:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

7.3 监控配置

1
2
3
4
5
6
7
8
9
10
# 启用监控
controller:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

server:
  metrics:
    enabled: true

八、日常运维命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 查看ArgoCD状态
argocd version
argocd cluster list

# 管理应用
argocd app list
argocd app get <app-name>
argocd app sync <app-name>
argocd app history <app-name>
argocd app rollback <app-name> --id <revision-id>

# 管理项目
argocd proj list
argocd proj get <project-name>

# 查看日志
kubectl logs -f deployment/argocd-server -n argocd
kubectl logs -f deployment/argocd-repo-server -n argocd
kubectl logs -f deployment/argocd-application-controller -n argocd

# 重启组件
kubectl rollout restart deployment argocd-server -n argocd
kubectl rollout restart deployment argocd-repo-server -n argocd
kubectl rollout restart deployment argocd-application-controller -n argocd

九、常见问题修复

问题现象 排查方向 修复方案
无法访问Web UI 域名解析/IngressRoute 检查域名解析，验证IngressRoute配置，查看Traefik日志
证书警告或错误 证书签发/Secret 检查cert-manager状态，验证证书Secret是否存在
无法同步Git仓库 网络/认证 检查网络连通性，配置SSH密钥或访问令牌
资源同步失败 权限/资源配置 检查ServiceAccount权限，验证资源配置格式
CLI登录失败 网络/认证 检查网络代理，验证用户名密码，使用–grpc-web参数
内存占用过高 资源限制/应用数量 调整资源限制，减少监控的应用数量

十、配置参考

所有ArgoCD配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/ArgoCD

该目录包含：

  • ArgoCD Helm values配置
  • 证书和路由配置
  • 生产环境优化配置
  • 示例应用配置
  • 监控和备份脚本

总结

本文完成了ArgoCD在K3s集群中的标准化部署，实现了GitOps核心组件的完整功能。ArgoCD作为GitOps环境的核心执行引擎，为自动化部署提供了强大的能力。

部署完成后，建议创建测试应用验证同步功能，配置自动同步策略，并设置适当的资源限制。下一篇文章将部署Tekton CI流水线，为GitOps环境提供持续集成能力。