flux-operator-cli

Flux Operator CLI

インストール

brew install controlplaneio-fluxcd/tap/flux-operator

~/.kube/config を使用します。オフライン（クラスターなし）とオンラインのコマンドに対応しています。

コマンド概要

コマンドは、オフライン（クラスターへのアクセス不要）とオンライン（クラスターが必要）の2種類に分かれます。

オフラインコマンド（クラスター不要）

コマンド	目的
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 - ビルド、差分、パッチの各コマンド
• references/commands-cluster-ops.md - クラスター運用（get、reconcile、suspend、resume など）
• references/commands-secrets.md - create secret のすべてのサブコマンド
• references/commands-skills.md - スキル管理コマンド

略語

略称	リソースの正式名称
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 チャートを使用してください。