2026.05.19

PipeCD v0.56.0 リリース ─ 7 ヶ月ぶりの安定版で Kubernetes 利用者が押さえるべき変更点

saratogax

記事内に商品プロモーションを含む場合があります

2026 年 5 月 13 日、CD ツールの PipeCD が v0.56.0 としてリリースされました。

前回の安定版 v0.55.0 が 2025 年 10 月 8 日なので、およそ 7 ヶ月ぶりの安定版リリースです。

この間、開発リソースが pipedv1（プラグインアーキテクチャ）に集中していたこともあり、v0.55.x 系を本番運用している人にとっては久々のアップデート機会となります。

本記事では、Kubernetes (pipedv0) で PipeCD を使っている運用者目線で、v0.55.0 → v0.56.0 の変更点のうち押さえておくべきものを整理します。

特に新設の spec.planPreview 設定と、plan-preview がエラーになるときの切り分け方を中心に扱います。

前提となる PipeCD の開発状況や移行判断の話は別記事にまとめています。

PipeCD 2026 年の現状と今後の移行判断

Contents

v0.56.0 のリリース概要
Kubernetes 利用者目線で効く変更点
spec.planPreview の各パラメータ
plan-preview が失敗するときの切り分け
pipedv1 プラグイン基盤の進捗
アップグレードを判断するなら
まとめ
関連リンク

v0.56.0 のリリース概要

v0.56.0 のリリースノートを見ると、変更項目の大半は pipedv1 プラグイン（ECS / kubernetes_multicluster）の実装進捗で占められています。

そのため、現行の pipedv0 + Kubernetes 利用者から見ると、「変更行数は多いが、自分に直接効く変更は少ない」という見え方になりがちです。

とはいえ、Kubernetes 利用者にも効く変更がいくつかあり、特に Plan Preview の挙動を piped 設定で構成できるようになったのは運用上のメリットが大きいです。

Kubernetes 利用者目線で効く変更点

1. Plan Preview の設定可能化（最大の目玉）

従来、plan-preview の挙動（ワーカー数、コマンドキューのバッファサイズ、ポーリング間隔、1 件あたりのタイムアウト）は、コード内部の定数として固定されていました。

v0.56.0 からは、これらが piped 設定の spec.planPreview ブロックで構成できるようになります。

背景となった Issue は pipe-cd/pipecd#5916、変更 PR は pipe-cd/pipecd#6646 です。

2. EventWatcher の nil pointer dereference 修正

EventWatcher が再 clone を試みる際に nil pointer dereference で落ちるバグが修正されました（pipe-cd/pipecd#6356）。

EventWatcher を使っている場合、稀に発生していた piped の panic が解消されます。

3. OIDC ログイン時の avatarURL 修正

ControlPlane の OIDC 認証で、avatarURL claim key の条件分岐に不具合がありアバター画像が表示されないケースが直りました（pipe-cd/pipecd#6630）。

4. 依存ライブラリの更新

利用者が意識することは無いですが、セキュリティ観点で押さえておきたい更新が複数入っています。

google.golang.org/grpc を 1.64.1 / 1.71.0 系 → 1.79.3 系に一括更新
go.opentelemetry.io/otel/sdk を 1.28.0 → 1.43.0 に更新
github.com/go-jose/go-jose/v4 を複数モジュールで更新
Web UI 側の node-forge / follow-redirects / lodash なども更新

逆に、影響しないもの

リリースノートの大半を占める [Multi_K8s-Plugin] や [ECS-Plugin] 系のコミットは、すべて pipedv1 プラグインアーキテクチャ向けです。

pipedv0 で kind: KubernetesApp を使っている現状の運用には直接影響しません。

spec.planPreview の各パラメータ

v0.56.0 で追加された spec.planPreview ブロックには 4 つのパラメータがあります。

いずれも省略可能で、省略時は従来と同じデフォルト値が適用されます。

キー	型	デフォルト	用途
`workerNum`	int	`3`	plan-preview コマンドを処理するワーカー goroutine 数
`commandQueueBufferSize`	int	`10`	内部コマンドチャネルのバッファサイズ
`commandCheckInterval`	duration	`5s`	新しい plan-preview コマンドのポーリング間隔
`commandHandleTimeout`	duration	`5m`	コマンド自体が timeout を指定しなかったときの、1 件あたりのビルドタイムアウト

※表は横スクロールできます

設定例は次のようになります。

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  # ... 既存の設定 ...
  planPreview:
    workerNum: 5
    commandQueueBufferSize: 20
    commandCheckInterval: 5s
    commandHandleTimeout: 10m

負の値を渡すと piped 起動時のバリデーションで失敗します。

また、内部実装では 0 を渡しても無視されてデフォルト値が使われる仕様になっており、誤って 0 動作になる事故は起きにくい作りです。

plan-preview が失敗するときの切り分け

「plan-preview がよくエラーになる」という相談を受けることがあります。

v0.56.0 の新設定で直る種類のエラーと、そうでないエラーがあるので、まず切り分けが必要です。

PR コメントに出る代表的なエラー

例えば次のようなエラーメッセージが GitHub の PR コメントに出ることがあります（アプリ名等はダミーに置き換えています）。

NOTE
An error occurred while building plan-preview for the following applications

app: sample-api, env: test, kind: kubernetes
Reason: failed while planning, error while preparing deploy source data (err: exit status 128, out: Preparing worktree (detached HEAD xxxxxx)
fatal: failed to read /tmp/gitcache999999/sample-kubernetes/worktrees/repo9/commondir: No error information
)

An error occurred while building plan-preview for applications of the following Pipeds

piped: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Reason: Timed out, maybe the Piped is offline currently.

このエラーは、一見すると「piped が offline」と書かれているため piped Pod のクラッシュを疑いがちです。

しかし実際には piped Pod は稼働しており、再起動もしていないケースが多くあります。

piped 内部の git キャッシュ構造

このエラーを理解するには、piped が git リポジトリをどう扱っているかを知っておく必要があります。

piped は起動時に /tmp/gitcache<乱数> ディレクトリを 1 つ作成します。

そして対象リポジトリを git clone --mirror でベアリポジトリとしてキャッシュします。

plan-preview や deploy で実際に作業ディレクトリが必要になるたびに、このキャッシュから git worktree add --detach で worktree を切り出して使う仕組みです。

つまり、ファイルシステム上は次のような構造になります。

/tmp/gitcache999999/
└── sample-kubernetes/        # ベアリポジトリ（--mirror）の実体
    ├── HEAD
    ├── objects/
    ├── refs/
    └── worktrees/
        └── repo9/             # 切り出した worktree の管理エントリ
            ├── commondir      # ベアリポジトリ本体への参照
            ├── HEAD
            └── ...

このうち commondir ファイルは、worktree からベアリポジトリ本体を指し示す重要なメタデータです。

これが読めなくなると、git は「この worktree がどのリポジトリに属するか分からない」状態になり、上記のエラーが発生します。

「Piped is offline」の正体

個別アプリでエラーが出た上で全体が Timed out, maybe the Piped is offline になるのは、ControlPlane から見て plan-preview コマンドの結果が commandHandleTimeout 内に返ってこなかった、という意味です。

つまり piped プロセスの健全性とは別物で、Pod が落ちているとは限りません。

「複数アプリ対象の plan-preview のうち、最初の何件かで早期に失敗し、残りを処理する前に全体タイムアウトに到達した」というパターンで、このメッセージが出やすくなります。

commondir が読めなくなる原因の候補

commondir: No error information の典型的な原因候補は次のとおりです。

/tmp の容量不足や自動掃除：piped の /tmp を Kubernetes の emptyDir で振っている場合、サイズリミットや evict、systemd-tmpfiles 等の自動掃除によってベアリポジトリの一部ファイルが消えることがあります。
worktree の残骸：並列で走る別の plan-preview や deploy が worktree のクリーンアップに失敗し、worktrees/repoN/ のメタデータだけ残るケース。
ディスク full：単純に /tmp 配下を含むストレージが書き込めなくなっているケース。

どれが該当するかを観察事象から特定するには、エラー発生直後に piped Pod 内で次のような確認をするのが手早いです。

kubectl exec -it <piped-pod> -- ls -la /tmp/gitcache*/<repoID>/worktrees/
kubectl exec -it <piped-pod> -- df -h /tmp
kubectl describe pod <piped-pod>   # Events に evict 等が無いか確認

v0.56.0 の新設定で「直る/直らない」の整理

v0.56.0 で追加された spec.planPreview 設定は、plan-preview のスループットや待ち時間に効く設定です。

しかし commondir not found のような ファイルシステム起因のエラーは設定では直りません。

症状別に整理すると次のとおりです。

context deadline exceeded が頻発（clone やビルドが遅い）→ commandHandleTimeout を 5m から 10m 〜 15m に伸ばすのが第一選択。
複数 PR 同時で反応しない→ workerNum を 3 から 5〜10 に、commandQueueBufferSize を 10 から 20〜50 に増やす。
plan-preview が走り始めるまで体感が遅い→ commandCheckInterval を 5s から 2s に短縮（ControlPlane への poll は増える）。
commondir: No error information 系→ 設定では解消しない。/tmp の置き場、容量、emptyDir の sizeLimit、ノードの evict 履歴を確認するのが先。

むしろ後者のケースで workerNum を闇雲に増やすと、worktree の並列競合が増えて状況が悪化する可能性もあるので注意が必要です。

pipedv1 プラグイン基盤の進捗

本記事の主題からは外れますが、v1 GA を待っている方向けに進捗だけ触れておきます。

v0.56.0 リリースサイクルでは、次世代の pipedv1 プラグインアーキテクチャに対して大量のコミットが入りました。

ECS プラグイン：SYNC / PRIMARY ROLLOUT / CANARY ROLLOUT / CANARY CLEAN / TRAFFIC ROUTING / ROLLBACK / Plan Preview / Livestate を連続実装。
kubernetes_multicluster プラグイン：Primary / Baseline / Canary の各 Rollout・Clean、Traffic Routing、livestate drift detection 修正、per-target kustomizeDir 対応など。

v1 GA はまだですが、v0.55.0 リリース時点から比べると プラグイン側の実装が一段進んだリリースと言えます。

アップグレードを判断するなら

Kubernetes (pipedv0) で運用している場合、v0.55.0 から v0.56.0 へのアップグレードは「劇的な機能追加は無いが、上げて損は無い」という温度感です。

特に次のいずれかに該当するなら、上げる価値があります。

plan-preview のタイムアウトや反応の遅さに不満があり、設定でチューニングしたい
EventWatcher を使っており、稀に piped が panic することがある
ControlPlane で OIDC を使っており、アバター表示の不具合が気になる
依存ライブラリの脆弱性対応をまとめて取り込みたい

逆に「plan-preview が commondir 関連で失敗している」のが主な悩みなら、まずは /tmp の置き場と容量を見直してからアップグレードに進むのが順番として正解です。

まとめ

v0.56.0 は、Kubernetes (pipedv0) 利用者にとって変更行数の割に直接の恩恵は限定的です。

ただし、spec.planPreview の追加は plan-preview を実運用しているチームには地味に効きます。

plan-preview のエラーは 「設定で直るもの」と「ファイルシステム起因で直らないもの」をまず切り分けるのが大事です。

本記事の切り分け手順とパラメータ表が、誰かの運用判断の参考になれば幸いです。