[MRyutaro]

背景・課題

外部オーケストレーターが保存/復元のタイミングを制御するカーネルでは、起動時の自動復元・停止時の自動保存が邪魔になる。とくに ElasticHub の zero-reload マイグレーションでは、保存も復元も明示 API のタイミングに寄せたい:

• 保存 … 旧カーネルを殺さず明示 API（POST /elastic_kernel/checkpoint）で保存する。その後の旧 pod 削除時に do_shutdown がまた自動保存すると、共有 NFS の同じ checkpoint を二重に上書きし teardown を遅らせる → 停止時の自動保存は切りたい。
• 復元 … 移行先のカーネルをあらかじめ起動して待機させておき、切り替えの瞬間に明示 API（POST /elastic_kernel/restore）で任意のタイミングで復元する。復元をカーネル起動（__init__）と密結合させないことで、カーネルの再起動時間をクリティカルパスから排除できる → 起動時の自動復元も切り、復元タイミングを外から制御したい。

保存と復元は独立に切れる必要がある（用途によって片方だけ切りたいこともある）。単一フラグでは両者をまとめてしか切れない。

さらに、env 変数だけだと起動時にしかモードを決められない。「どの pod が移行対象か」は起動時には分からず、実行中のカーネルに対して任意のタイミングで切り替える手段も必要だった。ただし実行時に意味を持つのは「停止時の自動保存」だけで、復元は __init__ の一度きりのイベントなので起動後に切り替えても効果がない。そのため実行時の切り替えは保存側のみを対象とする。

変更内容

自動保存と自動復元を独立に切り替えられるようにした。フラグ名は「いつ起きるか」を表す（checkpoint_on_shutdown = 停止時の保存、restore_on_startup = 起動時の復元）。設定は2段構え:

1. 起動時の初期モード（環境変数）

環境変数	既定	効果
ELASTIC_KERNEL_CHECKPOINT_ON_SHUTDOWN	有効	0/false/no/off で停止時(do_shutdown)の自動保存を無効化
ELASTIC_KERNEL_RESTORE_ON_STARTUP	有効	同上で起動時(__init__)の自動復元を無効化

• 両フラグは __init__（起動時）に一度だけ評価され self.checkpoint_on_shutdown / self.restore_on_startup の初期値になる。
• 起動モードはログ Auto checkpoint: on_shutdown=on|off, on_startup=on|off で確認できる。

どう渡すか（誰がこの env を使ってカーネルを起動するか）: これらはカーネルプロセスの環境変数なので、カーネルを起動する側がプロセスの環境に載せる。素の POST /api/kernels の body では任意の env を受け取れない点に注意（別途プロビジョナ等が必要）。実用的には次のいずれか:

• singleuser pod / サーバープロセスの環境に設定する（最も手軽・推奨）。JupyterHub なら KubeSpawner の environment などで pod に与えれば、その上で起動する全カーネルが継承する。「全 elastic カーネルで停止時保存 OFF」のような一括設定はこれで済む。
• カーネル起動 API に env を渡す。jupyter_client の KernelManager.start_kernel(env=...) や、ElasticHub の elastic_id_shim が同一 kernel_id でカーネルを起動する km.start_kernel(..., env=...) 経路に os.environ ＋上書きを載せる。pod 単位ではなくカーネル単位でモードを変えたいときはこちら。

import os
env = dict(os.environ, ELASTIC_KERNEL_CHECKPOINT_ON_SHUTDOWN="0")
# kernel_manager.start_kernel(env=env) など、起動 API に env として渡す

2. 実行時の上書き（control メッセージ / REST）— 停止時の自動保存のみ

起動後にモードを変えたい場合、走行中のカーネルへ切り替えを送れる。対象は停止時の自動保存のみ（復元は起動時に決まるので実行時の対象外）。

• control メッセージ elastic_set_checkpoint_on_shutdown … {enabled: bool} を送ると self.checkpoint_on_shutdown を差し替え、更新後の現在値を返す。enabled 省略時は現在値を返すだけの read-only 照会。
• REST POST /elastic_kernel/checkpoint_on_shutdown … checkpoint/restore と同じ流儀でオーケストレーターから HTTP で叩ける（body は enabled・bool・必須。無いと 400）。GET /elastic_kernel/checkpoint_on_shutdown?kernel_id=<id> で read-only に現在値を照会できる。
• フラグの読み書きだけで user_ns に触れないため、保存/復元と違いメインループの空き待ちが不要で、セル実行中でも割り込んで切り替えられる。

無効化しても、明示的な保存/復元（control メッセージ・REST API）は引き続き機能する。

ElasticHub での使い分け

全 elastic カーネルを auto（既定）のまま起動しておき、移行対象に決めた瞬間にその pod だけ実行時に停止時の自動保存を false へ倒す、という流れにできる。移行対象では保存・復元とも明示 API に寄せ、とくに復元は移行先カーネルを先に起動して待機させておき切り替え時に明示復元することで、カーネルの再起動時間をクリティカルパスから外す。env を起動時に固定する方式と違い「移行する pod だけ手動」を後から選べるので、culling 等の通常停止で保存されなくなる副作用を移行対象以外に及ぼさずに済む。

検証

• flake8 クリーン、black/isort 適用済み、mypy issues なし
• pytest 全体: 97 passed, 16 skipped（skip は既存）

🤖 Generated with Claude Code

https://claude.ai/code/session_014fHMAFLuxVkdQ1u4PAU3Sr