📚 课程目录第2章 Flux安装与基础配置

2. Flux安装与基础配置：使用Helm安装Flux、配置Git仓库连接、创建第一个Kustomization资源

本章是Flux实战的起点。我们将使用Helm在Kubernetes集群中安装Flux v2组件，完成与Git仓库的认证连接，并创建第一个Kustomization资源，使集群能够自动从Git仓库同步应用清单。掌握本节内容后，你将拥有一个可工作的GitOps基础设施。

2.1 安装前准备：集群与CLI工具

在安装Flux之前，请确保以下环境就绪：

组件	最低版本	验证命令
Kubernetes集群	v1.21+	`kubectl version --short`
Helm CLI	v3.8+	`helm version`
flux CLI	v2.x	`flux --version`
Git仓库（GitHub/GitLab/Bitbucket）	—	具有读写权限的Personal Access

推荐实践：使用 flux check --pre 命令在安装前自动检查集群是否满足Flux的运行时依赖（CRD版本、RBAC权限、网络连通性等）。

2.2 使用Helm安装Flux v2

Flux v2采用模块化架构，核心组件包括 source-controller（管理制品源）、kustomize-controller（执行Kustomize渲染与同步）、helm-controller（管理Helm Release）以及 notification-controller（处理事件通知）。我们通过Helm Chart统一安装所有组件。

2.2.1 添加Flux Helm仓库

helm repo add fluxcd-community https://fluxcd-community.github.io/helm-charts
helm repo update

2.2.2 创建命名空间与安装Chart

kubectl create namespace flux-system

helm install flux fluxcd-community/flux2 \
  --namespace flux-system \
  --set components={source-controller,kustomize-controller,helm-controller,notification-controller} \
  --set clusterDomain=cluster.local \
  --set watchAllNamespaces=true

  参数说明：
  components：显式指定安装的控制器列表，避免安装不需要的组件。
watchAllNamespaces：允许Flux监听所有命名空间中的资源变更，适用于多团队共享集群场景。
clusterDomain：与集群DNS域名保持一致，默认 cluster.local。

2.2.3 验证安装状态

kubectl get pods -n flux-system
flux check

当所有Pod处于 Running 状态且 flux check 输出均为 ✔ 时，安装成功。

2.3 配置Git仓库连接

Flux通过 GitRepository 自定义资源定义（CRD）来声明一个远程Git仓库作为制品源。配置过程分为两步：创建认证Secret，再创建GitRepository资源。

2.3.1 创建Git认证Secret

使用 flux create secret git 命令快速生成包含SSH密钥或HTTP 的Secret：

flux create secret git flux-system \
  --url=https://github.com/your-org/your-repo.git \
  --username=git \
  --password=ghp_yourPersonalAccessToken \
  --namespace flux-system

对于SSH方式：

flux create secret git flux-system \
  --url=ssh://git@github.com/your-org/your-repo.git \
  --ssh-key-algorithm=ed25519 \
  --ssh-rsa-bits=4096 \
  --namespace flux-system

安全提醒：切勿将或私钥明文写入版本控制。使用 flux create secret git 命令会自动将Secret编码并仅存储在集群中。生产环境建议集成外部密钥管理服务（如Vault、AWS Secrets Manager）。

2.3.2 创建GitRepository资源

以下YAML定义了一个指向主分支、每60秒轮询一次的Git仓库源：

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: flux-infra
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: flux-system
  url: https://github.com/your-org/your-repo.git

应用该资源：

kubectl apply -f gitrepository.yaml

2.3.3 验证源同步状态

kubectl get gitrepository -n flux-system
flux get sources git

当 READY 列为 True 时，表示Flux已成功从Git仓库拉取内容并缓存为制品（Artifact）。

2.4 创建第一个Kustomization资源

Kustomization是Flux的核心编排单元，它告诉kustomize-controller如何从GitRepository源中选取路径、应用补丁并同步到集群。

2.4.1 编写Kustomization YAML

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: infra-apps
  namespace: flux-system
spec:
  interval: 5m0s
  path: ./clusters/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-infra
  validation: client
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: nginx
      namespace: default
  patches:
    - patch: |
        - op: replace
          path: /spec/replicas
          value: 3
      target:
        kind: Deployment
        name: nginx

2.4.2 关键字段解析

字段	作用	推荐值
`interval`	集群与Git仓库的同步周期	生产环境建议 `5m` 或更长
`path`	仓库内Kustomize overlay目录	按环境分层：`./clusters/production`
`prune`	是否删除集群中不再存在于Git中的资源	`true`（GitOps核心原则）
`validation`	客户端/服务端校验模式	`client`（快速校验）
`healthChecks`	等待指定资源达到Ready状态后再标记同步完成	关键工作负载必须配置
`patches`	运行时覆盖Git中的默认配置	用于环境差异化，避免分支污染

2.4.3 应用并验证Kustomization

kubectl apply -f kustomization.yaml
flux get kustomizations

当 READY 为 True 且 MESSAGE 显示 Applied revision: main/abc123 时，第一个GitOps工作流已成功建立。

2.5 整体架构与数据流

下图展示了从Git仓库提交到集群资源生效的完整链路：

2.6 常见问题与排查

现象	可能原因	解决措施
`GitRepository` 一直 `False`	过期 / SSH密钥不匹配 / 仓库URL错误	检查Secret内容，使用 `flux create secret git` 重新生成
`Kustomization` 同步失败	path目录不存在 / YAML语法错误 / 资源冲突	查看 `kubectl describe kustomization infra-apps -n flux-system` 中的错误信息
Pod CrashLoopBackOff	镜像拉取失败 / 资源配额不足 / 配置错误	检查 `kubectl logs` 并确认 `healthChecks` 配置正确

调试利器：使用 flux reconcile kustomization infra-apps --with-source 手动触发一次完整的源拉取与同步，并观察实时日志输出，快速定位问题。

2.7 本章小结

通过本节实战，你已完成：

使用Helm在K8s集群中部署Flux v2核心控制器；
配置Git仓库认证并创建 GitRepository 源资源；
编写并应用第一个 Kustomization 资源，实现从Git到集群的自动同步。

现在，你的集群已经具备GitOps基础能力。下一阶段我们将深入Kustomization的参数调优，为回滚策略的精细化控制打下基础。