📚 课程目录第4章 Argo CD安装与配置

4. 安装与配置：在 Kubernetes 集群中安装 Argo CD，配置 Ingress 与 TLS

本章将指导你在生产级 Kubernetes 集群中完成 Argo CD 的安装，并配置安全的 Ingress 与 TLS 终止。正确的安装与网络配置是后续多环境部署与性能调优的基础。

4.1 安装前提与版本选择

组件	推荐版本 / 要求	说明
Kubernetes 集群	v1.24+	建议使用 EKS / AKS / GKE 或自建集群
kubectl	v1.24+	与集群版本偏差不超过 ±1 个次要版本
Helm	v3.10+	推荐使用 Helm 安装 Argo CD
Ingress Controller	nginx-ingress / traefik / AWS ALB	必须支持 TLS 终止
证书管理	cert-manager 或手动上传 Secret	生产环境建议自动签发

版本对齐建议：Argo CD 的 API 版本与 Kubernetes 版本存在依赖关系。安装前请查阅 https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/ 确认兼容性矩阵。

4.2 使用 Helm 安装 Argo CD

Helm 是官方推荐的安装方式，便于版本管理与参数化配置。

4.2.1 添加 Helm 仓库并创建命名空间

# 添加 Argo CD Helm 仓库
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# 创建专用命名空间
kubectl create namespace argocd

4.2.2 使用 values.yaml 自定义安装

创建 argocd-values.yaml 文件，包含核心配置：

# argocd-values.yaml
global:
  domain: argocd.example.com

server:
  ingress:
    enabled: true
    ingressClassName: nginx
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
    hosts:
      - argocd.example.com
    tls:
      - hosts:
          - argocd.example.com
        secretName: argocd-tls

configs:
  params:
    server.insecure: false
    server.rootpath: ""

controller:
  replicas: 1
  resources:
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

redis:
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 250m
      memory: 256Mi

4.2.3 执行安装

helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  -f argocd-values.yaml \
  --version 5.51.6

  安装验证：执行 kubectl get pods -n argocd，确认所有 Pod 处于 Running 状态。核心组件包括 argocd-server、argocd-repo-server、argocd-application-controller 和 argocd-redis。

4.3 配置 Ingress 与 TLS

Ingress 是外部流量进入 Argo CD 的网关。生产环境必须启用 TLS 加密。

4.3.1 Ingress 架构概览

4.3.2 手动创建 TLS Secret（无 cert-manager 时）

kubectl create secret tls argocd-tls \
  --namespace argocd \
  --cert=/path/to/tls.crt \
  --key=/path/to/tls.key

4.3.3 使用 cert-manager 自动签发

安装 cert-manager 后，创建 ClusterIssuer 和 Certificate 资源：

# ClusterIssuer 示例
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - http01:
          ingress:
            class: nginx

注意：cert-manager 的 HTTP-01 验证要求 Ingress 域名必须能从公网解析。如果集群位于私有网络，请使用 DNS-01 验证方式。

4.4 验证安装与访问

4.4.1 获取初始管理员密码

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

4.4.2 访问 Argo CD Web UI

打开浏览器访问 https://argocd.example.com，使用 admin 和上述密码登录。

4.4.3 使用 CLI 登录

argocd login argocd.example.com --username admin --password <password> --grpc-web

4.5 安装后关键配置项

配置项	推荐值	说明
`server.insecure`	`false`	禁止 HTTP 明文访问
`server.rootpath`	`/`	根路径，多租户场景可改为 `/argo-cd`
`configs.params.server.disable.auth`	`false`	生产环境必须保持认证开启
`controller.replicas`	`2`（生产）	高可用部署时建议 ≥2
`redis.replicas`	`3`（生产）	Redis 集群模式，避免单点故障

4.6 常见安装问题排查

Pod 启动失败：检查 kubectl describe pod <pod-name> -n argocd，常见原因为资源不足或镜像拉取失败。
Ingress 返回 502：确认 argocd-server Service 的端口映射正确（默认 80→8080，443→8080）。
TLS 证书未生效：检查 Secret 是否存在且 Ingress 的 tls.secretName 引用正确。
CLI 登录失败：添加 --grpc-web 参数，因为 Argo CD API 默认使用 gRPC。