4. Flux 安装与配置：使用 CLI 安装 Flux、引导 Git 仓库、配置 SSH 密钥与 Webhook

本章聚焦于 Flux 的落地安装与核心配置。作为云原生 GitOps 工具链的第一步，正确的安装与引导决定了后续资源配额校准的稳定性。我们将使用官方 CLI 工具 flux 完成集群引导，并配置安全的 SSH 通信与自动化 Webhook 触发。

4.1 前置条件与 CLI 安装

在安装 Flux 之前，请确保环境满足以下要求：

组件 版本要求 说明
Kubernetes 集群 >= 1.21 支持 Kubernetes 自定义资源（CRD）
kubectl >= 1.21 与集群版本匹配
Git 仓库 GitHub / GitLab / Bitbucket 用于存储清单与配置
flux CLI v2.x 最新稳定版 安装引导工具

使用以下命令安装 flux CLI（Linux / macOS）：

# 下载并安装 flux CLI
curl -s https://fluxcd.io/install.sh | sudo bash

# 验证安装
flux --version
提示： 对于 Windows 用户，建议使用 WSL2 或通过 Chocolatey 安装：choco install flux-cli。

4.2 引导 Git 仓库与集群

Flux 的引导过程会创建必要的 CRD、控制器，并将 Git 仓库与集群关联。核心命令为 flux bootstrap，它自动完成以下步骤：

  1. 在集群中安装 Flux 控制器（source-controller、kustomize-controller、helm-controller、notification-controller）。
  2. 在 Git 仓库中创建初始目录结构（clusters/、flux-system/）。
  3. 生成 SSH 密钥对并输出公钥，用于仓库授权。
  4. 将 Flux 组件清单提交至仓库，实现自管理。

以 GitHub 为例，执行引导命令：

export GITHUB_=<your-personal-access->
export GITHUB_USER=<your-github-username>

flux bootstrap github \
  --owner=$GITHUB_USER \
  --repository=flux-config \
  --branch=main \
  --path=./clusters/production \
  --personal
注意： --personal 参数表示使用个人仓库；若为组织仓库，需替换为 --repository=<org/repo> 并确保 具有 repo 权限。

引导成功后，Flux 会在集群中创建 flux-system 命名空间，并自动同步仓库中的清单。

4.3 配置 SSH 密钥

Flux 使用 SSH 密钥与 Git 仓库进行安全通信。引导过程中自动生成的密钥对存储在 Kubernetes Secret 中：

# 查看生成的密钥 Secret
kubectl get secret -n flux-system flux-system

# 提取公钥（用于添加到 Git 仓库的 Deploy Keys）
flux export source git flux-system \
  --namespace flux-system | grep -A 10 "ssh-rsa"

将公钥添加到 Git 仓库的 Deploy Keys 中（以 GitHub 为例）：

步骤 操作
1 进入仓库 Settings → Deploy Keys
2 点击 "Add deploy key"
3 粘贴公钥内容，勾选 "Allow write access"
4 保存后，Flux 即可通过 SSH 拉取/推送代码
最佳实践： 建议为每个环境（production、staging）使用独立的 SSH 密钥和仓库路径，避免权限混淆。

4.4 配置 Webhook 实现自动同步

默认情况下，Flux 以轮询方式（默认 1 分钟）检查 Git 仓库变更。通过配置 Webhook，可以实现代码推送后立即触发同步，缩短延迟。

Flux 支持两种 Webhook 接收方式：

  • Notification Controller：内置接收器，通过 Receiver CRD 定义。
  • Flux Webhook Forwarder：轻量级代理，适用于多集群场景。

以下为使用 Notification Controller 配置 GitHub Webhook 的步骤：

# 1. 创建 Receiver 资源
cat <<EOF | kubectl apply -f -
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Receiver
metadata:
  name: github-receiver
  namespace: flux-system
spec:
  type: github
  events:
    - "push"
  secretRef:
    name: webhook-
  resources:
    - kind: GitRepository
      name: flux-system
EOF

# 2. 创建 Webhook  Secret
kubectl create secret generic webhook- \
  --namespace=flux-system \
  --from-literal==<your-random-secret>

# 3. 获取 Receiver 暴露的地址
kubectl get receiver github-receiver -n flux-system \
  -o jsonpath='{.status.webhook}'

将获取到的 Webhook URL 和 配置到 GitHub 仓库的 Webhook 设置中：

  • Payload URL：Receiver 的 .status.webhook 地址
  • Content type：application/json
  • Secret：与 webhook- 中的值一致
  • Events：选择 "Just the push event"
提示： 如果集群在私有网络内，可使用 ngrok 或 Ingress 暴露 Receiver 服务。Flux 官方也提供 flux webhook 命令用于本地测试。

4.5 安装与配置流程总览

下图展示了从 CLI 安装到 Webhook 配置的完整链路：

Flux 安装与配置流程 Flux 安装与配置流程 安装 flux CLI flux bootstrap 生成 SSH 密钥 配置 Deploy Key 创建 Receiver CRD 配置 GitHub Webhook 代码推送 → 自动同步 说明：Webhook 触发后，Flux 立即拉取最新代码并应用变更， 无需等待默认的 1 分钟轮询间隔。

4.6 验证安装状态

安装完成后，使用以下命令验证 Flux 组件是否正常运行：

# 检查 Flux 控制器 Pod 状态
kubectl get pods -n flux-system

# 查看 Flux 自定义资源
kubectl get gitrepositories -A
kubectl get kustomizations -A

# 检查同步状态
flux get kustomizations --watch

如果所有 Pod 处于 Running 状态，且 GitRepository 与 Kustomization 显示 Ready，则说明安装与配置成功。

关键检查点： 确保 flux-system 命名空间下的 source-controller 和 kustomize-controller 日志中无认证错误或网络超时。若出现 SSH 连接失败，请重新检查 Deploy Key 的权限与公钥内容。

4.7 常见问题与排错

问题 可能原因 解决方案
bootstrap 超时 网络限制或 权限不足 检查 GITHUB_ 是否包含 repo 和 admin:public_key 权限
SSH 连接被拒绝 公钥未正确添加到 Deploy Keys 使用 flux export source git 重新获取公钥并验证
Webhook 未触发同步 Receiver 未暴露或 Secret 不匹配 检查 Receiver 的 .status.webhook 地址是否可达， 是否一致
同步循环或冲突 手动修改了集群资源 使用 flux reconcile 强制同步，或回滚 Git 仓库变更

通过以上步骤，您已成功完成 Flux 的安装、Git 仓库引导、SSH 密钥配置与 Webhook 集成。下一阶段将进入 Flux 的资源配额校准实战配置。

← 上一章 📖 返回目录 下一章 →