クイックスタート:Kubernetes上でHarborを起動する(5分)
専用のレジストリがない環境では、複数のステージングクラスタや本番クラスタにまたがるコンテナイメージの管理はすぐに煩雑化してしまいます。Harborは、OCI Distribution Registryに本番環境レベルのガバナンス機能を付加することでこの問題を解決します。公式Helmチャートを利用すれば、わずか5分程度で実稼働可能なインスタンスを立ち上げることができます。
まず、HarborのHelmリポジトリを追加し、専用のNamespaceを作成します:
helm repo add harbor https://helm.goharbor.io
helm repo update
kubectl create namespace harbor
次に、最小限のvalues-quickstart.yamlファイルを定義します。この構成では、TLS対応のIngressを有効化し、50GBの永続ストレージを割り当て、Trivyスキャナーを有効にします:
expose:
type: ingress
tls:
enabled: true
certSource: auto
secret:
secretName: harbor-tls
ingress:
hosts:
core: registry.internal.example.com
externalURL: https://registry.internal.example.com
persistence:
enabled: true
resourcePolicy: keep
persistentVolumeClaim:
registry:
size: 50Gi
trivy:
enabled: true
harborAdminPassword: "SecureAdminPass123!"
チャートをクラスタにデプロイします:
helm install harbor harbor/harbor -f values-quickstart.yaml -n harbor
すべてのコアPodがRunning状態になるまでロールアウトを監視します:
kubectl get pods -n harbor -w
準備が整ったら、ブラウザでhttps://registry.internal.example.comを開きます。ユーザー名adminと上記で設定したパスワードを使用してログインします。
アーキテクチャ解説:主要コンポーネントの詳細
Harborはモノリシックなコンテナプロキシではありません。API Gatewayの背後で動作する、分散型のマイクロサービス群として構成されています:
- Harbor Core:認証、RBAC認可、Webhook、OIDCトークンの発行を管理します。
- Registry & Controller:OCI Distribution仕様に基づいて構築されています。生のイメージレイヤblob、チャンクアップロード、およびOCIアーティファクトマニフェストを処理します。
- Jobservice:イメージのレプリケーション、スケジュールされたガベージコレクション、タグ保持ルールを実行する非同期ジョブキューです。
- Trivy Security Scanner:CVE脆弱性フィードをダウンロードし、プッシュごとにイメージレイヤを検査します。
- Database (PostgreSQL) & Cache (Redis):プロジェクト設定、監査ログ、ユーザー権限、アクティブなセッション状態を保存します。
自動脆弱性スキャンの設定
イメージがクラスタに到達する前に脆弱性を検知できれば、何時間ものインシデント対応の手間を省くことができます。開発チームは、多数の重大なCVEを含む古いベースディストリビューションに基づいたイメージをプッシュしてしまいがちです。Harborでは、REST APIを介して直接プッシュ時スキャン(scan-on-push)ポリシーを適用できます。
1回のAPIコールで、core-servicesというプロジェクトにポリシーを設定できます:
HARBOR_URL="https://registry.internal.example.com"
AUTH="admin:SecureAdminPass123!"
# プロジェクト「core-services」でプッシュ時にイメージを自動スキャンするように設定
curl -u "$AUTH" -X PUT "$HARBOR_URL/api/v2.0/projects/core-services" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"auto_scan": "true",
"prevent_vul": "true",
"severity": "high"
}
}'
prevent_vul: trueおよびseverity: highを設定すると、Harborは未解決のHigh(高)またはCritical(緊急)のCVE(CVSSスコア7.0以上)を含むイメージのプル要求を強制的にブロックします。kubeletが該当するイメージをプルしようとすると、HarborはHTTP 412(Precondition Failed)エラーを返し、脆弱性のあるコンテナが本番環境で実行されるのを阻止します。
高度な活用法:クロスレジストリレプリケーションとエンタープライズRBAC
1.5GBものイメージをリージョンをまたいでプルすると、Podのオートスケーリングが遅延し、高額なWAN外部送信料金(エグレス費用)が発生します。例えば、トラフィック急増時に米国のセントラルレジストリからEUのクラスタへイメージをプルすると、ノードごとに30〜60秒のコールドスタート遅延が加わります。Harborは、プライマリレジストリとリージョンレジストリ間でイメージをミラーリングする自動レプリケーションルールによってこの課題を解決します。
レプリケーションエンドポイントとルールのセットアップ
まず、セカンダリデータセンターをリモートレプリケーションターゲットとして登録します:
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/registries" \
-H "Content-Type: application/json" \
-d '{
"name": "edge-us-west",
"type": "harbor",
"url": "https://edge-registry.uswest.internal.example.com",
"credential": {
"type": "basic",
"access_key": "robot$sync-agent",
"access_secret": "SecretTokenValue456!"
}
}'
次に、イベント駆動型のレプリケーションポリシーを作成します。セントラルレジストリに新しいイメージタグがプッシュされるたびに、エッジインスタンスへの即時同期がトリガーされます:
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/replication/policies" \
-H "Content-Type: application/json" \
-d '{
"name": "replicate-core-to-edge",
"src_resource": { "filters": [{ "type": "name", "value": "core-services/**" }] },
"dest_registry": { "id": 1 },
"dest_namespace": "core-services",
"trigger": { "type": "event_based" },
"enabled": true
}'
OIDCとロボットアカウントによるきめ細かなRBAC
個人の認証情報やcluster-adminトークンを自動ビルドシステムと共有してはなりません。Harborには、Project Admin、Maintainer、Developer、Guest、Limited Guestという5段階の階層化されたRBACロールが用意されています。
GitHub ActionsやGitLab CIなどのCI/CDランナー用には、有効期限を90日に設定したスコープ付きロボットアカウントを発行します。権限のスコープは、指定したプロジェクト内でのプッシュおよびプル操作のみに制限します:
curl -u "$AUTH" -X POST "$HARBOR_URL/api/v2.0/robots" \
-H "Content-Type: application/json" \
-d '{
"name": "ci-builder",
"description": "リリースワークフロー用スコープ付きトークン",
"duration": 90,
"level": "project",
"permissions": [
{
"kind": "project",
"namespace": "core-services",
"access": [
{ "resource": "repository", "action": "push" },
{ "resource": "repository", "action": "pull" }
]
}
]
}'
生成されたトークンは、KubernetesのimagePullSecretまたはCIシークレット変数として挿入します。万が一侵害された場合でも、トークンは自動的に失効し、レジストリ設定の変更や他のプロジェクトへのアクセスは行えません。
本番運用のための実践的なプラクティス
高負荷なビルド処理下でもHarborの信頼性を維持するには、実践的な運用の習慣付けが不可欠です:
- タグ保持ルールの自動化:アクティブなCIパイプラインでは毎日数百ものビルドがプッシュされ、使い捨てのアーティファクトでディスクが圧迫されることがあります。機能ブランチ用には最新の10タグのみを保持し、リリース用のセマンティックバージョニングタグ(
v*.*.*など)は無期限に保持するリテンションポリシーを設定しましょう。 - オフピーク時のガベージコレクションをスケジュール設定:UI上でイメージを削除しても、マニフェストの参照が削除されるだけであり、レイヤblobはディスク上に残ります。開発者50名規模のチームであれば、週1回(例:日曜日 02:00 UTC)のガベージコレクションを実行することで、アクティブなデプロイ時間帯に影響を与えることなく、200GB〜400GBもの不要なストレージ領域を日常的に回収できます。
- S3互換ストレージによるバックエンド構成:レジストリのデータ量が2TBを超えると、通常のKubernetes PersistentVolumeでは拡張が難しくなります。Helm valuesの
persistence.imageChartStorageセクションを調整し、blobストレージをAWS S3、Cloudflare R2、またはMinIOへルーティングしましょう。 - Jobserviceキューのレイテンシ監視:Harborは標準でPrometheusメトリクスを出力します。
harbor_jobservice_task_queue_size > 25に対するアラートを設定してください。キューの滞留が継続している場合、通常はTrivyスキャンワーカーやレプリケーションジョブがボトルネックになっていることを示しており、水平スケーリングが必要です。

