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 の位置づけ

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

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

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 で失敗する形で出ます。

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 などで管理する

まとめ

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

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

関連記事

• Harbor プライベートコンテナレジストリ構築 – Kubernetes / Docker 向け内部レジストリを用意する
• Kubernetes MetalLB を Helm で導入する – Harbor で Chart を管理する考え方
• VMware TKG 向け Harbor 構築 – 閉域 Kubernetes の内部レジストリ
• Ubuntu 22.04 containerd の設定 – Kubernetes ノード向けに SystemdCgroup を有効化する
• Kubernetes クラスター構築 – kubeadm で controlPlaneEndpoint と CNI を整理する
• Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl を整理する

Related posts:

Kubernetes MetalLB を Helm で導入する – Harbor で Chart を管理する考え方 Ubuntu 22.04 Kubernetes 管理ツールのインストール – kubectl / Helm / calicoctl を整理する Helm は自作がおすすめ Helm は Apt や DNF のようにはならない Kubernetes MetalLB の導入 – LoadBalancer Service をオンプレ環境で成立させる Kubernetes Multus の導入 – Pod に複数 NIC を接続する CentOS 8 Docker インストール – Docker CE の導入 VMware TKG 向け Harbor 構築 – 閉域 Kubernetes の内部レジストリ Harbor プライベートコンテナレジストリ構築 – Kubernetes / Docker 向け内部レジストリを用意する Kubernetes Helmの導入 Kubernetes 1 つの Pod 内で複数の CentOS コンテナを実行する Kubernetes Nginx コンテナと Service NodePort