4. Flux CLI 安装与引导：Flux CLI 下载安装、bootstrap 命令详解、flux bootstrap github/gitlab 流程

Flux CLI 是操作 Flux CD 的核心命令行工具，负责集群引导、资源清单生成、状态查询与故障排查。本章聚焦 CLI 的安装验证、bootstrap 命令的完整参数体系，以及面向 GitHub 与 GitLab 两大主流平台的引导流程。

4.1 Flux CLI 下载安装

Flux CLI 提供多平台二进制分发，推荐使用官方安装脚本或包管理器进行安装。安装完成后需验证版本与集群访问权限。

安装方式 适用平台 命令示例
官方脚本（macOS/Linux） amd64 / arm64 curl -s https://fluxcd.io/install.sh | sudo bash
Homebrew（macOS） macOS brew install fluxcd/tap/flux
二进制下载（Windows/Linux） 所有平台 从 GitHub Releases 下载对应二进制
版本验证：安装后执行 flux --version，输出应类似 flux version 2.x.x。同时确保 kubectl 已配置并可访问目标集群。

4.2 bootstrap 命令详解

flux bootstrap 是引导流程的单一入口，它将 Flux 控制器安装到集群，并将 Git 仓库作为唯一真实来源。命令核心参数分为三类：仓库连接、集群配置与安全选项。

参数类别 参数名 说明 示例值
仓库连接 --owner GitHub 组织或用户 / GitLab 组或用户 my-org
--repository 仓库名称 fleet-infra
--branch 主分支名称 main
集群配置 --path 集群配置在仓库中的相对路径 clusters/production
--kubeconfig 指定 kubeconfig 文件路径 ~/.kube/config
安全选项 --private-key-file SSH 私钥路径（用于 Git 认证） ~/.ssh/id_ed25519
--personal 使用个人账号而非组织 true
核心行为：bootstrap 会自动在目标仓库中创建 clusters/<cluster-name>/flux-system/ 目录，写入 Flux 控制器的 Kubernetes 清单，并提交到 Git。集群中的 Flux Pod 会持续监听该路径。

4.3 flux bootstrap github 流程

GitHub 引导流程需要提前创建个人访问令牌（PAT），并赋予 repo 全部权限。流程分为令牌准备、执行引导、验证部署三个步骤。

  1. 创建 GitHub PAT：访问 GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens，选择仓库权限为 Read and Write。
  2. 设置环境变量：export GITHUB_=<your->
  3. 执行引导命令：
flux bootstrap github \
  --owner=my-org \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production \
  --personal=false \
  --private-key-file=~/.ssh/id_ed25519
  1. 验证部署：
flux get kustomizations --namespace=flux-system
kubectl get pods -n flux-system
常见错误：如果引导失败，检查 GITHUB_ 是否已导出、仓库是否已存在且不为空、SSH 公钥是否已添加到 GitHub 账户。使用 flux logs --level=error 查看详细错误。

4.4 flux bootstrap gitlab 流程

GitLab 引导流程与 GitHub 类似，但使用 GitLab 个人访问令牌，并需要指定 GitLab 实例地址（自托管或 SaaS）。

  1. 创建 GitLab PAT：GitLab User Settings → Access Tokens，选择 api 和 write_repository 权限。
  2. 设置环境变量：export GITLAB_=<your->
  3. 执行引导命令：
flux bootstrap gitlab \
  --owner=my-group \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production \
  ---auth=true \
  --private-key-file=~/.ssh/id_ed25519
  1. 验证部署：同样使用 flux get kustomizations 和 kubectl get pods 确认。
自托管 GitLab：如果使用自托管实例，需添加 --hostname=gitlab.example.com 参数，并确保该地址可从集群访问。

4.5 引导流程架构图

下图展示 flux bootstrap 在 GitHub 平台上的完整执行流程，从 CLI 发起、Git 仓库写入到集群控制器部署的端到端链路。

Flux Bootstrap GitHub 流程架构 Flux Bootstrap GitHub 流程架构 Flux CLI GitHub API Git 仓库 推送清单 写入文件 Kubernetes 集群 Flux 控制器 kubectl apply GitOps 同步 引导后：仓库变更自动同步 至集群 Flux 控制器

4.6 引导后验证清单

引导完成后，建议执行以下验证步骤，确保 GitOps 流水线就绪：

检查项 命令 预期结果
Flux 命名空间 kubectl get ns flux-system 命名空间状态为 Active
控制器 Pod kubectl get pods -n flux-system 所有 Pod 处于 Running 状态
GitRepository 资源 flux get sources git 显示仓库 URL 与最新提交
Kustomization 资源 flux get kustomizations 状态为 Ready
Git 提交记录 查看仓库 clusters/<name>/flux-system/ 包含 gotk-components.yaml 等文件
生产建议：引导完成后，立即将 GITHUB_ 或 GITLAB_ 从环境中清除，避免泄露。后续 Flux 通过 SSH 密钥与 Git 仓库通信，无需长期令牌。
← 上一章 📖 返回目录 下一章 →