prefect

これは prefect.utilities.schema_tools.validation.process_properties() のバグが原因です（main コミット 148e9978 の Prefect 3.8.7.dev6 で再現されています）。このループは required_fields をネストされたオブジェクトの required リストに再バインドするため、後続の兄弟プロパティが誤ったリストに対して検証されてしまいます。また、再帰呼び出しでも allow_none_with_default が引き継がれません。

issue #23189 の修正を含む Prefect リリースにアップグレードしてください。main から開発版をインストールする場合：

python -m pip install --upgrade "prefect @ git+https://github.com/PrefectHQ/prefect.git"

ソースを直接修正する場合は、required_fields を再代入する代わりに、ネストされた必須フィールド用に別の変数を使用してください：

if "properties" in schema:
nested_required = schema.get("required", [])
process_properties(
schema["properties"],
nested_required,
allow_none_with_default=allow_none_with_default,
)

プロパティループ内で required_fields = schema.get("required", []) を使用しないでください。

一時的な回避策：各スキーマレベルで、ネストされたオブジェクトのプロパティをすべての兄弟プロパティより後に配置してください。また、デフォルト値を持つネストされたフィールドでは allow_none_with_default に依存しないでください。明示的なデフォルト値を送信するか、None が実際に許可される場合にのみ "type": ["string", "null"] でフィールドを nullable として宣言してください。

これは Prefect 3.8.8 に影響します。Cloud のメンテナンス中、API コールは Prefect-Maintenance: true と Retry-After を伴う 503 を返すため、ランナーはポーリングをバックオフします。その後、/health エンドポイントは PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE × PREFECT_RUNNER_POLL_FREQUENCY（デフォルトでは 2 × 10 = 20 秒）の経過後に 503 を返し、また最初のポーリングが完了する前に 500 を返すことがあり、その結果ライブネスプローブによってランナーが再起動されます。

**恒久対応:** issue #23326 に対するランナーのメンテナンスヘルスチェック修正を含むリリースへ Prefect をアップグレードしてください:

pip install -U prefect

修正済みのバージョンでは、クライアントがメンテナンスによるバックオフに従っている間 /health は正常な状態を維持し、最初のポーリングが成功する前にエラーになることはなくなります。

**影響を受けるバージョンでの回避策:** ポーリング欠落のしきい値を想定されるメンテナンス期間よりも長く設定します:

export PREFECT_RUNNER_POLL_FREQUENCY=10
export PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE=60

これにより、/health が異常と報告するまでに 600 秒（60 × 10）の猶予が生まれます。

Kubernetes では、プローブにも同じ期間を許容させ、メンテナンス中に起動するプロセスにはスタートアッププローブを使用してください:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  periodSeconds: 10
  failureThreshold: 60
  timeoutSeconds: 5
startupProbe:
  httpGet:
    path: /health
    port: 8080
  periodSeconds: 10
  failureThreshold: 60

スタートアッププローブが重要なのは、flow.serve()/serve() がランナーの Web サーバーの起動前にデプロイメントを登録するため、起動処理がメンテナンスの終了を待っている間 /health が接続を拒否する可能性があるからです。

フローピッカーは pathlib.Path を str(path) で文字列に変換しますが、これは Windows ネイティブのバックスラッシュを使用します。エントリーポイントは、flows/hello.py:my_flow のような POSIX スタイルのフォワードスラッシュを使用すべきです。

prefect/_internal/ast_utils.py 内の find_prefect_decorated_functions_in_file で、以下を置き換えることで修正します:

"filepath": str(path)

これを次のように:

"filepath": path.as_posix()

フォワードスラッシュのパスは Windows 上でも正しく動作し、期待される path/to/file.py:function_name というエントリーポイント形式を生成します。

一時的な回避策:
1. 手動エントリーポイントオプションを選択し、フォワードスラッシュを使用してパスを入力します: path/to/file.py:function_name。
2. バックスラッシュが prefect.yaml に保存されていた場合は、手動でフォワードスラッシュに置き換えてください。
3. POSIX パスの修正を含むリリースに Prefect をアップグレードしてください。

Prefect 3.8.7 では、Cloud のメンテナンス応答（Prefect-Maintenance: true と Retry-After を伴う 503）がワーカーのポーリングをブロックします。約300秒後（PREFECT_WORKER_QUERY_SECONDS × 30）に /health が 503 を返し、Kubernetes がワーカーを再起動します。再起動後も、setup() が完了するまでヘルスポートは利用できないため、プローブの失敗が繰り返し発生します。

公式の prefect-worker Helm チャートを使った即時の回避策: 既知のメンテナンス時間帯は liveness プローブを無効にします:

livenessProbe:
  enabled: false

次のコマンドで適用します:

helm upgrade worker prefect/prefect-worker -f values.yaml

または:

helm upgrade worker prefect/prefect-worker --set livenessProbe.enabled=false

メンテナンス時間帯が終了したら、プローブを再度有効にしてください。ワーカーがメンテナンスのバックオフ状態にとどまる時間は固定のしきい値よりも長くなる可能性があるため、プローブのしきい値やポーリング間隔を増やす方法は信頼できません。

恒久対策: ワーカー向けの PR #23230 を含む Prefect リリースにアップグレードしてください。この修正では、ヘルス評価時にメンテナンスのバックオフ終了時刻を追跡し、setup() の前にヘルスサーバーを起動するため、メンテナンス中も /health が利用可能な状態が維持されます。Runner または flow.serve() を使用するデプロイメントでは、別途ランナーのヘルスチェックに関するフォローアップ修正も必要です。

これは、3.8.7 や 3.8.8 などのバージョンの Prefect ワーカーに影響します。ポーリングが、ワーカーがすでに実行中のフロー実行を返すことがあります。サブミッション ID はインフラストラクチャの起動後にクリアされますが、CapacityLimiter トークンは実行が終了するまで保持されたままになります。ワーカーは anyio.WouldBlock のみをキャッチするため、トークン重複による RuntimeError がポーリングループを終了させます。

推奨される修正: issue #23340 の修正を含むパッチ適用済みの Prefect リリースにアップグレードし、その後ワーカーを再起動してください:

python -m pip install -U prefect
prefect version

パッチ適用済みのバージョンでは、重複したサブミッションはワーカーをクラッシュさせる代わりに、ログに記録されスキップされます。

アップグレードできない場合の即時の回避策:

1. クラッシュしたワーカーを再起動して、ポーリングを再開します。
2. ワーカーコマンドから --limit を削除します。これによりリミッターを回避できますが、ローカルの同時実行数の上限も解除されます。
3. ソースパッチとして、prefect/workers/base.py の _submit_scheduled_flow_runs でリミッターの取得処理をラップし、重複トークンがスキップされるようにします:

try:
    self._limiter.acquire_on_behalf_of_nowait(flow_run.id)
except RuntimeError as exc:
    if "already holding one of this CapacityLimiter's tokens" in str(exc):
        logger.info(
            "Duplicate submission of flow run %s detected; skipping",
            flow_run.id,
        )
        continue
    raise
except anyio.WouldBlock:
    # Keep the existing WouldBlock handling here
    ...

パッチを適用した後、ワーカーを再起動してください。