📚 课程目录第4章 Flux CLI 安装

4. Flux CLI 安装：下载安装、版本选择、环境变量配置与基础命令

Flux CLI 是与 Flux CD 控制平面交互的核心工具，用于引导集群、管理资源、查看状态和调试工作流。本章将系统讲解 Flux CLI 的安装流程、版本匹配策略、环境变量配置方法以及高频基础命令，确保你能够在本地和 CI 环境中快速搭建可用的 CLI 环境。

前置要求： 安装 Flux CLI 前，请确保已具备 kubectl（≥1.21）和 git（≥2.28）环境，并拥有对目标 Kubernetes 集群的 admin 权限。

4.1 下载安装与版本选择

Flux CLI 提供多平台二进制分发，推荐从官方 GitHub Releases 页面获取最新稳定版本。安装方式包括脚本一键安装、手动下载以及包管理器安装。

4.1.1 脚本安装（推荐）

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

# 验证安装
flux --version

4.1.2 手动下载安装

# 下载指定版本（以 v2.3.0 为例）
wget https://github.com/fluxcd/flux2/releases/download/v2.3.0/flux_2.3.0_linux_amd64.tar.gz

# 解压并移动到 PATH
tar -xzf flux_2.3.0_linux_amd64.tar.gz
sudo mv flux /usr/local/bin/

# 验证
flux --version

4.1.3 版本选择策略

场景	推荐版本	说明
生产环境	最新稳定版（如 v2.3.x）	经过充分测试，API 稳定，安全补丁完整
新功能试用	最新预发布版（如 v2.4.0-rc.1）	包含新特性，但可能存在未修复的缺陷
与已有集群对齐	与集群中 Flux 控制器版本一致	避免 CLI 与控制器 API 版本不兼容
CI/CD 流水线	固定版本（如 v2.3.0）	使用语义化版本锁定，避免意外升级导致行为变化

版本兼容性注意： Flux CLI 与集群内运行的 Flux 控制器应保持大版本一致（如均为 v2.x）。跨大版本使用可能导致 flux reconcile 或 flux get 命令返回不兼容的 API 响应。

4.2 环境变量配置

Flux CLI 支持通过环境变量覆盖默认行为，便于在 CI/CD、多集群或受限网络环境中使用。以下为关键环境变量及其用途：

环境变量	默认值	说明
`FLUX_KUBECONFIG`	`~/.kube/config`	指定 kubeconfig 文件路径，用于多集群切换
`FLUX_CACHE_DIR`	`~/.cache/flux`	缓存目录，存放 Git 仓库克隆和 Helm 索引
`FLUX_LOG_LEVEL`	`info`	日志级别：`debug`、`info`、`warn`、`error`
`FLUX_DISABLE_GIT_KNOWN_HOSTS`	`false`	设为 `true` 跳过 Git 主机密钥验证（仅测试环境）
`FLUX_EXPERIMENTAL`	`false`	启用实验性功能（如 OCI 仓库支持）

# 示例：为 CI 环境配置环境变量
export FLUX_KUBECONFIG=/workspace/kubeconfig
export FLUX_CACHE_DIR=/tmp/flux-cache
export FLUX_LOG_LEVEL=debug

# 执行命令
flux get kustomizations --all-namespaces

最佳实践： 在 CI 流水线中，将 FLUX_KUBECONFIG 指向临时生成的 kubeconfig，避免污染全局配置。同时设置 FLUX_CACHE_DIR 为可写临时目录，防止缓存冲突。

4.3 基础命令介绍

Flux CLI 命令按功能分为引导、资源管理、状态查看、故障排查和清理五大类。以下为最常用的命令及其使用场景：

4.3.1 引导与初始化

# 引导 Flux 控制器到集群（自动安装 CRD 和控制器）
flux bootstrap github \
  --owner=my-org \
  --repository=flux-infra \
  --branch=main \
  --path=./clusters/production

# 检查引导状态
flux check

4.3.2 资源管理

# 创建或更新资源
flux create source git my-app \
  --url=https://github.com/my-org/my-app \
  --branch=main \
  --interval=1m

flux create kustomization my-app \
  --source=my-app \
  --path="./deploy" \
  --prune=true \
  --interval=5m

# 手动触发资源同步
flux reconcile source git my-app
flux reconcile kustomization my-app

4.3.3 状态查看

# 列出所有资源
flux get sources git
flux get kustomizations
flux get helmreleases

# 查看资源详情
flux get kustomization my-app
flux get helmrelease my-app --show-manifests

# 查看事件日志
flux events my-app --type=warning

4.3.4 故障排查

# 检查集群状态
flux check --pre

# 导出资源状态为 YAML
flux export kustomization my-app

# 查看控制器日志
flux logs --level=error --since=10m

4.3.5 清理与卸载

# 卸载 Flux 控制器（保留 CRD）
flux uninstall --keep-crds

# 完全卸载
flux uninstall

  命令速查表： 使用 flux --help 查看所有命令分组；flux <command> --help 查看子命令详情。常用组合：flux get + flux reconcile + flux logs 构成日常巡检三件套。

4.4 安装验证与常见问题

4.4.1 安装后快速验证

# 1. 检查版本
flux --version

# 2. 检查集群前置条件
flux check --pre

# 3. 列出所有 Flux API 资源
flux get all

# 4. 查看 Flux 命名空间中的 Pod 状态
kubectl get pods -n flux-system

4.4.2 常见安装问题

问题	原因	解决方案
`flux: command not found`	二进制未加入 PATH	检查安装路径，执行 `export PATH=$PATH:/usr/local/bin`
`Error: unable to connect to cluster`	kubeconfig 未配置或集群不可达	设置 `KUBECONFIG` 或 `FLUX_KUBECONFIG` 环境变量
`Error: API version mismatch`	CLI 版本与控制器版本不一致	升级 CLI 或控制器至相同大版本
`Error: Git host key verification failed`	Git 主机密钥未添加到 known_hosts	使用 `ssh-keyscan` 添加密钥，或设置 `FLUX_DISABLE_GIT_KNOWN_HOSTS=true`

快速诊断： 遇到安装或连接问题时，首先执行 flux check --pre 获取集群前置条件检查结果，该命令会明确提示缺失的依赖或配置错误。

4.5 本章小结

完成本章学习后，你应能够：

使用脚本或手动方式安装指定版本的 Flux CLI
根据生产、CI/CD 或试用场景选择合适的版本
配置 FLUX_KUBECONFIG、FLUX_LOG_LEVEL 等环境变量以适应多集群和调试需求
熟练使用 flux bootstrap、flux create、flux get、flux reconcile、flux logs 等核心命令
通过 flux check --pre 快速诊断安装和连接问题