flux-operator-cli

Flux Operator CLI

安装

brew install controlplaneio-fluxcd/tap/flux-operator

使用 ~/.kube/config。支持离线（无集群）和在线命令。

命令概览

命令分为两类：离线（无需访问集群）和在线（需要访问集群）。

离线命令（无需集群）

命令	用途
build instance	根据 FluxInstance YAML 生成 K8s 清单
build rset	根据 ResourceSet YAML 生成 K8s 清单
diff yaml <source> <target>	比较 YAML 文件，生成 RFC 6902 JSON 补丁
patch instance	生成用于升级 Flux 控制器的 kustomize 补丁

在线命令（需要访问集群）

命令	用途
get instance|rset|rsip|all	列出 Flux Operator 资源及其状态
export report	导出包含分发状态的 FluxReport
export resource <kind>/<name>	将 Flux 资源导出为 YAML/JSON
reconcile instance|rset|rsip|resource|all	触发协调
suspend instance|rset|rsip|resource	暂停协调
resume instance|rset|rsip|resource	恢复协调
delete instance|rset|rsip	删除 Flux 资源
stats	查看协调统计信息和存储用量
trace <kind>/<name>	跟踪对象在 GitOps 交付流水线中的流转
tree rset|ks|hr	以树形结构显示托管对象
wait instance|rset|rsip	轮询，直到资源就绪
create secret <type>	创建供 Flux 使用的 Kubernetes 密钥
install	使用 Flux Operator 和实例引导集群
uninstall	从集群中移除 Flux Operator
version	显示 CLI、Operator 和分发版本

常见模式

在本地构建并预览清单

# Build FluxInstance manifests
flux-operator build instance -f flux-instance.yaml

# Build ResourceSet with inputs
flux-operator build rset -f resourceset.yaml \
  --inputs-from inputs.yaml

# Diff two YAML files (local or remote URLs)
flux-operator diff yaml old.yaml new.yaml -o json-patch-yaml

集群日常运维

# Check status of everything
flux-operator get all -A

# Filter by readiness
flux-operator get all --ready-status=False

# Reconcile a stuck resource
flux-operator reconcile resource Kustomization/my-app -n default --wait

# Reconcile everything
flux-operator reconcile all --wait

# Trace where an object comes from in the GitOps pipeline
flux-operator trace Deployment/my-app -n default

# View the object tree under a Kustomization
flux-operator tree ks my-app -n default

升级 Flux 控制器

# Generate upgrade patches for a target version
flux-operator patch instance -f flux-instance.yaml -v v2.5

# With a custom registry
flux-operator patch instance -f flux-instance.yaml -v v2.5 \
  -r my-registry.example.com/flux

# Verify controllers updated
flux-operator get instance -A

维护期间暂停和恢复

# Suspend before maintenance
flux-operator suspend instance flux -n flux-system

# Verify suspended
flux-operator get instance flux -n flux-system

# Resume after maintenance
flux-operator resume instance flux -n flux-system --wait

安全删除

# Delete but keep managed resources in place
flux-operator delete instance flux -n flux-system --with-suspend

# Delete and wait for completion
flux-operator delete rset my-rset -n default --wait

# Verify deletion
flux-operator get all -n default

引导集群

# Basic install
flux-operator install

# Verify install succeeded
flux-operator get all -A

# Install with Git sync
flux-operator install \
  --instance-sync-url=https://github.com/org/fleet \
  --instance-sync-ref=main \
  --instance-sync-path=clusters/production \
  --instance-sync-creds=username:ghp_token

# Install with cluster tuning
flux-operator install \
  --instance-cluster-type=aws \
  --instance-cluster-size=large \
  --instance-cluster-multitenant

创建供 Flux 使用的密钥

# Git SSH auth
flux-operator create secret ssh my-ssh-secret \
  --private-key-file=id_ed25519 \
  --knownhosts-file=known_hosts \
  -n flux-system

# Container registry auth
flux-operator create secret registry my-reg-secret \
  --server=ghcr.io \
  --username=bot \
  --password-stdin \
  -n flux-system

# SOPS age encryption
flux-operator create secret sops my-sops-secret \
  --age-key-file=age.key \
  -n flux-system

# Export as YAML instead of applying (for GitOps)
flux-operator create secret basic-auth my-auth \
  --username=admin --password=secret --export

卸载

# Full removal
flux-operator -n flux-system uninstall

# Keep the namespace
flux-operator -n flux-system uninstall --keep-namespace

# Verify removal
flux-operator version

参考

• references/commands-build-diff-patch.md - build、diff 和 patch 命令
• references/commands-cluster-ops.md - 集群运维（get、reconcile、suspend、resume 等）
• references/commands-secrets.md - 所有 create secret 子命令
• references/commands-skills.md - Skills 管理命令

缩写

简写	完整资源名称
rset	ResourceSet
rsip	ResourceSetInputProvider
ks	Kustomization
hr	HelmRelease

提示

• 在 create secret 命令中使用 --export，可生成 YAML 而不应用它 — 这对于以声明方式管理密钥的 GitOps 工作流很有用。

• trace 会从任意 Kubernetes 对象反向追踪，查找管理该对象的 Flux 协调器以及源清单所在位置。

• 除本地文件外，diff yaml 还接受远程 URL（GitHub、GitLab、Gist、OCI）。

• patch instance 会就地修改 FluxInstance YAML，并替换之前生成的补丁，因此可以安全地重复运行。

• install 面向开发/测试环境。生产环境请使用 Helm charts。