仕組み: 1 枚の証明書が
更新されるまで

登場する概念

管理者が API・GUI で操作するのは「名前」だけです．コマンドや資格情報そのものを 直接指定することはできません．次の概念を押さえておくと，以降の図が読みやすくなります．

全体の流れ

以下は，証明書の期限が近づいてから新しい証明書が Certificate Store に格納されるまでの 典型的な流れです．横方向が登場人物，縦方向が時間の経過を表します．

Run の状態遷移

1 回の reconcile 試行は Run というレコードで表され，次のいずれかの状態を持ちます． ある target について，同時に queued／starting／running の run が存在できるのは 1 つだけです．2 つ目を要求すると，アクティブな run を示す 409 run_active が返ります．

更新が必要かの判断

「そろそろ確認する時期か」を決めるのは Conductor のスケジューラですが， 「実際に発行・更新が必要か」を最終的に決めるのは常に Runner です． この 2 つの判断は分かれています．

Result の action は 3 種類です．issued はそのオブジェクトについて store に証明書が存在しなかった場合， renewed は証明書が存在し新しいフィンガープリントが以前と異なる場合， noop は上記の早期終了の場合です．Conductor が「期限到来」と判断した run でも，Runner が証明書はまだ最新だと確認すれば ACME CA には一切接触せず noop で終わります．

Runner の 1 回の実行

Runner は起動されるたびに，ちょうど 1 つの JobSpec を処理してから終了する使い捨てのプロセスです． 次の手順は runner.md: 実行フロー を要約したものです．

1. ジョブを読む — 署名付きエンベロープなら署名を検証し，リプレイ台帳と照合する．
2. 厳密に検証する — 未知のフィールドや重複キーを拒否し，文書が自己整合していることを確かめる（これは認可ではない）．
3. 自身の設定で認可する — RunnerAuthorizationPolicy に照らし，DNS サフィックスとバインディング名を既定拒否で検査する．
4. バインディング名を解決する — acme／dns／store の 3 つの名前を自身の設定の実体（URL・資格情報の変数名など）に変換する．
5. Certificate Store に現在の証明書を問い合わせる — 更新が不要なら noop でここまでにする．
6. 作業ディレクトリを作る — <workDir>/run-<runId>-<rand>（モード 0700）．ACME アカウントの状態だけを状態ディレクトリからコピーする．
7. lego の argv と環境をゼロから組み立てる — Runner プロセス自身の環境は継承しない．JobSpec の値がシェル文字列に補間されることはない．
8. lego をちょうど 1 回起動する — 専用のプロセスグループで，タイムアウト付きで実行する．
9. 生成された証明書を検証する — SAN が target の名前と一致すること，鍵が一致すること，まだ失効していないことなどを確認する．
10. Certificate Store に格納する — ここでのみ証明書と秘密鍵が永続化される．
11. 作業ディレクトリを破棄する — defer により，成功・失敗を問わずすべての経路で実行される．これが秘密鍵のローカルコピーを消す唯一の処理である．
12. Result を出力して終了する — stdout に 1 行の JSON，指定があればファイルにも．

引数ベクトルは常に固定の順序で組み立てられ（--accept-tos --email … --server … --dns … --domains … --key-type … --path … の後に run），シェルは一度も起動されません．EAB のキー ID と HMAC は argv ではなく LEGO_EAB_KID／LEGO_EAB_HMAC という環境変数で渡されるため，プロセス一覧には現れません． 詳しくはrunner.md: lego の起動を参照してください．

JobSpec と Result の例

Conductor と Runner の間を行き来する文書はこの 2 種類だけです．どちらも厳密にデコードされ （未知のフィールドと重複キーは拒否），現れるのは不透明な識別子・正規化された FQDN・ ポリシーの値・論理バインディング名だけです．

JobSpec（CertificateReconcileJob．実例）:

{
  "apiVersion": "acme-conductor.cits-nue.github.io/v1alpha1",
  "kind": "CertificateReconcileJob",
  "runId": "01JABCDEFGHJKMNPQRSTVWXYZ0",
  "target": { "id": "01JABCDEFGHJKMNPQRSTVWXYZ1", "fqdn": "wiki.example.ac.jp", "revision": 3 },
  "policy": {
    "allowedDnsSuffixes": ["example.ac.jp"],
    "allowWildcard": false,
    "renewBeforeDays": 30,
    "keyType": "ec256"
  },
  "acme": { "binding": "letsencrypt-staging" },
  "dns": { "binding": "azure-dns-staging" },
  "store": { "binding": "filesystem-dev" }
}

Result（CertificateReconcileResult）成功時:

{
  "kind": "CertificateReconcileResult",
  "runId": "01JABCDEFGHJKMNPQRSTVWXYZ0",
  "status": "succeeded",
  "action": "issued",
  "expiresAt": "2026-12-19T00:00:00Z",
  "fingerprintSha256": "a1b2c3d4…",
  "storeObjectRef": "www-example-ac-jp",
  "error": null
}

失敗時:

{
  "kind": "CertificateReconcileResult",
  "runId": "01JABCDEFGHJKMNPQRSTVWXYZ0",
  "status": "failed",
  "action": "failed",
  "error": { "code": "DnsFailure", "summary": "TXT record propagation timed out" }
}

どちらの文書にも 決して現れないもの があります: シェルコマンド，実行ファイルの パス，任意の環境変数，コンテナイメージの参照，クライアントシークレットやアクセスキーや秘密鍵， 任意のクラウドリソース ID，任意の出力パスです．そのためのフィールドがそもそも存在しません． error.summary も lego の生の出力や環境変数のダンプではなく，Runner が持つ安全な テンプレートからのみ生成されます．詳しくは architecture.md: JobSpec/Result コントラクト と runner.md: Result とエラーコード を参照してください．

障害時の振る舞い

この設計により，Conductor 側の「結果不明」という保守的な記録と，Runner 側の 「Store に問い合わせてから判断する」という冪等な振る舞いの組み合わせだけで， 二重発行や証明書の取りこぼしを防いでいます．詳しくは conductor.md: シャットダウンと復旧 を参照してください．