# k3sのスケールゼロでNodeの追加待ちをPodの側で測定する

## サマリ

- Worker Nodeを0台に縮小するk3sで、Nodeの作成からReadyまでを起動時間として集計すると、0秒になった。
  - Nodeのオブジェクトはkubeletの自己登録で作成され、それより前のEC2・OS・agentの起動を含まない。
  - 観測したNodeでは作成とReadyへの遷移が同じ秒に記録されていた。
- 配置先のないPodの作成から配置までの時間で、Nodeの追加の待機を測定する。
  - 一度でも配置できない状態（`Unschedulable`）を観測したPodに限り、配置前に時刻を保存する。
  - 配置先をWorkerに限定したPodを対象にする。
- 起動を禁止している時間帯にかかる標本は、集計から除外する。

## 背景

self-hosted runnerのWorker Nodeは、ジョブのない時間は0台まで縮小し、費用の削減のため深夜から朝までの時間帯は起動そのものを禁止していた。
runnerの稼働の状況の画面では、Worker Nodeが0台のときに、ジョブの開始までの見込みの時間を利用者に示すため、Nodeの起動の所要時間の90パーセンタイル値（p90）を表示していた。
所要時間はNodeのオブジェクトの作成からReadyまでの時間を7日分集計した値である。
設計の段階では0台からの起動に2〜4分を想定していたが、33件の測定値でp50とp90はどちらも0秒だった。
見込みの時間が最も必要な0台のときに、すぐにジョブが開始するかのような表示になっていた。

## 前提となるNodeとPodの時刻

### Nodeの自己登録

NodeはKubernetesのクラスタへ参加したマシンに対応するAPIのオブジェクトである（EC2のインスタンス1台がNode1つ）。
kubeletはデフォルトでは [起動後にAPIサーバーへNodeを自己登録する](https://kubernetes.io/docs/concepts/architecture/nodes/#self-registration-of-nodes) 。
Nodeのオブジェクトの作成時刻は`metadata.creationTimestamp`である。
マシンの起動（EC2の起動、OSの起動、k3sのagentの起動）と、Nodeのオブジェクトの作成は別の時点である。
k3sでは [制御を担うserverもkubeletを実行してNodeとして登録される](https://docs.k3s.io/architecture) 。

### 条件の遷移の時刻

NodeとPodの`status.conditions`は、ReadyやPodScheduledなどの状態を`True`・`False`・`Unknown`の値で記録する。
ReadyはNodeがPodの実行の準備を完了しているかどうか、PodScheduledはPodがNodeに配置済みかどうかを示す。
各条件の`lastTransitionTime`は、[その条件の`status`が最後に変化した時刻](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions) である。
最初に`True`になった時刻ではないので、`False`への遷移の後に再び`True`になると、後の時刻で上書きされる。
条件は種類ごとに1つだけ保持され、過去の遷移の履歴は保存されない。

### PodScheduledとUnschedulable

PodScheduledは、[PodがNodeに配置済みかどうか](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions) を示すPodの条件である。
配置できるNodeがない場合、schedulerはこの条件を`False`（reason `Unschedulable`）にし、Nodeへの配置が成立するとこの条件は`True`になる。
[Cluster Autoscalerは、追加のNodeに配置できる`Unschedulable`のPodを検出してNodeの追加を検討する](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#how-does-scale-up-work) 。
この状態はCluster AutoscalerがNodeの追加を検討する手掛かりになる。

## Nodeの作成からReadyまでが0秒になる理由

個別のNodeの作成時刻（`metadata.creationTimestamp`）とReadyの条件の遷移の時刻（`lastTransitionTime`）は、同じ秒だった。

```text
node phases: {created: <日付>T07:28:04Z, ready: <日付>T07:28:04Z}
```

Nodeのオブジェクトが作成されるのは、EC2とOSの起動が終了し、k3sのagentのkubeletが登録した時点である。
次の図のとおり、Nodeの登録より前の工程（EC2とOSの起動、agentの起動）は、Podの作成から配置までの区間には含まれ、Nodeの作成からReadyまでの区間には含まれない。

```mermaid
sequenceDiagram
  participant P as Pod
  participant CA as Cluster Autoscaler
  participant E as EC2
  participant K as k3sのagent
  participant N as Nodeのオブジェクト
  participant S as scheduler
  P->>P: 作成（creationTimestamp）
  P->>P: PodScheduled=False（Unschedulable）
  CA->>E: Nodeを追加（EC2を起動）
  E->>K: OSとk3sのagentを起動
  K->>N: kubeletが自己登録（creationTimestamp）
  N->>N: Ready=True（観測では同じ秒）
  S->>P: Nodeに配置（PodScheduled=True）
  Note over P,N: Podの作成から配置までは登録前の工程を含む<br/>Nodeの作成からReadyまでは含まない
```

Nodeの作成時刻とReadyの条件は次のコマンドで確認できる。
Readyの条件が一度`False`や`Unknown`に変化したNodeの`lastTransitionTime`は、起動の時間の算出には使用できない。

```bash
kubectl get node <node-name> \
  -o 'jsonpath={.metadata.creationTimestamp}{"  "}{.status.conditions[?(@.type=="Ready")].status}{"  "}{.status.conditions[?(@.type=="Ready")].lastTransitionTime}{"\n"}'
# 作成時刻、Ready の status、Ready の lastTransitionTime の順に表示される
```

## Podの作成から配置までを測定する

配置先をWorkerに限定したPodは、Workerが0台の間は配置できないので、Nodeの追加の待機はPodの側に記録される。
そこで、`PodScheduled=False`を観測したPodについて、Podの作成時刻から`PodScheduled=True`の`lastTransitionTime`までを測定した。

```bash
kubectl get pod <pod-name> -n <namespace> \
  -o 'jsonpath={.metadata.creationTimestamp}{"  "}{.status.conditions[?(@.type=="PodScheduled")].status}{"  "}{.status.conditions[?(@.type=="PodScheduled")].reason}{"  "}{.status.conditions[?(@.type=="PodScheduled")].lastTransitionTime}{"\n"}'
# 配置前: <日付>T06:21:12Z  False  Unschedulable  <日付>T06:21:12Z
# 配置後: <日付>T06:21:12Z  True     <日付>T06:21:38Z
```

測定の対象は配置先をWorkerに限定したPodである。
Workerを指定しないPodはserverのNodeに配置される場合があり、その場合はこの待機が発生しない。
self-hosted runnerのPodは配置先をWorker Nodeに限定する設定だったので、Workerが0台の間は配置先がない。

### 配置の前に時刻を保存する

配置後は`PodScheduled`の`False`の時刻が`True`の時刻で上書きされるので、配置後のPodの状態からは、そのPodの待機の有無を判別できない。
Podの一覧の取得とwatchでの変更の受信を併用し、`False`の時刻を検出した時点で保存する。
監視の開始の前に配置済みのPodは、待機の有無が不明なので集計の対象外になる。

次の例は`uid`を主キーとするSQLiteのテーブルに、最初に観測した`False`の時刻と配置の時刻を上書きせずに保存する文である。
未観測の時刻の値はNULLにする。

```sql
CREATE TABLE runner_pods (
  uid TEXT PRIMARY KEY,
  created_at TEXT NOT NULL,
  scheduled_at TEXT,
  first_unschedulable_at TEXT
);

INSERT INTO runner_pods (uid, created_at, scheduled_at, first_unschedulable_at)
VALUES (?, ?, ?, ?)
ON CONFLICT (uid) DO UPDATE SET
  scheduled_at = COALESCE(runner_pods.scheduled_at, excluded.scheduled_at),
  first_unschedulable_at = COALESCE(runner_pods.first_unschedulable_at, excluded.first_unschedulable_at);
```

### 集計から除く標本

空きのあるNodeへすぐに配置されたPodを含めると、分布はNodeの追加を待機したPodの値を示さなくなる。
集計は`first_unschedulable_at`のあるPodに限定する。

```sql
SELECT created_at, scheduled_at
FROM runner_pods
WHERE first_unschedulable_at IS NOT NULL
  AND scheduled_at IS NOT NULL
  AND created_at >= ?;
```

Workerが稼働中で空きがない場合も、Podは`Unschedulable`になり、ほかのジョブの完了後にそのWorkerへ配置される。
この待機はNodeの追加を含まない。
集計を配置先のNodeの作成時刻がPodの作成時刻より後の標本に限定すると、配置先が既存のWorkerだった標本は除外される。

もう1つは起動を禁止している時間帯にかかる標本である。
この時間帯に作成されたPodは禁止の解除まで配置されず、その待機を含めると、表示するp90に運用の方針による時間が混入する。
作成から配置までの区間が禁止の時間帯と一部でも重複する標本は、集計から除外した。
禁止の時間帯は毎日の時単位で最短でも1時間あるので、区間の開始から1時間ごとの各時刻と、区間の終了の時刻が、禁止の時間帯の範囲内かを判定する（24時間以上の区間は必ず重複する）。
禁止の時間帯の開始の前に開始し、時間帯の途中で終了する区間では、終了の時刻が時間帯の範囲内になる。
時間帯の全体を含む区間では、1時間ごとの時刻のいずれかが時間帯の範囲内になる。
次は判定の実装の抜粋で、`lock`、`Covers`、`tokyo`は説明用の名前である。

```go
for at := from; at.Before(to); at = at.Add(time.Hour) {
	if lock.Covers(at, tokyo) { // at.In(tokyo).Hour() が StartHour〜EndHour の範囲内か
		return true
	}
}
return lock.Covers(to, tokyo)
```

この判定は夏時間のない`Asia/Tokyo`を前提とする。
夏時間のあるタイムゾーンでは、時単位の時間帯の実際の長さが1時間未満になる日がある。
その日は1時間ごとの判定では重複を検出できない場合がある。
たとえば`Australia/Lord_Howe`では [夏時間の切り替えで時計を30分進める](https://github.com/eggert/tz/blob/main/australasia) ので、2時台の実際の長さは30分になる。
実行イメージにタイムゾーンの情報がない場合、`time.LoadLocation("Asia/Tokyo")`は失敗する。
Goでは [`time/tzdata`](https://pkg.go.dev/time/tzdata) のimportで、タイムゾーンの情報をバイナリに同梱できる。

この値はPodのNodeへの配置までで、イメージの取得やコンテナの起動は含まない。
