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

3. Argo CD 安装与配置

本章将指导你在一个现有的 Kubernetes 集群中完成 Argo CD 的安装、基础配置以及首次 UI 访问。Argo CD 的安装方式灵活，主要分为 kubectl 快速部署和 Helm 生产级部署两种。我们将分别演示这两种方式，并完成初始密码获取、CLI 工具安装以及 UI 端口转发访问。

3.1 环境准备与前提条件

在开始安装前，请确保你的环境满足以下条件：

组件	版本要求	说明
Kubernetes 集群	>= 1.23	支持 Kubernetes API 的集群（如 Minikube、Kind、EKS、AKS、GKE）
kubectl	>= 1.23	已配置好集群访问上下文
Helm（可选）	>= 3.8	仅在使用 Helm 方式安装时需要
集群资源	至少 2 vCPU / 4 GB 内存	Argo CD 控制平面组件需要一定资源

推荐环境： 建议使用 Kind 或 Minikube 创建本地测试集群。以下命令可快速创建一个 Kind 集群：

kind create cluster --name argocd-demo

3.2 方式一：使用 kubectl 快速安装（适用于测试/快速验证）

kubectl 方式是最直接的安装方法，Argo CD 官方提供了标准的 manifest 文件。此方式适合快速搭建验证环境。

3.2.1 创建命名空间并部署

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

# 应用官方标准安装清单
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

3.2.2 验证 Pod 状态

部署完成后，等待所有 Pod 进入 Running 状态：

kubectl get pods -n argocd

# 预期输出示例：
# NAME                                                READY   STATUS    RESTARTS   AGE
# argocd-application-controller-0                     1/1     Running   0          2m
# argocd-applicationset-controller-6b7b6b6b4f-xxxxx   1/1     Running   0          2m
# argocd-dex-server-7f8c9d6b7c-xxxxx                  1/1     Running   0          2m
# argocd-notifications-controller-5c8c8c8c8-xxxxx     1/1     Running   0          2m
# argocd-redis-7f8c9d6b7c-xxxxx                       1/1     Running   0          2m
# argocd-repo-server-6b7b6b6b4f-xxxxx                 1/1     Running   0          2m
# argocd-server-6b7b6b6b4f-xxxxx                      1/1     Running   0          2m

  关键组件说明：
  argocd-server：API 服务与 UI 入口，负责认证、API 请求路由。
argocd-repo-server：仓库服务，负责拉取 Git 仓库并生成 Kubernetes manifest。
argocd-application-controller：应用控制器，持续对比 Git 中的期望状态与集群中的实际状态。
argocd-redis：缓存层，用于存储应用状态和配置缓存。

3.3 方式二：使用 Helm 安装（适用于生产/定制化配置）

Helm 方式提供了更灵活的配置能力，适合需要自定义参数、资源限制或集成已有监控体系的生产环境。

3.3.1 添加 Helm 仓库并更新

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

3.3.2 创建 values 文件（可选但推荐）

创建一个 argocd-values.yaml 文件，用于覆盖默认配置：

# argocd-values.yaml
global:
  # 关闭默认的 Dex 部署，使用内置的本地用户
  dex:
    enabled: false

server:
  # 配置 ingress 或直接使用 NodePort
  service:
    type: NodePort
    nodePortHttp: 30080
    nodePortHttps: 30443

  # 启用自签名证书（生产环境建议使用 Let's Encrypt）
  ingress:
    enabled: false

configs:
  params:
    # 允许通过 HTTP 访问（非 HTTPS 场景）
    server.insecure: true

3.3.3 执行 Helm 安装

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

3.3.4 验证 Helm Release

helm list -n argocd
# 预期输出：
# NAME    NAMESPACE  REVISION  UPDATED                   STATUS    CHART           APP VERSION
# argocd  argocd     1         2024-01-15 10:30:00       deployed  argo-cd-5.46.7  v2.9.3

注意： 生产环境中，务必配置 server.ingress 并启用 HTTPS，同时设置 configs.params.server.insecure: false。上述示例中的 server.insecure: true 仅用于本地开发测试。

3.4 初始配置：获取管理员密码与安装 CLI

3.4.1 获取初始管理员密码

Argo CD 在首次部署时会自动生成一个随机密码，存储在名为 argocd-initial-admin-secret 的 Secret 中：

# 方式一：直接获取密码明文
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# 方式二：保存到环境变量
export ARGOCD_PASSWORD=$(kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d)
echo $ARGOCD_PASSWORD

3.4.2 安装 Argo CD CLI

CLI 工具是管理 Argo CD 的核心方式，支持 Linux、macOS 和 Windows：

操作系统安装命令

Linux (x86_64)

操作系统	安装命令
Linux (x86_64)	`curl -sSL -o /usr/local/bin/argocd \ https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 chmod +x /usr/local/bin/argocd`
macOS (Intel/Apple Silicon)	`brew install argocd`
Windows	`# 使用 winget winget install ArgoCD`

curl -sSL -o /usr/local/bin/argocd \
  https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

macOS (Intel/Apple Silicon)

brew install argocd

Windows

# 使用 winget
winget install ArgoCD

3.4.3 使用 CLI 登录

# 先通过端口转发暴露服务（见 3.5 节）
# 然后使用 CLI 登录
argocd login localhost:8080 --username admin --password $ARGOCD_PASSWORD --insecure

# 验证登录状态
argocd account get-user-info

3.5 UI 访问：端口转发与 Ingress 配置

Argo CD 的 Web UI 默认通过 HTTPS 提供服务。以下是两种常见的访问方式。

3.5.1 方式一：kubectl 端口转发（开发/调试）

这是最快捷的方式，将本地端口转发到 argocd-server 服务：

# 将本地 8080 端口转发到 argocd-server 的 443 端口
kubectl port-forward svc/argocd-server -n argocd 8080:443

# 保持终端运行，然后打开浏览器访问：
# https://localhost:8080

浏览器安全提示： 由于使用自签名证书，浏览器会显示安全警告。点击“高级” -> “继续前往 localhost（不安全）”即可。生产环境应配置受信任的 TLS 证书。

3.5.2 方式二：NodePort 访问（集群内测试）

如果你在安装时配置了 NodePort（如 3.3.2 节所示），可以直接通过节点 IP 访问：

# 获取集群节点 IP
kubectl get nodes -o wide

# 访问地址（使用 HTTP，因为配置了 insecure）
# http://<NODE_IP>:30080

3.5.3 方式三：Ingress 配置（生产推荐）

对于生产环境，建议通过 Ingress 控制器暴露服务。以下是一个 Nginx Ingress 示例：

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

# 应用 Ingress 配置
kubectl apply -f argocd-ingress.yaml

3.6 安装架构总览

下图展示了在单集群中安装 Argo CD 后的组件部署架构与访问路径：

3.7 安装方式对比总结

对比维度	kubectl 方式	Helm 方式
部署速度	极快（单条命令）	中等（需准备 values 文件）
定制化能力	低（需手动修改 manifest）	高（通过 values 文件灵活配置）
版本管理	手动管理版本	Helm 原生支持版本回滚与升级
生产适用性	不推荐（难以维护）	推荐（可重复、可审计）
资源开销	默认配置	可精细控制资源限制

  最佳实践建议：
  开发/测试环境：使用 kubectl 方式快速部署，配合端口转发访问 UI。
预发布/生产环境：使用 Helm 方式，将 values 文件纳入 Git 仓库管理，实现 GitOps 闭环。
安全加固：安装完成后立即修改默认 admin 密码，并配置 RBAC 权限。

3.8 验证安装：创建第一个测试应用

安装完成后，可以通过 CLI 快速验证 Argo CD 是否正常工作：

# 使用 CLI 创建一个测试应用（指向官方示例仓库）
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# 同步应用
argocd app sync guestbook

# 查看应用状态
argocd app get guestbook

# 在 UI 中查看：打开浏览器访问 https://localhost:8080
# 使用 admin 和之前获取的密码登录

如果应用状态显示 Synced 且 Healthy，则说明 Argo CD 安装与配置成功。