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 ソースまで遡ってたどります。