Kubernetes 上に Harbor を構築する – Helm で内部コンテナレジストリを運用する意味

Kubernetes クラスター上に Harbor を Helm で導入する流れを整理します。Harbor はコンテナレジストリですが、実体は Web UI、registry、database、jobservice、scanner などを含む複合アプリケーションです。

Docker Compose 版 Harbor をクラスタ外に置く構成と、Helm で Kubernetes 上に Harbor 自体を載せる構成では、考えるべきことが変わります。この記事では、Kubernetes 上に Harbor を構築する場合の values、TLS、Ingress、永続ボリューム、pull する側の信頼設定を整理します。

クラスタ内 Harbor は、Kubernetes が Harbor を動かし、その Kubernetes が Harbor からイメージを取得する構成です。便利ですが、初期構築と障害復旧では依存関係を必ず意識します。

クラスタ内 Harbor の位置づけ

• Harbor 自体を Kubernetes アプリケーションとして運用する
• Helm values で公開方式、TLS、永続化を管理する
• Ingress または LoadBalancer で Harbor を外部公開する
• Kubernetes ノードが Harbor から image pull できるようにする
• Harbor が落ちるとイメージ配布にも影響するため依存関係を理解する

Harbor を Kubernetes 上に置く場合、Kubernetes が Harbor を動かし、同じ Kubernetes が Harbor からイメージを取得する、という循環に近い構造になります。そのため、初期構築や障害復旧では依存関係を意識します。

前提条件

Helm で Harbor を入れる前に、少なくとも次の前提を確認します。

• 利用する Kubernetes クラスタが安定している
• Helm が利用できる
• Ingress Controller または LoadBalancer の公開方式が決まっている
• StorageClass と永続ボリュームの方針が決まっている
• Harbor 用 FQDN と DNS が決まっている
• TLS 証明書と CA 信頼の扱いが決まっている

Helm リポジトリを追加する

helm repo add harbor https://helm.goharbor.io
helm repo update
helm search repo harbor/harbor

Chart version と App version を確認し、利用する Kubernetes バージョン、Ingress Controller、StorageClass と合わせて判断します。

Namespace を作成する

kubectl create namespace harbor
kubectl get namespace harbor

values ファイルを用意する

実運用では、コマンドラインの --set だけで導入せず、values ファイルを作成して管理します。

cat <<'EOF' > harbor-values.yaml
expose:
  type: ingress
  tls:
    enabled: true
  ingress:
    hosts:
      core: harbor.example.com

externalURL: https://harbor.example.com

persistence:
  enabled: true

harborAdminPassword: "change-me"
EOF

ここでは最小例にしています。実際には Ingress class、TLS Secret、StorageClass、容量、replica、scanner、Notary などを環境に合わせて明示します。

TLS と Ingress を考える

Harbor は Docker / containerd から HTTPS レジストリとして参照されます。そのため、Ingress の TLS 証明書と、クライアント側が信頼する CA の整合性が重要です。

• Harbor の FQDN と証明書の SAN を一致させる
• Ingress Controller が TLS 終端するのか Harbor 側で終端するのか決める
• Docker / containerd / Kubernetes ノードに CA を配置する
• 証明書更新時の反映手順を決める

TLS の問題は、Harbor の Pod が正常でも docker login や Kubernetes の image pull で失敗する形で出ます。Pod 状態と利用者側の接続性は分けて確認します。

Helm でインストールする

helm install harbor harbor/harbor -n harbor -f harbor-values.yaml
helm list -n harbor
kubectl get pods -n harbor -o wide

Harbor は複数 Pod で構成されるため、全体が Running になるまで少し時間がかかります。

状態を確認する

kubectl get all -n harbor
kubectl get pvc -n harbor
kubectl get ingress -n harbor
helm status harbor -n harbor

PVC が Bound になっているか、Ingress が作成されているか、Harbor の外部 URL に到達できるかを確認します。

Docker からログインする

docker login harbor.example.com
docker pull nginx:latest
docker tag nginx:latest harbor.example.com/library/nginx:latest
docker push harbor.example.com/library/nginx:latest

ログインできない場合は、Harbor の認証情報、プロジェクト権限、TLS 証明書、名前解決、Ingress の到達性を分けて確認します。

Kubernetes から pull する

Kubernetes から private image を pull する場合は、imagePullSecret を作成します。

kubectl create secret docker-registry harbor-regcred   --docker-server=harbor.example.com   --docker-username=<user>   --docker-password=<password>   --docker-email=admin@example.com

apiVersion: v1
kind: Pod
metadata:
  name: harbor-pull-test
spec:
  imagePullSecrets:
    - name: harbor-regcred
  containers:
    - name: nginx
      image: harbor.example.com/library/nginx:latest

Secret が正しくても、ノード側が Harbor の TLS 証明書を信頼していなければ pull は失敗します。認証と証明書信頼は別の問題として扱います。

更新と削除

Helm で導入した Harbor は、release と values を基準に更新します。

helm upgrade harbor harbor/harbor -n harbor -f harbor-values.yaml
helm rollback harbor <revision> -n harbor
helm uninstall harbor -n harbor

削除時も PVC や Secret が残る場合があります。データを消してよいかを確認してから扱います。

クラスタ内に置く場合の注意

• Harbor 障害時に新規 Pod の image pull が失敗する可能性がある
• Harbor 自身の再作成に必要なイメージ取得経路を考える
• PV とバックアップを必ず設計する
• Ingress / TLS / DNS を Harbor の外部 URL と一致させる
• values ファイルを Git などで管理する

特に内部レジストリを Harbor に寄せる場合、Harbor 自身の復旧手順は別枠で考えるべきです。クラスタ上で動いているから安心なのではなく、クラスタ上で動いているからこそ、ストレージ、証明書、DNS、Ingress、イメージ取得経路を一体で復旧できる必要があります。

まとめ

Kubernetes 上に Harbor を Helm で導入する場合、Harbor は単なるレジストリではなく Kubernetes アプリケーションとして運用する対象になります。Helm values、Ingress、TLS、PV、imagePullSecret、ノード側の CA 信頼をまとめて設計する必要があります。

クラスタ外の Harbor は依存関係が分かりやすく、クラスタ内 Harbor は Kubernetes 管理に寄せやすいという違いがあります。どちらが正しいというより、障害時に何を復旧すれば image pull が戻るのかを説明できる構成にしておくことが重要です。

関連する記事

• Photon OS で Harbor を構築した記録 – VMware 環境における内部レジストリ基盤
• VMware TKG と Harbor – インターネット非接続環境で内部レジストリを用意する意味
• Docker Harbor プライベートコンテナレジストリ構築
• Kubernetes MetalLB を Helm で導入する – Harbor で Chart を管理する考え方
• Ubuntu 26.04 で Kubernetes コントロールプレーンを構築する
• Kubernetes を前提とした仮想化アーキテクチャ – VM とコンテナをどう重ねるか

Related posts:

Kubernetes MetalLB を Helm で導入する – Harbor で Chart を管理する考え方 Ubuntu 22.04 WordPress – Apache / PHP / MariaDB で CMS を構築する Helm は自作がおすすめ – Chart を自分で管理する意味 Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl を整理する Helm は Apt や DNF のようにはならない Harbor プライベートコンテナレジストリ構築 – Kubernetes / Docker 向け内部レジストリを用意する Kubernetes MetalLB の導入 – LoadBalancer Service をオンプレ環境で成立させる Kubernetes 設定マニュアル – オンプレ環境でクラスタ運用を整理する Kubernetes Multus の導入 – Pod に複数 NIC を接続する kubernetes diskfullでpodが起動しなくなった Kubernetes Calico eBPF の設計メモ – kube-proxy 代替、DualStack、高可用性をどう見るか Kubernetes コントロールプレーンノードを追加できない場合