flux-cli

Flux CLI

安装

brew install fluxcd/tap/flux
# or: curl -s https://fluxcd.io/install.sh | sudo bash

默认命名空间为 flux-system。使用 ~/.kube/config。

命令概览

引导 — 通过 GitOps 在集群上初始化 Flux

flux bootstrap github|gitlab|gitea|bitbucket-server|git|azure-devops

# Example
flux bootstrap github \
  --owner=my-org \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production \
  --personal

源 — Flux 获取清单和图表的位置

# Create sources
flux create source git <name> --url=<repo-url> --branch=<branch>
flux create source helm <name> --url=<chart-repo-url>
flux create source oci <name> --url=<oci-url>
flux create source bucket <name> --bucket-name=<name> --endpoint=<url>

# Query sources
flux get sources all|git|helm|oci|bucket|chart
flux export source git|helm|oci|bucket [name] [--all]
flux reconcile source git|helm|oci|bucket|chart <name>
flux suspend source git|helm|oci|bucket <name>
flux resume source git|helm|oci|bucket <name>
flux delete source git|helm|oci|bucket <name>

Kustomization — 从源部署清单

# Create
flux create kustomization <name> \
  --source=GitRepository/<source-name> \
  --path=./path \
  --prune=true

# Build locally (preview what would be applied)
flux build kustomization <name> --path=./local/path

# Diff against cluster (exit 0=no diff, 1=has diff)
flux diff kustomization <name> --path=./local/path

# Manage
flux get kustomizations
flux reconcile kustomization <name>
flux suspend kustomization <name>
flux resume kustomization <name>
flux export kustomization <name>
flux delete kustomization <name>

Helm 发布 — 部署 Helm 图表

# From a HelmRepository
flux create helmrelease <name> \
  --source=HelmRepository/<repo-name> \
  --chart=<chart-name> \
  --chart-version=">=1.0.0" \
  --values=./values.yaml

# From a GitRepository
flux create helmrelease <name> \
  --source=GitRepository/<repo-name> \
  --chart=./charts/my-chart

# Manage
flux get helmreleases
flux reconcile helmrelease <name>
flux suspend helmrelease <name>
flux resume helmrelease <name>
flux export helmrelease <name>
flux delete helmrelease <name>
flux debug helmrelease <name>

镜像自动化 — 自动更新镜像

# Set up image scanning
flux create image repository <name> --image=<registry/image>
flux create image policy <name> \
  --image-ref=<repo-name> \
  --select-semver=">=1.0.0"

# Set up auto-update
flux create image update <name> \
  --git-repo-ref=<git-source> \
  --git-repo-path=./clusters \
  --checkout-branch=main \
  --push-branch=main \
  --author-name=flux \
  [email protected]

# Query
flux get images all|repository|policy|update
flux reconcile image repository|policy|update <name>

告警与接收器 — 通知

# Create an alert provider (Slack, Teams, GitHub, etc.)
flux create alert-provider <name> \
  --type=slack \
  --channel=general \
  --address=https://hooks.slack.com/...

# Create an alert
flux create alert <name> \
  --provider-ref=<provider-name> \
  --event-source="Kustomization/*"

# Webhook receivers (trigger reconciliation from external events)
flux create receiver <name> \
  --type=github \
  --event=push \
  --resource=GitRepository/<source-name> \
  --secret-ref=webhook-secret

密钥 — 源的身份验证

flux create secret git <name> --url=<repo-url> --username=<u> --password=<p>
flux create secret helm <name> --username=<u> --password=<p>
flux create secret oci <name> --url=<registry> --username=<u> --password=<p>
flux create secret tls <name> --cert-file=cert.pem --key-file=key.pem
flux create secret proxy <name> --address=<proxy-url>
flux create secret githubapp <name> --app-id=<id> --app-installation-id=<id> \
  --app-private-key-file=key.pem

OCI 制品 — 以 OCI 镜像的形式推送/拉取清单

# Push local manifests to an OCI registry
flux push artifact oci://<registry>/<name>:<tag> \
  --path=./manifests \
  --source=https://github.com/org/repo \
  --revision=main@sha1:abc123

# Pull artifact locally
flux pull artifact oci://<registry>/<name>:<tag> --output=./output

# Tag, list, diff
flux tag artifact oci://<registry>/<name>:<tag> --tag=latest
flux list artifacts oci://<registry>/<name>
flux diff artifact oci://<registry>/<name>:<tag> --path=./local

诊断与调试

# View controller logs
flux logs [-f] [--level=error] [--kind=Kustomization] [--name=my-app] [-A]

# View events
flux events [--for=Kustomization/<name>] [-A]

# Trace an object through the GitOps pipeline
flux trace <kind> <name> [-n <namespace>]

# View resource tree under a Kustomization/HelmRelease
flux tree kustomization|helmrelease <name> [-n <namespace>]

# Reconciliation statistics
flux stats

# Check Flux prerequisites and installation
flux check

安装与生命周期

# Install Flux controllers (without bootstrap)
flux install [--components=source-controller,kustomize-controller,...]

# Uninstall Flux
flux uninstall

# Check installation health
flux check

# Version info
flux version

常见工作流

引导并部署应用

# 1. Bootstrap Flux on a cluster
flux bootstrap github --owner=my-org --repository=fleet --path=clusters/prod --personal

# 2. Verify bootstrap succeeded
flux check
flux get all

# 3. Create a source
flux create source git my-app \
  --url=https://github.com/my-org/my-app \
  --branch=main --interval=1m

# 4. Deploy via Kustomization
flux create kustomization my-app \
  --source=GitRepository/my-app \
  --path=./deploy --prune=true --interval=5m

# 5. Verify reconciliation
flux get kustomization my-app

部署 Helm 图表

# 1. Add the chart repo
flux create source helm bitnami \
  --url=https://charts.bitnami.com/bitnami --interval=1h

# 2. Create the release
flux create helmrelease nginx \
  --source=HelmRepository/bitnami \
  --chart=nginx \
  --chart-version=">=15.0.0" \
  --values=./nginx-values.yaml

# 3. Verify release is ready
flux get helmrelease nginx

应用前预览更改

# Build locally
flux build kustomization my-app --path=./deploy

# Diff against live cluster
flux diff kustomization my-app --path=./deploy

调试失败的协调

# Check what's failing
flux get all -A --status-selector ready=false

# View logs for errors
flux logs --level=error -f

# Trace a specific object
flux trace deployment my-app -n default

# Debug a HelmRelease
flux debug helmrelease my-release -n default

导出以进行备份/迁移

# Export everything
flux export source git --all > sources.yaml
flux export kustomization --all > kustomizations.yaml
flux export helmrelease --all > helmreleases.yaml

维护窗口

# Suspend all kustomizations
flux suspend kustomization --all -n flux-system

# Do maintenance...

# Resume
flux resume kustomization --all -n flux-system

参考资料

• references/bootstrap.md - 所有 flux bootstrap 子命令及特定于提供商的标志
• references/sources.md - flux create source git|helm|oci|bucket 的所有标志
• references/kustomizations.md - Kustomization 创建、构建和差异比较命令
• references/helmreleases.md - flux create helmrelease 的所有标志
• references/artifacts-and-images.md - OCI 制品和镜像自动化命令

全局标志

所有命令都继承标准 Kubernetes 标志：

标志	默认值	说明
--kubeconfig	~/.kube/config	kubeconfig 的路径
--context	—	kubeconfig 上下文
-n, --namespace	flux-system	命名空间范围
--timeout	5m	操作超时时间
--verbose	—	打印生成的对象
--export	—	将 YAML 输出到标准输出，而不是应用

提示

• 对任何 create 命令使用 --export 都会生成 YAML 而不应用——将其通过管道传输到文件， 并提交到 Git，实现真正的 GitOps。
• flux get all -A --status-selector ready=false 可以快速发现问题。
• 如果存在差异，flux diff kustomization 会以代码 1 退出——可用于 CI 流水线门禁。
• flux reconcile 会立即触发同步，而不是等待间隔时间。
• flux trace 会从任意 Kubernetes 对象反向追踪到其 Flux 源。