2. Argo CD 安装与基础配置：Helm Chart安装、CLI工具安装、初始密码获取、Ingress配置、TLS证书配置

本章将完整演示从零部署 Argo CD 生产级实例的全流程。我们将采用 Helm Chart 作为安装载体，配合 CLI 工具 实现运维管理，并完成 Ingress 与 TLS 证书 的配置，确保外部流量安全接入。所有操作均基于 Kubernetes 1.28+ 环境。

2.1 安装架构概览

下图展示了 Argo CD 安装后的核心组件及其交互关系。API Server 作为统一入口，通过 Ingress 对外暴露；Repository Server 负责拉取 Git 仓库；Application Controller 负责同步状态。

2.2 使用 Helm Chart 安装 Argo CD

Argo CD 官方维护的 Helm Chart 位于 argo-cd 仓库。推荐使用 values.yaml 覆盖默认配置，以便后续管理。

2.2.1 添加 Helm 仓库并更新

helm repo add argo-cd https://argoproj.github.io/argo-helm
helm repo update

2.2.2 创建命名空间并安装

kubectl create namespace argocd
helm install argocd argo-cd/argo-cd \
  --namespace argocd \
  --version 7.1.2 \
  --values values.yaml

2.2.3 关键 values.yaml 配置项

配置路径	默认值	生产推荐值	说明
configs.params.server.insecure	false	true	在 Ingress 层终止 TLS 时，关闭 Argo CD 内置 TLS
server.ingress.enabled	false	true	启用 Ingress 资源创建
server.ingress.hosts	[]	["argocd.example.com"]	Ingress 域名
server.ingress.tls	[]	见下文 TLS 配置	TLS 证书配置
controller.replicas	1	2	高可用场景下增加副本

2.3 安装 Argo CD CLI 工具

CLI 工具用于本地管理 Argo CD 实例，支持应用同步、项目管理和用户认证。

2.3.1 下载与安装

# Linux (amd64)
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

# macOS (Homebrew)
brew install argocd

2.3.2 验证安装

argocd version --client

输出应显示客户端版本号，例如 argocd: v2.12.0+xxx。

2.4 获取初始密码

Argo CD 安装后会自动生成一个随机密码，存储在 Secret 中。以下是两种获取方式：

2.4.1 从 Secret 中提取

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

2.4.2 使用 CLI 登录并修改密码

argocd login argocd.example.com --username admin --password $(kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d)

# 修改密码
argocd account update-password

2.5 Ingress 配置

Ingress 负责将外部 HTTPS 流量路由到 Argo CD API Server。以下配置基于 nginx-ingress-controller。

2.5.1 通过 values.yaml 配置 Ingress

server:
  ingress:
    enabled: true
    ingressClassName: nginx
    hosts:
      - argocd.example.com
    paths:
      - /
    annotations:
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
      nginx.ingress.kubernetes.io/backend-protocol: "HTTP"

2.5.2 手动创建 Ingress 资源（可选）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-tls

2.6 TLS 证书配置

生产环境必须使用 TLS 加密。推荐使用 cert-manager 自动签发 Let's Encrypt 证书，或使用自签名证书用于测试。

2.6.1 使用 cert-manager 自动签发

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: argocd-tls
  namespace: argocd
spec:
  secretName: argocd-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - argocd.example.com

2.6.2 手动创建自签名证书（测试环境）

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=argocd.example.com"

kubectl create secret tls argocd-tls \
  --cert=tls.crt \
  --key=tls.key \
  -n argocd

2.6.3 在 values.yaml 中引用证书 Secret

server:
  ingress:
    tls:
      - hosts:
        - argocd.example.com
        secretName: argocd-tls

2.7 安装后验证清单

完成安装后，请逐项检查以下内容：

检查项	验证命令	预期结果
Pod 状态	kubectl get pods -n argocd	所有 Pod 处于 Running 状态
Service 暴露	kubectl get svc -n argocd	argocd-server 类型为 ClusterIP
Ingress 可达	curl -I https://argocd.example.com	返回 HTTP/2 200
CLI 登录	argocd login argocd.example.com	登录成功，无证书错误
TLS 证书	openssl s_client -connect argocd.example.com:443	证书链完整，未过期

2.8 常见问题与排错

• Ingress 返回 502：检查 nginx.ingress.kubernetes.io/backend-protocol: "HTTP" 注解是否配置正确。Argo CD API Server 默认监听 8080 (HTTP)，而非 HTTPS。
• 证书无效：确认 Secret 名称与 Ingress 中 secretName 一致，且证书包含正确的 SAN 域名。
• CLI 连接超时：检查防火墙规则，确保 443 端口已开放，且 DNS 解析正确。
• Helm 安装失败：使用 helm get manifest argocd -n argocd 查看实际生成的资源，对比 values.yaml 中的配置。