4. Argo CD CLI 与 Web UI 入门：CLI 安装与认证、Web UI 界面导航、项目与应用创建基础

本章是 Argo CD 操作入口的实战起点。无论你偏好命令行的高效还是图形界面的直观，都需要掌握 CLI 与 Web UI 的安装、认证和基础操作。我们将从 CLI 安装与 认证开始，再深入 Web UI 的界面布局，最后完成第一个项目与应用的创建。

4.1 Argo CD CLI 安装与认证

Argo CD CLI（argocd）是与 API Server 交互的核心工具，支持安装、部署、同步和诊断等全生命周期操作。

4.1.1 CLI 安装方式

操作系统 安装命令 / 步骤
macOS (Homebrew) brew install argocd
Linux (curl 下载) 
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
Windows (PowerShell) 
$version = (Invoke-RestMethod https://api.github.com/repos/argoproj/argo-cd/releases/latest).tag_name
Invoke-WebRequest -Uri "https://github.com/argoproj/argo-cd/releases/download/$version/argocd-windows-amd64.exe" -OutFile "argocd.exe"
版本验证：安装后执行 argocd version --client，确认 CLI 版本与 Argo CD 服务端版本兼容（建议大版本一致）。

4.1.2 CLI 认证流程

CLI 认证有三种主流方式，推荐使用 admin 密码或 Bearer 进行首次登录。

  1. admin 密码登录（初始密码存储在 Secret 中）：
# 获取初始 admin 密码
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# 登录 Argo CD API Server
argocd login <ARGOCD_SERVER>:443 \
  --username admin \
  --password <INITIAL_PASSWORD> \
  --insecure   # 仅测试环境使用，生产应配置 TLS
  1. Bearer 认证（适合 CI/CD 自动化）：
# 在 Web UI 中生成 ：用户头像 → 用户信息 → 创建 
# 或通过 CLI 生成
argocd account generate- --account <ACCOUNT_NAME>

# 使用  登录（无需密码）
argocd login <ARGOCD_SERVER>:443 --auth- <>
  1. SSO / OIDC 认证（企业集成）：配置 Dex 或 Keycloak 后，CLI 通过浏览器完成 OAuth 流程。
安全提醒：生产环境务必禁用 --insecure，并为 Argo CD Server 配置有效的 TLS 证书。 应定期轮换，避免硬编码在脚本中。

4.2 Web UI 界面导航

Argo CD Web UI 是 GitOps 的可视化控制台，提供应用状态、同步历史和配置管理的全景视图。下图展示了 Web UI 的核心布局与导航结构。

Argo CD Web UI 界面导航结构 顶部导航栏 Applications Settings User Info Docs Search 侧边栏 Applications Projects Repositories Clusters Accounts Settings 主内容区 应用卡片 名称 / 状态 / 同步 健康 / 仓库 / 目标 应用卡片 名称 / 状态 / 同步 健康 / 仓库 / 目标 应用卡片 名称 / 状态 / 同步 健康 / 仓库 / 目标 批量操作：同步 / 刷新 / 删除 / 暂停 界面说明 • 顶部导航：全局搜索、用户设置、文档入口 • 左侧侧边栏：应用、项目、仓库、集群、账户管理 • 主内容区：应用卡片列表，支持筛选、排序、批量操作

4.2.1 关键界面区域

  • Applications 视图：默认首页，以卡片或列表形式展示所有应用，每个卡片显示应用名称、同步状态（Synced/OutOfSync）、健康状态（Healthy/Degraded）、目标仓库与路径。
  • 应用详情页：点击卡片进入，包含 APP（资源树）、DIFF（差异对比）、HISTORY（同步历史）、PARAMETERS（参数覆盖）等标签页。
  • Settings：管理仓库连接、集群注册、项目 RBAC、通知配置等全局设置。

4.3 项目与应用创建基础

在 Argo CD 中，Project（项目）是应用分组的逻辑边界，用于隔离环境、控制权限和约束部署目标。Application（应用）则是 GitOps 的核心实体，定义了从 Git 仓库到 Kubernetes 集群的完整同步规则。

4.3.1 创建 Project（项目）

项目定义了允许部署的 源仓库、目标集群/命名空间 以及 资源类型 的约束。

方式一：CLI 创建

# 创建项目定义文件 project.yaml
cat <<EOF > project.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  description: "Production environment project"
  # 允许的源仓库
  sourceRepos:
  - 'https://github.com/my-org/production-manifests.git'
  # 允许的目标集群和命名空间
  destinations:
  - namespace: 'prod-*'
    server: 'https://kubernetes.default.svc'
  # 允许部署的资源类型
  clusterResourceWhitelist:
  - group: '*'
    kind: '*'
  # 拒绝的命名空间
  namespaceResourceBlacklist:
  - group: ''
    kind: 'ServiceAccount'
EOF

# 应用项目
argocd proj create -f project.yaml

方式二：Web UI 创建

  1. 点击左侧 Projects → New Project。
  2. 填写项目名称、描述。
  3. 在 SOURCES 标签页添加允许的 Git 仓库 URL。
  4. 在 DESTINATIONS 标签页添加目标集群和命名空间（支持通配符 *）。
  5. 在 CLUSTER RESOURCES / NAMESPACED RESOURCES 设置资源白名单/黑名单。
  6. 点击 Create 完成。
最佳实践：为每个环境（dev/staging/production）创建独立项目，并在项目级别锁定源仓库和目标集群，防止误操作跨环境部署。

4.3.2 创建 Application（应用）

应用将 Git 仓库中的 Kubernetes 清单同步到目标集群。下图展示了应用创建时的核心配置项与流程。

Application 创建核心配置流程 应用名称 唯一标识，如 guestbook 所属项目 如 production 源仓库 Git URL + 路径 目标集群 + 命名空间 同步策略 自动 / 手动 同步选项 Prune / SelfHeal 参数覆盖 Helm Values / Kustomize 创建完成 Apply 配置说明 • 源仓库：支持 Helm Chart、Kustomize、YAML/JSON 清单、Jsonnet • 目标集群：默认指向 Argo CD 所在集群（https://kubernetes.default.svc），也可注册外部集群 • 同步策略：自动同步可设置 Prune（删除多余资源）和 SelfHeal（自动修复漂移） • 参数覆盖：可在 UI 或 CLI 中临时覆盖 Helm Values 或 Kustomize 参数，不影响 Git 源

CLI 创建应用示例：

argocd app create guestbook \
  --project production \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace prod-guestbook \
  --sync-policy automated \
  --auto-prune \
  --self-heal

Web UI 创建步骤：

  1. 点击 New App 按钮。
  2. 填写 Application Name（应用名称）和 Project（所属项目）。
  3. 在 SOURCE 区域选择仓库 URL、Revision（分支/tag/commit）、Path（清单目录）。
  4. 在 DESTINATION 区域选择目标集群 URL 和命名空间。
  5. 在 SYNC POLICY 区域选择 Manual 或 Automated，并勾选 Prune Resources / Self Heal。
  6. 点击 Create 完成创建，然后点击 Sync 触发首次同步。
快速验证：创建完成后，在 Web UI 的应用卡片上观察同步状态。首次同步成功后，状态应变为 Synced 和 Healthy。若出现 OutOfSync，说明集群实际状态与 Git 仓库定义不一致，可手动点击 Sync 修复。

4.4 本章小结

  • CLI 安装：支持 macOS、Linux、Windows，通过 argocd login 完成认证，推荐使用 用于自动化场景。
  • Web UI 导航：顶部导航 + 左侧侧边栏 + 主内容区，Applications 视图是日常操作核心，应用详情页提供资源树、差异对比和同步历史。
  • 项目创建：定义源仓库、目标集群和资源约束，是环境隔离和权限控制的基础单元。
  • 应用创建：绑定 Git 仓库路径与目标集群命名空间，配置同步策略（自动/手动）和同步选项（Prune/SelfHeal），实现 GitOps 声明式部署。
← 上一章 📖 返回目录 下一章 →