Photon OS で Harbor を構築した記録 – VMware 環境における内部レジストリ基盤

この記事は、Photon OS 上に Harbor を構築した当時の作業メモを、VMware 環境における内部コンテナレジストリ基盤として読み直すための記事です。古いコマンドをそのまま現在の正解として扱うのではなく、Harbor をどの層に置き、どの前提を満たしてから Kubernetes / TKG へ使わせるのかを整理します。

Harbor は単なる Docker Registry ではありません。Web UI、認証、プロジェクト管理、イメージ配布、TLS、レプリケーション、スキャン連携などを含むレジストリ基盤です。特に VMware、vSphere、TKG、閉域 Kubernetes のような環境では、内部レジストリの完成度がクラスタ構築と復旧作業の安定性に直結します。

この記事の位置づけ

元の記事は、Photon OS 4 上で Harbor を構築した時の作業メモでした。いま同じ記事を読む場合、細かいバージョンやコマンドをそのまま追うよりも、内部レジストリを構成するために何を先に決める必要があるのかを見る方が役に立ちます。

• Photon OS を Harbor の実行基盤として使う意味
• VMware 環境で内部レジストリを先に用意する理由
• DNS、TLS、プロキシ、ストレージ、バックアップの責任分界
• Kubernetes / TKG から Harbor を使う時の信頼設定
• Docker Compose 版 Harbor と Kubernetes 上の Harbor の違い

この記事は、現在の Harbor 公式手順を置き換えるものではありません。現行バージョンで実作業をする場合は、公式ドキュメントの前提条件、HTTPS 設定、harbor.yml、ライフサイクル管理を確認したうえで、ここでは設計上の読み替えに集中します。

Photon OS を Harbor の実行基盤として見る

Photon OS は、クラウドやエッジ向けの appliance OS として位置づけられている軽量 Linux です。VMware 環境、コンテナホスト、Kubernetes ノードといった文脈で使いやすいように作られており、Harbor を単体 VM 上で動かす土台として自然に選ばれていました。

ただし、Photon OS を使うこと自体が Harbor 運用の本質ではありません。本質は、Kubernetes ノードが信頼できる URL から必要なイメージを取得でき、障害時にもそのレジストリを復旧できることです。OS はそのための実行基盤の 1 つとして選びます。

内部レジストリが必要になる理由

Kubernetes や TKG では、多くのコンポーネントがコンテナイメージとして配布されます。外部レジストリへ常に安定して到達できる環境なら単純ですが、VMware 環境や閉域環境では、必要なイメージを内部に保持する設計が重要になります。

• インターネット非接続やプロキシ制約がある環境でもイメージを配布できる
• クラスタ構築に必要なイメージを事前に内部へ集約できる
• 外部レジストリ障害や rate limit の影響を受けにくくできる
• プロジェクト単位で権限、認証、ロボットアカウントを分けられる
• 検証済みイメージだけをクラスタ側へ使わせる運用にしやすい

Harbor は、単に docker push する置き場ではありません。クラスタがどのイメージをどこから取得するのか、誰が更新できるのか、どの CA を信頼するのか、復旧時にどのイメージを優先して戻すのかを決めるための基盤です。

構築前に決めること

Harbor のインストールは、インストーラを展開して harbor.yml を編集し、install.sh を実行する流れです。ただし、運用で重要なのはコマンドより前の設計です。

公式ドキュメントでも、Docker Compose で Docker host へ配置する方式と、Helm で Kubernetes クラスタへ配置する方式が分けられています。単体 VM 上の Harbor は小さく始めやすい一方、可用性は VM、ストレージ、バックアップ設計に依存します。

ネットワークと名前解決

Harbor は Kubernetes ノードや bootstrap 環境から名前で参照されるため、IP アドレスだけでなく FQDN を先に決めます。レジストリ URL が後から変わると、証明書、image reference、node 側の trust、CI/CD の設定をまとめて直すことになります。

sudo tee /etc/systemd/network/10-static-eth0.network > /dev/null <<'EOF'
[Match]
Name=eth0
[Network]
Address=192.0.2.10/24
Gateway=192.0.2.1
DNS=192.0.2.53
EOF
sudo systemctl restart systemd-networkd

上の例は Photon OS 側で固定 IP を設定する場合の形です。記事用の例示アドレスを使っているため、実環境では自分の管理ネットワーク、DNS、gateway に置き換えます。

TLS 証明書を先に固める

Harbor を運用基盤として使うなら、HTTPS を前提にします。公式ドキュメントでも、本番環境では HTTPS を使う方針が示されています。閉域環境であっても、HTTP のままにすると、後から Kubernetes ノードや Docker / containerd 側の設定を見直す範囲が広がります。

• Harbor の FQDN と証明書の SAN を一致させる
• Harbor host 側に server certificate と key を配置する
• 利用側の Docker / containerd / OS trust store へ CA を配布する
• 一時的な insecure 設定を恒久運用にしない
• 証明書更新時に Harbor と利用側の両方を確認する

openssl x509 -in harbor.example.internal.crt -noout -subject -issuer -dates
openssl x509 -in harbor.example.internal.crt -noout -text | grep -A1 "Subject Alternative Name"

証明書は Harbor だけで完結しません。Kubernetes ノード、bootstrap VM、CI/CD runner、管理端末が同じ CA を信頼しているかまで含めて確認します。

Harbor を導入する

Harbor の導入作業そのものは、インストーラを取得し、harbor.yml を作成して、prepare と install.sh を実行する流れです。ここでは現行手順を固定せず、作業の骨格だけを示します。実作業では必ず利用する Harbor バージョンの公式手順を確認してください。

tar xzf harbor-online-installer-vX.Y.Z.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml
sudo ./prepare
sudo ./install.sh
docker compose ps

harbor.yml では、hostname、HTTPS 証明書、admin password、database、data volume、proxy、external URL などを環境に合わせて決めます。ここに一時値や検証用の名前を残すと、後からクラスタ側の参照を直すことになります。

hostname: harbor.example.internal
https:
  port: 443
  certificate: /data/cert/harbor.example.internal.crt
  private_key: /data/cert/harbor.example.internal.key
harbor_admin_password: change-this-before-use
data_volume: /data

Docker Compose 版と Kubernetes 版を分けて考える

Harbor は Docker host 上に Docker Compose で構築することも、Kubernetes クラスタ上に Helm で構築することもできます。どちらが正しいかではなく、どの依存関係を許容するかで選びます。

TKG や閉域 Kubernetes の初期構築では、クラスタが存在する前からレジストリが必要になることがあります。この場合、単体 VM 上の Harbor は bootstrap 用の依存点として意味があります。一方で、クラスタ運用が進んだ後に可用性やスケールを重視するなら、Kubernetes 上の Harbor も選択肢になります。

利用側ノードで確認すること

Harbor が起動して Web UI に入れるだけでは、内部レジストリ基盤としては不十分です。利用側ノードから login、pull、push、証明書検証まで確認します。

curl --fail --silent --show-error https://harbor.example.internal/api/v2.0/systeminfo
docker login harbor.example.internal
docker pull registry.k8s.io/pause:3.10
docker tag registry.k8s.io/pause:3.10 harbor.example.internal/library/pause:3.10
docker push harbor.example.internal/library/pause:3.10
docker pull harbor.example.internal/library/pause:3.10

Kubernetes / containerd 側では、Docker で成功したから終わりではありません。containerd の registry 設定、CA 配布、imagePullSecret、Pod からの pull を別に確認します。

バックアップと復旧を設計する

Harbor が停止しても、すでに各ノードに存在するイメージだけで動いている Pod はすぐ止まらないかもしれません。しかし、ノード追加、Pod 再作成、クラスタ再構築、アップグレードでは Harbor が必要になります。内部レジストリは補助サーバーではなく、コンテナ基盤の依存点です。

• harbor.yml と証明書、秘密鍵、CA を保管する
• database と registry storage のバックアップ方式を決める
• 復旧後に同じ FQDN と証明書で戻せるようにする
• クラスタ構築に必要な重要イメージを一覧化する
• 外部から再取得できないイメージを優先して保護する
• robot account や project 権限を復元できるようにする

特に閉域環境では、バックアップから Harbor を戻せても、必要なイメージが欠けているとクラスタ復旧が止まります。Harbor の VM だけでなく、そこに保存されているイメージ集合も復旧対象として扱います。

いま読む場合の注意点

この記事の元になった作業は、Photon OS 4 と当時の Harbor 構成を前提にしていました。現在の Harbor、Docker Compose、Photon OS、Kubernetes / TKG では、推奨バージョン、前提パッケージ、設定項目、運用方法が変わっている可能性があります。

そのため、この記事は現在の正確なコマンド集としてではなく、内部レジストリをなぜ用意するのか、どの設計要素を先に決めるべきか、VMware 環境で Harbor がどの責務を持つのかを確認する記事として読むのが自然です。

• Harbor のインストール前提条件は利用するバージョンの公式ドキュメントで確認する
• Docker Compose の扱いは OS と Docker Engine のバージョンに合わせる
• Photon OS のサポート状態とパッケージ更新方法を確認する
• 検証用の HTTP / insecure registry 設定を本番運用へ持ち込まない
• TKG / Kubernetes 側の image registry 設計と一緒に判断する

参考情報

• Harbor Installation and Configuration
• Harbor Installation Prerequisites
• Configure HTTPS Access to Harbor
• Configure the Harbor YML File
• Project Photon OS

まとめ

Photon OS で Harbor を構築する意味は、単にレジストリを 1 台立てることではありません。VMware 環境や閉域 Kubernetes 環境で、必要なコンテナイメージを内部から安定して配布できる基盤を作ることです。

Harbor を運用するなら、ネットワーク、DNS、TLS、プロキシ、ストレージ、バックアップ、ノード側の信頼設定まで含めて考える必要があります。特に TKG や Kubernetes の構築では、内部レジストリの完成度がクラスタ構築と復旧の安定性に直結します。

関連記事

Docker と Podman はどっちを使うべき？用途別に使い分ける Docker / コンテナ基礎ガイド