📚 课程目录第4章环境搭建与初始化

4. 环境搭建与初始化：安装 Argo CD / Flux、配置 Git 仓库连接、初始化集群与 Namespace

GitOps 声明式发布模型的生产落地，始于一套可靠、可复现的引导环境。本章聚焦两大主流工具——Argo CD 与 Flux v2——的安装选型、Git 仓库认证配置，以及集群与 Namespace 的初始化策略。错误的引导步骤会导致后续所有同步失败，因此本节内容按“安装 → 连接 → 初始化”三阶段组织，并给出常见陷阱的排查路径。

4.1 工具选型对比：Argo CD vs Flux v2

在搭建环境前，需根据团队运维习惯与集群规模选择 GitOps 引擎。下表从架构、安全模型、多集群支持三个维度给出对比：

对比维度	Argo CD	Flux v2 (source-controller + kustomize-controller)
架构风格	中心化 API Server + Application Controller	去中心化 Operator 集合，每个控制器独立
安装复杂度	中等，需配置 RBAC 与 TLS	较低，默认 Helm Chart 开箱即用
Git 认证方式	SSH / HTTPS + 令牌 / Webhook	HTTPS 令牌优先，SSH 需额外 Secret
多集群支持	原生，通过 cluster secret 注册	需 KubeConfig 或 Cluster API 集成
UI 与可观测性	内置 Web UI + 应用拓扑图	依赖第三方 Dashboard (Weave GitOps)
声明式自举	支持 App of Apps 模式	支持 GitRepository + Kustomization 链式引用

选型建议： 若团队需要可视化审批流程与多集群统一管理，优先选择 Argo CD；若追求轻量、纯声明式且与 Kustomize 深度集成，Flux v2 更合适。生产环境建议先在小集群做 POC，验证 Git 仓库连接稳定性后再推广。

4.2 安装 Argo CD 与 Flux v2

4.2.1 Argo CD 安装步骤

创建命名空间：kubectl create namespace argocd

安装官方 Manifest：

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

暴露 API Server： 使用 LoadBalancer 或 NodePort，生产环境建议 Ingress + TLS。

获取初始密码：

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

登录 CLI：argocd login <server> --username admin

4.2.2 Flux v2 安装步骤

安装 CLI 工具：

curl -s https://fluxcd.io/install.sh | sudo bash

预检集群：flux check --pre 确保集群满足版本要求。

引导安装：

flux bootstrap github \
  --owner=<your-org> \
  --repository=<fleet-infra> \
  --branch=main \
  --path=./clusters/prod \
  --personal

验证组件状态：flux get all

常见陷阱： Flux bootstrap 会直接向 Git 仓库写入集群状态文件。若仓库已存在非 Flux 管理的 YAML，可能导致冲突。建议使用专用空仓库或独立分支进行引导。

4.3 配置 Git 仓库连接

Git 仓库是 GitOps 的单一事实来源。连接配置错误是故障排查中最高频的原因之一。以下按认证方式分类说明：

认证方式	Argo CD 配置方法	Flux v2 配置方法
HTTPS + 令牌	`argocd repo add https://github.com/org/repo --username --password $GITHUB_`	通过 `flux create source git` 指定 `--secret-ref`
SSH 密钥	`argocd repo add git@github.com:org/repo --ssh-private-key-path ~/.ssh/id_rsa`	创建 `Secret` 类型为 `kubernetes.io/ssh-auth`
Webhook 自动同步	配置 GitHub/GitLab Webhook 指向 Argo CD API	使用 `flux create receiver` 生成 Webhook URL

4.3.1 连接验证命令

# Argo CD
argocd repo list

# Flux v2
flux get sources git
kubectl describe gitrepository <name> -n flux-system

若返回状态为 Healthy 或 True，说明连接正常；若出现 Connection refused 或 authentication failed，优先检查 Secret 中的令牌是否过期、SSH 密钥是否已添加到仓库 Deploy Keys。

故障排查要点： 对于自托管 Git 实例（如 GitLab 内网），需额外配置 TLS 证书或跳过证书验证（仅测试环境）。Argo CD 通过 --insecure-skip-verify 参数控制；Flux 通过 spec.secretRef 中的 caFile 字段注入 CA 证书。

4.4 初始化集群与 Namespace

集群初始化包括：创建基础 Namespace、设置 RBAC 权限、部署 Cluster API 资源（如 CRD、ClusterRole）。GitOps 要求所有初始化配置也存储在 Git 仓库中，实现“集群即代码”。

4.4.1 推荐 Namespace 规划

Namespace	用途	是否受 GitOps 管理
`flux-system` / `argocd`	GitOps 控制平面	是（自举）
`infra`	基础设施组件（Ingress、监控、日志）	是
`team-a` / `team-b`	业务应用隔离	是
`kube-system`	系统组件	否（避免冲突）

4.4.2 初始化脚本示例（Argo CD App of Apps）

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cluster-bootstrap
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/fleet-infra
    path: clusters/prod/bootstrap
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: infra
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

该 Application 会同步 clusters/prod/bootstrap 目录下的所有 YAML，包括 Namespace、ServiceAccount、ClusterRoleBinding 等。Flux 对应使用 Kustomization 资源实现相同效果。

4.5 环境初始化流程总览

下图展示了从空集群到 GitOps 就绪状态的完整初始化流程，包含安装、仓库连接、Namespace 创建三个关键阶段：

4.6 常见初始化故障与排查

故障现象	可能原因	排查命令 / 方法
Argo CD 安装后 Pod 一直 CrashLoopBackOff	RBAC 未正确绑定或 API Server 版本不兼容	`kubectl describe pod -n argocd` 查看事件；检查集群版本 ≥ 1.21
Flux bootstrap 报错 `failed to push`	Git 令牌权限不足（缺少 push 权限）	验证令牌 scope 包含 `repo`；尝试手动 git push 确认
仓库连接成功但同步失败	路径错误或 YAML 格式不合法	`argocd app get <app> --hard-refresh`；`flux reconcile source git`
Namespace 创建后应用无法调度	缺少 ResourceQuota 或 NetworkPolicy 冲突	`kubectl describe quota -n <ns>`；检查 NetworkPolicy 是否拒绝入口

最佳实践： 在初始化阶段，建议为每个 Namespace 预先创建 LimitRange 和 ResourceQuota，避免后续应用因资源不足而无法启动。同时，将 Namespace 定义放在 Git 仓库的 bootstrap/ 目录下，与业务应用分离，便于权限控制。

4.7 初始化后的健康检查清单

控制平面健康： 所有 GitOps 组件 Pod 状态为 Running，无重启计数持续增长。
Git 仓库同步： 执行 argocd repo list 或 flux get sources git，状态为 Healthy / True。
Namespace 就绪： 目标 Namespace 已存在，且 kubectl auth can-i 验证 ServiceAccount 权限正确。
自举应用同步： 第一个 Application 或 Kustomization 已成功同步，无 OutOfSync 或 Failed 状态。