Harbor自前コンテナレジストリ本番構築｜認証統合・GC設定・障害時フォールバック設計

Harbor を本番投入する前に確認しておくこと

Harbor は CNCF の卒業プロジェクトであり、2026年時点では v2.11 系が最新安定版として多くのディストリビューションや IaC ツールで標準的に利用されています。Docker Hub の rate limit 問題や、セキュリティスキャン要件の厳格化を背景に、自前レジストリを本番に置く組織が増えています。

ただし「とりあえず docker compose up」で起動して終わりにすると、認証が素通し・ディスクが際限なく膨らむ・障害時に全ワークロードが止まるという三重苦を抱えることになります。本記事では、本番で実際に問題になる認証統合・GC 設定・フォールバック設計の3点を軸に、構築から運用定着まで順を追って説明します。

前提環境と構成の全体像

以下の前提で説明します。OS は Ubuntu 24.04 LTS、コンテナランタイムは Docker Engine 27 系、Harbor のデプロイは公式の Helm chart（harbor/harbor）を Kubernetes クラスターに適用する形を想定します。オンプレミス Kubernetes（例：kubeadm + Calico）でも、マネージド Kubernetes でも手順の差はほとんどありません。

構成要素は次のとおりです。

• Core API サーバー（harbor-core）：Web UI とレジストリ API を提供
• Registry（distribution）：実際のイメージ blob を格納
• Trivy アドオン：CVE スキャンを push 時に自動実行
• Redis / PostgreSQL：セッション・メタデータ管理
• JobService：GC・レプリケーション・スキャンをバックグラウンドで処理

ストレージバックエンドは S3 互換オブジェクトストレージ（MinIO や AWS S3）を使うと PVC のサイジング問題から解放されます。Helm values で persistence.imageChartStorage.type: s3 を指定し、バケット名・エンドポイント・認証情報を渡すだけで切り替えられます。

認証統合：LDAP と OIDC の選択と設定

Harbor の認証モードは「内部ユーザーDB」「LDAP/AD」「OIDC」の3種類です。本番では内部 DB のみに頼るのは推奨されません。退職者アカウントの無効化が手動になるためです。

LDAP/AD 統合の手順

管理コンソール（Web UI）の Administration → Configuration → Authentication から Auth Mode を「LDAP」に切り替えます。主な設定項目を確認します。

• LDAP URL：ldaps://ldap.example.internal:636（TLS を必須化する）
• LDAP Search DN / Password：読み取り専用のサービスアカウントを使う
• LDAP Base DN：ou=people,dc=example,dc=internal
• LDAP UID：uid（AD なら sAMAccountName）
• LDAP Group Base DN：Harbor のロール（管理者・開発者・ゲスト）を LDAP グループに対応付ける場合に設定

設定後、Test LDAP Server ボタンで接続を確認してから保存します。既存の内部ユーザーは LDAP 認証ユーザーとは別エンティティとして残るため、移行期間中は重複に注意が必要です。

OIDC 統合（Keycloak / Dex 等）

Auth Mode を「OIDC」に切り替えると、サービス間の SSO が実現しやすくなります。Keycloak を IdP として使う場合、Harbor 側の設定は次の4項目が最低限必要です。

• OIDC Provider Name：任意の表示名
• OIDC Endpoint：https://keycloak.example.internal/realms/myrealm
• OIDC Client ID / Secret：Keycloak の Client で作成したものを入力
• OIDC Scope：openid,profile,email,offline_access

CLI（docker login）でも OIDC 認証を使う場合は、Harbor の「CLI secret」機能でユーザーごとにトークンを発行し、それをパスワード代わりに使います。CI/CD パイプラインでは Robot Account（サービスアカウント相当）を使う方が管理しやすいです。Robot Account は特定プロジェクトへの push/pull 権限だけを絞り込んで発行でき、有効期限も設定できます。

Garbage Collection の設定と運用

Harbor はイメージの「削除」操作をしても、blob（実データ）はストレージから即座には消えません。参照カウントを外すだけで、実際の空き容量確保には GC 実行が必要です。これを知らずに放置すると、ストレージが際限なく増加します。

GC のスケジューリング

管理コンソールの Administration → Garbage Collection から設定します。GC には「停止なし GC（non-disruptive GC）」と通常の GC の2種類があります。

非停止 GC は Harbor v2.7 以降で利用可能になりました。通常の GC はレジストリの read-only モード移行が発生するため、実行中は push が一時的にブロックされます。本番環境では非停止 GC をスケジュール実行するのが現在の推奨です。

スケジュールの例として、深夜帯（例：毎日 03:00）に実行する設定が一般的です。GC の実行ログは Administration → Garbage Collection → Logs から確認できます。不要 blob の削除量・実行時間をログで継続的に監視し、ストレージ使用量の伸びが緩やかになっているかを確認します。

Tag Retention Policy との組み合わせ

GC はあくまで「参照されていない blob を消す」処理です。タグ付きのイメージは GC で消えません。ストレージ肥大の根本対策には、プロジェクトごとの Tag Retention Policy が必要です。

ポリシーは「直近 N 件のタグを保持」「正規表現に一致するタグを保持」など複数のルールを組み合わせられます。想定例として、main ブランチの最新 10 件と semver タグ（v*）は常に保持し、その他の PR タグは 30 日後に削除するようなルール設計が考えられます。Retention Policy でタグを削除した後に GC を実行することで、はじめて実際のディスク容量が解放されます。この2ステップの関係を運用手順書に明記しておくと、担当者が変わったときのトラブルを防げます。

障害時フォールバック設計

自前レジストリが単一障害点になると、デプロイパイプライン全体が止まります。本番では最低限3つの対策を講じます。

Harbor 自体の高可用性

Helm chart では portal.replicas・core.replicas・registry.replicas をそれぞれ 2 以上に設定することで主要コンポーネントを冗長化できます。JobService は Stateful な処理のため replicas=1 が現行の推奨です（v2.11 時点）。PostgreSQL と Redis は外部の HA 構成（例：Patroni + PgBouncer、Redis Sentinel）に切り出すと可用性が上がります。

イメージのプロキシキャッシュとミラーリング

Harbor の「Proxy Cache」機能を使うと、Docker Hub や ghcr.io などの外部レジストリのキャッシュとして Harbor を機能させられます。ノードや CI ランナーの pull リクエストを Harbor 経由にしておけば、上流レジストリが一時停止しても Harbor のキャッシュから取得を続けられます。設定は Administration → Registries で外部レジストリを登録し、プロジェクト作成時に「Proxy Cache」タイプを選択するだけです。

さらに多拠点・DR 構成では「Replication」機能でセカンダリ Harbor へイメージを非同期レプリケーションします。push イベントをトリガーにリアルタイム転送する設定と、スケジュール転送を組み合わせることで、RTO（目標復旧時間）を短縮できます。

Kubernetes の imagePullPolicy と fallback 設定

Kubernetes 側でも対策が必要です。imagePullPolicy: IfNotPresent にしておくと、ノード上にキャッシュが残っていれば Harbor が停止しても既存 Pod の再起動は問題なく行えます。新規スケジューリングが必要な場面では pull できないため、コアワークロードのイメージを事前に全ノードへプル＆キャッシュしておく DaemonSet ベースのウォームアップ手法が有効です。

containerd の設定（/etc/containerd/config.toml）では [plugins."io.containerd.grpc.v1.cri".registry.mirrors] セクションに Harbor を primary、Docker Hub を fallback として並べることができます。Harbor が応答しない場合に自動的に上流に fallback するため、開発環境では利便性が高い一方、本番では意図しないバージョンの pull が発生するリスクもあるため用途に応じて判断します。

2026年現行環境での注意点

Harbor v2.10 以降、OCI Distribution Spec v1.1 への対応が進んでおり、application/vnd.oci.image.index.v1+json の multi-platform manifest を扱う際の互換性が改善されました。Buildkit や ko など OCI ネイティブなビルドツールを使っている場合は、Harbor 側のバージョンも v2.10 以上を使うことで問題が少なくなります。

Trivy の脆弱性 DB 更新については、Harbor 内部で定期的に自動更新が走りますが、エアギャップ環境では DB をオフラインで持ち込む手順が必要です。trivy-adapter の設定で offline モードとカスタム DB パスを指定できます。

また、2026年現在 Docker Hub は Authenticated Pull でも IP 単位のレート制限が継続しています。CI パイプラインの並列度が高い環境では Proxy Cache の設定は実用上ほぼ必須の対策と言えます。

Helm chart の values ファイルは GitOps リポジトリで管理し、existingSecret 参照で Secret を直接 chart に埋め込まない運用が定着しています。Sealed Secrets や External Secrets Operator と組み合わせて、パスワード・証明書を安全に扱う設計を最初から組み込んでおくと、後の監査対応が楽になります。