> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/harbor-registry.md).
# Harbor レジストリ
## Harbor レジストリガイド
> ミニプレム（MiniPrem）デプロイメント向けのコンテナイメージレジストリアクセス
{% hint style="info" %}
本ページの内容はデジタルヒューマン株式会社の正式サポート対象外です。参考情報としてご利用ください。
{% endhint %}
### 目次
* [概要](#overview)
* [アクセス権の取得](#getting-access)
* [ネットワーク要件](#network-requirements)
* [Harbor 接続のテスト](#testing-your-harbor-connection)
* [トラブルシューティング](#troubleshooting)
* [サポート](#support)
* [ライセンス](#license)
### 概要
MiniPrem およびデジタルヒューマンのレンダラー（開発コード：Renny）向けのコンテナイメージは、プライベート Harbor レジストリ `cr.uneeq.io` でホストされています。Harbor レジストリは、セキュアでエンタープライズグレードのコンテナイメージリポジトリを提供し、パブリックな Docker Hub レジストリと比較して、コスト最適化、セキュリティ強化、きめ細かなアクセス制御を実現します。
#### なぜ Harbor レジストリなのか
**コスト最適化**
* プライベートレジストリホスティングによる帯域コストの削減
* 効率的なイメージレイヤーキャッシングとストレージ
* Harbor のレート制限やプル料金なし
**セキュリティ強化**
* 認証情報の一元管理
* すべてのイメージプル操作の監査ログ
* イメージスキャンと脆弱性検出
* きめ細かなロールベースアクセス制御（RBAC）
**運用制御**
* 顧客ごとのきめ細かなアクセス制御
* すべてのレジストリ操作の監査証跡
* イメージアクセスに関する問題への専用サポート
* 一貫したイメージのバージョニングとタグ付け
#### Docker Hub からの移行
これまで MiniPrem や Renny のイメージを Docker Hub からプルしていた場合、以下の対応が必要です。
1. [サポート窓口](https://support.digitalhumans.jp/)から Harbor レジストリの認証情報を申請してください
2. イメージ参照を `cr.uneeq.io` を使用する形式に更新してください
3. 新しいレジストリで認証できるよう Docker / Kubernetes を構成してください
### アクセス権の取得
#### ロボットアカウントの考え方
自動化されたコンテナイメージプルを管理するために「ロボットアカウント」（サービスアカウント）を使用します。個人ユーザーアカウントとは異なり、ロボットアカウントは Docker、Kubernetes、CI/CD パイプラインといったデプロイメントシステムによるプログラム的な利用を目的として設計されています。
**ロボットアカウントの形式**:
```
Username: robot$customer-name
Password: [secure token provided by UneeQ]
```
#### 認証情報のリクエスト
Harbor レジストリの認証情報を取得するには、以下の手順を行ってください。
1. **サポート窓口への連絡**:
* サポートサイト:
* 顧客名およびデプロイメント環境を明記してください
* Harbor アクセス用のロボットアカウントを依頼してください
2. **受領する情報**:
* ロボットアカウントのユーザー名（形式: `robot$customer-name`）
* セキュアなパスワード／トークン
* レジストリ URL: `https://cr.uneeq.io`
* サポート対象のイメージリポジトリ（例: `uneeq/renny-renderer`、`uneeq/renny-encoder`）
#### 認証情報を安全に保管する
{% hint style="info" %}
**🔐 セキュリティのベストプラクティス:** Harbor の認証情報をバージョン管理にコミットしないでください。デプロイメント環境に適したセキュアな認証情報管理システムを利用してください。
{% endhint %}
**推奨される認証情報の保管方法**:
* **Docker（ローカル開発）**:
```bash
# Docker automatically encrypts credentials in ~/.docker/config.json
docker login https://cr.uneeq.io
```
* **Kubernetes**:
```bash
# Use Kubernetes Secrets for image pull credentials
kubectl create secret docker-registry harbor-credentials \
--docker-server=cr.uneeq.io \
--docker-username='robot$customer-name' \
--docker-password='your-password' \
--docker-email='support@uneeq.com' \
-n your-namespace
```
* **CI/CD パイプライン**（GitHub Actions、GitLab CI など）:
* 認証情報は暗号化されたリポジトリシークレットとして保管してください
* CI/CD 構成からはシークレットを参照してください
* ワークフローファイルに認証情報をハードコードしないでください
### ネットワーク要件
#### ファイアウォール構成
Harbor レジストリからイメージをプルするには、レジストリのエンドポイントへのネットワーク接続性を確保する必要があります。
{% hint style="warning" %}
**🔥 エンタープライズファイアウォールに関する注意:** 厳格なファイアウォールルールを持つエンタープライズ環境や企業環境でデプロイする場合、ネットワーク管理者に Harbor レジストリをホワイトリストへ登録してもらうようにしてください。
{% endhint %}
**レジストリエンドポイントの詳細**:
* **ホスト名**: `cr.uneeq.io`
* **ポート**: 443（HTTPS のみ）
* **プロトコル**: HTTPS（TLS 1.2 以上）
* **DNS**: パブリック DNS による名前解決が必要
#### ホワイトリスト要件
ファイアウォールルールで、以下への送信接続を許可してください。
```
Domain: cr.uneeq.io
Port: 443/tcp
Protocol: TLS 1.2+
Direction: Outbound
Service: Container Image Pull
```
#### ネットワーク接続性のテスト
コンテナをデプロイする前に、ネットワークが Harbor レジストリへ到達できることを確認してください。
```bash
# Test DNS resolution
nslookup cr.uneeq.io
# Test HTTPS connectivity
curl -I https://cr.uneeq.io
```
### Harbor 接続のテスト
Harbor レジストリからプルするコンテナをデプロイする前に、以下のステップに沿って構成を検証してください。
#### 前提条件
* Docker がインストール済みかつ起動済みであること
* Harbor レジストリの認証情報（ロボットアカウントのユーザー名とパスワード）
* `cr.uneeq.io` のポート 443 へのネットワークアクセス
#### ステップ 1: DNS 解決のテスト
システムが Harbor レジストリのホスト名を解決できることを確認します。
```bash
nslookup cr.uneeq.io
```
**期待される出力**:
```
Server: 8.8.8.8
Address: 8.8.8.8#53
Non-authoritative answer:
Name: cr.uneeq.io
Address: 1.2.3.4
```
**トラブルシューティング**: 「no such host」エラーが表示される場合は、DNS 構成またはネットワーク接続性を確認してください。
#### ステップ 2: HTTPS 接続性のテスト
レジストリへの HTTPS 接続を確立できることを確認します。
```bash
curl -I https://cr.uneeq.io
```
**期待される出力**:
```
HTTP/1.1 301 Moved Permanently
Location: https://cr.uneeq.io/v2/
Server: nginx
```
**トラブルシューティング**: 接続タイムアウトや TLS エラーが発生する場合は、ファイアウォールルールを確認し、ポート 443 にアクセスできることを確認してください。
#### ステップ 3: Docker 認証のテスト
ロボットアカウントの認証情報を使用して、Harbor レジストリで認証します。
```bash
docker login https://cr.uneeq.io --username 'robot$your-customer-name'
# Enter password when prompted
```
**期待される出力**:
```
Password:
Login Succeeded
```
**トラブルシューティング**: 「authentication required」エラーが表示される場合は、ロボットアカウントの認証情報が正しいこと、およびアカウントが失効していないことを確認してください。
#### ステップ 4: イメージプルのテスト
Harbor レジストリからテストイメージをプルし、読み取りアクセスが正常に行えることを確認します。
```bash
docker pull cr.uneeq.io/uneeq/renny-renderer:latest
```
**期待される出力**:
```
latest: Pulling from uneeq/renny-renderer
e0a742c94bf5: Download complete
5e632e8c65ba: Download complete
[... more layers ...]
Digest: sha256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9
Status: Downloaded newer image for cr.uneeq.io/uneeq/renny-renderer:latest
```
**トラブルシューティング**: プルが失敗する場合、以下を確認してください。
* インターネット接続が安定していること
* 指定したイメージタグがレジストリに存在すること
* 認証情報にプル権限が付与されていること
#### ステップ 5: 認証情報の永続化を確認
Docker が認証情報を保存していることを確認します。
```bash
cat ~/.docker/config.json | grep -A 5 cr.uneeq.io
```
**期待される出力**:
```json
"cr.uneeq.io": {
"auth": "cm9ib3QkY3VzdG9tZXItbmFtZTpwYXNzd29yZA=="
}
```
**注記**: `auth` フィールドには Base64 エンコードされた認証情報が表示されます。これは正常な動作で、Docker は保存する認証情報にこの形式を使用します。
### トラブルシューティング
#### よくある問題と解決策
**"unauthorized: authentication required"**
**原因**: Docker のログインに失敗したか、認証情報が失効しています。
**解決策**:
1. Harbor レジストリで再度認証してください。
```bash
docker logout https://cr.uneeq.io
docker login https://cr.uneeq.io --username 'robot$your-customer-name'
```
2. ロボットアカウントの認証情報がまだ有効であることを確認してください。
* [サポート窓口](https://support.digitalhumans.jp/)に連絡してアカウント状態を確認してください
* トークンが失効している場合は新しい認証情報を依頼してください
3. Docker の認証情報キャッシュをクリアして再試行してください。
```bash
rm ~/.docker/config.json
docker login https://cr.uneeq.io
```
**"dial tcp: lookup cr.uneeq.io: no such host"**
**原因**: DNS 解決の失敗です。システムがレジストリのホスト名を解決できていません。
**解決策**:
1. DNS 構成を確認してください。
```bash
nslookup cr.uneeq.io
dig cr.uneeq.io
```
2. 別の DNS サーバーでテストしてください。
```bash
nslookup cr.uneeq.io 8.8.8.8 # Google DNS
nslookup cr.uneeq.io 1.1.1.1 # Cloudflare DNS
```
3. ファイアウォールが DNS（ポート 53）を許可しているか確認してください。
* 企業ファイアウォールの内側にある場合は、ネットワーク管理者に連絡してください
* DNS クエリがパブリックネームサーバーに到達できることを確認してください
4. Kubernetes クラスターでは、CoreDNS が動作していることを確認してください。
```bash
kubectl get pods -n kube-system | grep coredns
```
**"x509: certificate signed by unknown authority"**
**原因**: TLS 証明書の検証に失敗しています。通常は企業ファイアウォール／プロキシが HTTPS を傍受していることが原因です。
**解決策**:
1. 証明書が有効であることを確認してください。
```bash
openssl s_client -connect cr.uneeq.io:443 -showcerts
```
2. 組織でプロキシや証明書インスペクションを使用していないか確認してください。
* ネットワーク／セキュリティチームに連絡してください
* プロキシのホワイトリストに Harbor レジストリを追加する必要がある場合があります
3. 開発目的でのみ（本番環境では非推奨）:
```bash
docker login https://cr.uneeq.io --username 'robot$your-customer-name' --insecure-skip-verify
```
4. 企業プロキシの内側にある場合はカスタム CA 証明書を追加してください。
```bash
# Place your corporate CA certificate in /etc/docker/certs.d/cr.uneeq.io/ca.crt
sudo mkdir -p /etc/docker/certs.d/cr.uneeq.io
sudo cp /path/to/ca.crt /etc/docker/certs.d/cr.uneeq.io/ca.crt
```
**"timeout waiting for network" / "connection timed out"**
**原因**: ネットワーク接続性の問題です。ファイアウォールによるブロックや、レジストリが一時的に利用できないことが原因です。
**解決策**:
1. 一般的なネットワーク接続性をテストしてください。
```bash
ping cr.uneeq.io
traceroute cr.uneeq.io
```
2. ファイアウォールが送信 HTTPS（ポート 443）を許可していることを確認してください。
```bash
curl -v https://cr.uneeq.io
```
3. レジストリが利用可能か確認してください。
* Web ブラウザで にアクセスしてください
* Harbor のログインページが表示されるはずです
4. 企業ネットワークでは以下を確認してください。
* HTTP プロキシで認証が要求されないこと
* HTTPS トラフィックがブロックされていないこと
* ネットワーク管理者が `cr.uneeq.io` をホワイトリストに登録していること
5. タイムアウトを延長して再試行してください。
```bash
docker pull cr.uneeq.io/uneeq/renny-renderer:latest --timeout=60
```
**"Error response from daemon: manifest not found"**
**原因**: 指定したイメージタグがレジストリに存在しないか、読み取りアクセス権がありません。
**解決策**:
1. イメージタグが存在し、正しいことを確認してください。
```bash
# Check available tags (requires Harbor API access)
curl -H "Authorization: Bearer $(echo -n 'robot$customer-name:password' | base64)" \
https://cr.uneeq.io/api/v2.0/projects/uneeq/repositories/renny-renderer/artifacts
```
2. プル権限を保有していることを確認してください。
* [サポート窓口](https://support.digitalhumans.jp/)に連絡してロボットアカウントの権限を確認してください
* お使いのアカウントが対象のイメージリポジトリに対して認可されていることを確認してください
3. 動作確認済みのイメージタグを使用してください。
```bash
# Try a specific version instead of latest
docker pull cr.uneeq.io/uneeq/renny-renderer:v1.2.3
```
#### Kubernetes 固有の問題
**Harbor からプルする際に Pod が CrashLoopBackOff になる**
**診断**:
```bash
kubectl describe pod
kubectl logs --previous
```
**解決策**:
1. イメージプルシークレットが存在することを確認してください。
```bash
kubectl get secrets -n your-namespace | grep harbor
```
2. イメージプルシークレットを作成または更新してください。
```bash
kubectl delete secret harbor-credentials -n your-namespace
kubectl create secret docker-registry harbor-credentials \
--docker-server=cr.uneeq.io \
--docker-username='robot$customer-name' \
--docker-password='your-password' \
--docker-email='support@uneeq.com' \
-n your-namespace
```
3. Pod スペックがイメージプルシークレットを参照していることを確認してください。
```yaml
spec:
imagePullSecrets:
- name: harbor-credentials
containers:
- name: renny
image: cr.uneeq.io/uneeq/renny-renderer:latest
```
4. Pod からのネットワーク接続性を確認してください。
```bash
# Deploy test pod
kubectl run -it --rm debug --image=alpine --restart=Never -- \
wget -O- https://cr.uneeq.io
```
***
### サポート
Harbor レジストリのアクセスやコンテナイメージに関するご相談は、以下までお問い合わせください。
* **サポートサイト**:
* **Harbor API リファレンス**: [Harbor 公式ドキュメント](https://goharbor.io/docs/working-with-projects/working-with-images/)
***
### ライセンス
Copyright © 2025 UneeQ Limited. All rights reserved.
Harbor レジストリでホストされているすべてのコンテナイメージは UneeQ の専有物であり、お客様のデプロイメント契約条件に従います。