アーティファクト・イメージ保管の設計 — 何を成果物として残しどうバージョンするか

ビルドパイプラインが整っていても、成果物の保管設計が後回しになると、6か月後には「同じバージョンを再現できない」「どれが本番稼働中か判断できない」という状態が待っている。設計判断として問われるのは、何を保管対象とし何を都度再ビルドするかの境界、イミュータブルなバージョン付けの設計、保持世代とクリーンアップの自動化、そして肥大化を防ぐ削除基準の明確化だ。これらを設計段階で決めておかないと、運用が進むほど「削除できない」「探せない」の二重苦に陥る。

ビルド成果物を場当たりで置いて再現できなくなる構造

ビルド環境への依存が再現不能を生む

ローカルマシンでビルドした成果物をそのままサーバーへ配置するという運用は、環境が数台のうちは問題が表面化しません。ところが環境数が10を超えた段階で「別のマシンでビルドしたバイナリが動かない」という事態が頻発し始めます。ビルド時のライブラリバージョン、コンパイラのマイナーバージョン、OSに依存したリンクパスが異なれば、ファイル名が同じでも中身は別物になります。この問題に気づくころには本番リリースを何度も重ねた後であることが多く、手戻りの規模が大きくなっています。保管設計の失敗は、ビルド失敗よりも遅れて表面化する点が厄介です。

タグなし・命名ルールなしで積み上がるリスク

「日付だけをファイル名にしている」という管理は短期間は機能しますが、担当者が変わるタイミングで破綻します。引き継いだ担当者がストレージを開くと、日付だけのディレクトリが100個以上並んでおり、どれが本番稼働中のバイナリと対応するかの調査に2日以上かかったという話を現場でよく聞きます。コンテナイメージの場合、タグを付けずにlatestのまま上書きし続けると、ロールバック時に戻す先が存在しないという状況を招きます。「保存してある」と「再現できる状態で保存してある」は、設計レベルで全く異なる概念です。

チームが拡大すると「誰がビルドしたか」が消える

担当者が複数になると、ビルド時の環境変数・使用したDockerfileのコミットハッシュ・依存パッケージのロックファイルがアーティファクトと紐付いていない状態でのインシデント対応は、口頭確認と推測に頼ることになります。人数が増えるほど情報の欠落が大きくなる設計といえます。「誰がいつ何から作ったか」をアーティファクト側のメタデータとして記録する仕組みを保管設計に組み込まないと、チームが拡大するほどトレーサビリティのコストが急増します。

何を成果物として保管し、何を都度ビルドするかの判断

保管すべきアーティファクトの3条件

アーティファクトとして保管すべきかどうかは、「再現コスト」「変動リスク」「参照頻度」の3軸で判断できます。再現コストとは、同じ成果物をゼロからビルドし直すのにかかる時間と手間です。Dockerイメージのフルビルドが10分以上かかる・外部の依存ライブラリバージョンが固定されていない・ビルド環境自体の再現に作業が必要、という場合は保管対象です。変動リスクの観点では、npmやPyPIのパッケージは週次で更新されるため、「同じコードから同じビルドが得られる」保証がありません。参照頻度は、ロールバック要件やマルチ環境展開の頻度から判断します。

都度ビルドで許容できるものの見極め

ビルド時間が2分以内でビルド環境が決定論的に固定されており、かつ外部依存がロックされている場合は、都度ビルドで問題ありません。テスト用の一時的なコンテナや機能確認イメージは、保管コストに見合わないことが多いです。ただしこの判断は「現在の規模」ではなく「6か月後の規模」で行う必要があります。ブランチが20本を超えた段階で一時イメージの管理コストが急増し、「保管しなかった判断」を後悔するチームは少なくありません。

設定ファイル・マイグレーションスクリプトという中間層

コンテナイメージやバイナリの議論に隠れがちな「中間層」の成果物があります。DBマイグレーションスクリプト、Terraform planの出力、設定ファイルのレンダリング済み結果などです。「どの状態のインフラに対してどのスクリプトを適用したか」の対応関係が記録されていないと、復旧時に誤った前提で操作するリスクが生まれます。これらをアプリケーションのアーティファクトと同様にバージョン・タイムスタンプ・コミットハッシュ付きで管理するかどうかは、設計段階での重要な線引きです。

バージョン付けと不変性(イミュータブル)をどう設計するか

latestタグが設計上抱える本質的な問題

コンテナレジストリで最も頻繁に見られるアンチパターンが、latestタグへの依存です。複数の環境が同じlatestタグを参照している状態で更新が走ると、次のdocker pullで全環境が別のイメージを取得します。「デプロイした覚えがないのに動作が変わった」というインシデントの多くは、latestタグ参照が原因です。設計上の対処は、本番・ステージング環境のデプロイ時には必ずイミュータブルなタグ（ビルドID・コミットハッシュ等）を使用し、latestはCIパイプライン内の一時参照専用に限定するルールを設計段階で決めることです。

セマンティックバージョンとビルドハッシュの組み合わせ

バージョン付けの設計では、セマンティックバージョン（v1.2.3）とビルドハッシュ（短縮コミットSHA等）を組み合わせる構成が安定します。セマンティックバージョンだけでは「v1.2.3のどのビルドか」が複数存在しうるという問題があり、ハッシュだけでは人間がバージョン系列を把握しにくい。v1.2.3-a3f8c21という形式は、トレーサビリティと可読性を両立させます。タグ付けのルールはCIが自動生成するよう設計しないと、担当者の手作業に依存して抜けが生まれます。

イミュータブルとは「上書き禁止の設計」である

イミュータブルなアーティファクト管理とは、同一タグ・バージョンへの上書きを設計レベルで禁止することを意味します。ECRやArtifactory等の主要なレジストリにはイミュータブルタグの設定が存在するため、運用ルールではなく設定値として強制できます。これを適用しないと、CIが同じバージョン番号を再利用した場合に過去のアーティファクトが静かに置き換わります。ロールバック先として指定したバージョンが実は別ビルドだったという事態は、ストレージ節約を理由にイミュータブル設定をオフにしているチームで発生します。オフにする場合はそのトレードオフを設計ドキュメントに残すことが最低限必要です。

比較表: 自前レジストリ/マネージド/オブジェクトストレージの比較

コンテナイメージとバイナリアーティファクトの保管先を選定する際、自前でレジストリを構築するか、クラウドのマネージドサービスを使うか、汎用のオブジェクトストレージで代替するか、という3択に収束することが多いです。それぞれに向いている条件と設計上の落とし穴を整理します。

方式	向いている条件	設計上の落とし穴	代表的な選定基準
自前レジストリ（Harbor等）	インターネット非接続環境・クラウド送出規制がある	HA構成・証明書管理・ガベージコレクション運用が全て自前の設計範囲に入る	閉域ネットワーク・特定のコンプライアンス要件がある場合
マネージドレジストリ（ECR・GCR・ACR等）	クラウドネイティブ・IAM統合が容易	マルチクラウドやオンプレ混在時に認証設計とイメージプロモーションが複雑になる	クラウド単一環境・CI/CDとの統合を優先する場合
汎用オブジェクトストレージ（S3等）	バイナリ・tarball・設定ファイルなどコンテナ以外のアーティファクト	バージョン管理・アクセス制御・検索性をアプリ層で別途実装する必要がある	Terraform状態ファイル・バイナリリリース・マイグレーションスクリプトの保管

自前レジストリを選ぶべき条件

自前レジストリが合理的な選択肢になるのは、閉域環境・クラウドサービスへのデータ送出が規制されているコンプライアンス要件がある場合に限られます。ストレージバックエンド・TLS証明書の管理・高可用性のための複数インスタンス構成・ガベージコレクションの定期実行まで全て自前の設計範囲に入ることを前提とする必要があります。「とりあえず1台のVMにHarborを立てる」という構成は、ストレージ使用量が数百GBを超えた段階でパフォーマンスと信頼性の問題が顕在化します。

マネージドサービスで十分な条件と注意点

クラウド環境のCI/CDパイプラインから直接push/pullする用途であれば、マネージドレジストリが設計の複雑さを大幅に下げます。IAMによるアクセス制御・レプリケーション・ライフサイクルポリシーによる自動削除がマネージドで提供されるため、運用設計の範囲が限定されます。注意点は、マルチクラウドやオンプレ混在のハイブリッド構成です。認証トークンの有効期限・イメージのプロモーションフロー（dev→stg→prod間の移動をどの単位で管理するか）を設計段階で決めておかないと、環境間でのイメージ管理が煩雑になります。

保持世代とクリーンアップをどこで線引きするか

積み上がるアーティファクトの現実的な規模

アーティファクト保管設計で最も後回しにされるのがクリーンアップポリシーです。週5回のデプロイが走る環境では、ライフサイクルポリシーなしで運用を続けると1年間で250回分以上のイメージが蓄積します。コンテナイメージ1枚の平均が500MBであれば、それだけで125GB以上になります。ストレージコスト自体よりも「目的のバージョンを探すのにかかる時間」が先に問題になることが多く、一覧の表示が遅くなったり、どれが稼働中かわからなくなったりします。

世代管理ポリシーは「数」ではなく「目的」で設計する

保持世代の設計では、「何個残すか」ではなく「何のために残すか」で切ることが機能します。本番稼働中のバージョン・ロールバック候補としての直近N世代・長期監査要件があるリリースタグ付きバージョン、という3カテゴリで保持条件を分けるのが一般的です。「直近10世代」という単純なルールは、リリース間隔が長い場合に本番バージョンが削除される事故を招きます。タグパターン（releaseプレフィックスやセマンティックバージョン形式等）を条件にしたルールと、経過日数・世代数のルールを組み合わせて設計します。

クリーンアップ自動化の前提条件

クリーンアップの自動化は、「削除して問題ないことを確認できる仕組み」を先に設計してから動かす順序が重要です。アーティファクトと実環境の参照関係が記録されていないと、「まだどこかで使われているかもしれない」という理由で自動削除が止められ、肥大化が続きます。デプロイ時に「環境名＋アーティファクトID」を記録するメタデータストア（オブジェクトストレージ上のJSONやマネージドのKVS等）を設計に組み込み、現在参照中のアーティファクトをクリーンアップ処理が除外できる構成にすることが、自動化の前提条件です。

何でも残して肥大化する境界の見極め

「削除できない」アーティファクトが生まれる構造

アーティファクトが削除できない状態になる原因の多くは、「どの環境がどのバージョンを使っているか」の対応表が存在しないことです。環境数が30を超えるような規模では、全環境のデプロイ状態を手動で把握することは現実的でなく、削除の安全性を確認できなければ古いアーティファクトを「念のため残す」判断が積み重なります。これはストレージが安価だからという理由では正当化できない設計上の問題です。参照関係のトレーサビリティなしに保管量を増やすほど、将来の削除コストと調査コストが膨らみます。

ストレージコストより先に来る「探せないコスト」

保管量が増えることで最初に顕在化するのは、ストレージ費用ではなく認知負荷と検索コストです。「3か月前のあのバージョン」を探すためにビルドログを遡って30分かかるという状況は、チームの実装作業から継続的に時間を奪います。特定のアーティファクトをピンポイントで取り出せる命名・タグ・メタデータの設計が保管設計の核心であり、「場所に置いてあれば十分」という発想は規模が大きくなるほど破綻します。

肥大化を防ぐ3つの判断基準

「何でも残す」状態から脱するための判断基準は、(1)本番環境が現在参照しているバージョン、(2)ロールバック計画に含まれる直近N世代、(3)監査・コンプライアンス要件があるリリースタグ付きバージョン、の3つに絞り込むことです。それ以外は削除可能と設計段階で定義し、クリーンアップポリシーに組み込みます。「もしかしたら必要になるかもしれない」という理由で残しているアーティファクトは、再現可能なビルドパイプラインが整っていれば再生成できるため、保管の優先度を下げる判断ができます。

アーティファクト保管設計チェックリスト

設計段階で確認すべき判断項目を以下にまとめます。プロジェクト開始時と、チーム人数・環境数が大きく変わったタイミングで見直してください。

• 保管対象のアーティファクトを定義しているか（コンテナイメージ・バイナリ・設定ファイル・マイグレーションスクリプト等の区別）
• 都度ビルドで許容するものと保管するものの境界を明示しているか
• イミュータブルタグを設定でオンにしているか（同一タグへの上書きを禁止しているか）
• バージョン付けのルールがCIで自動生成されるか（手動作業に依存していないか）
• セマンティックバージョンとビルドハッシュを組み合わせたタグ形式を採用しているか
• latestタグの参照をCI内部に限定し、本番・ステージング環境では使用しないルールがあるか
• 保持世代のポリシーを「世代数」ではなく「目的別カテゴリ」で設計しているか
• 本番稼働中のバージョンがクリーンアップ対象から自動的に除外される仕組みがあるか
• 環境名とアーティファクトIDの対応をメタデータとして記録・参照できるか
• クリーンアップの自動化が動作しているか（ライフサイクルポリシーの設定が有効になっているか）
• アーティファクトのビルド時メタデータ（コミットハッシュ・ビルド日時・ビルド環境情報）が付与されているか
• 保管先の方式（自前/マネージド/オブジェクトストレージ）を環境要件から選定し直す必要がないか
• 環境数が30を超えた場合でも現行の設計が機能するか想定して確認したか