# Руководство по использованию PearlHarbor registry
# 2026-03-11 12:45

Цель: документ описывает как собирать/тегировать/пушить образы в реестр PearlHarbor, как запускать тестовый набор пушей из репозитория, какие ошибки встречаются и как их устранять.

Файлы в репе, полезные для работы:
- [examples/push-sample/Dockerfile](examples/push-sample/Dockerfile) — минимальный Dockerfile для теста.
- [examples/push-sample/build_and_push.sh](examples/push-sample/build_and_push.sh) — простая утилита сборки и опционального пуша (DO_PUSH=true).
- [test_pearlharbor_push.sh](test_pearlharbor_push.sh) — расширенный тестовый скрипт для многократных пушей и опциональной очистки (CLEANUP=true).
- `secrets/pearlharbor_registry.txt` — локальный файл с настройками/паролем (не ложить в публичные места).

1) Быстрый старт (ручной, один образ)

1.1. Подготовка

- Убедитесь, что у вас есть `docker` и вы можете запускать `docker build` и `docker push`.
- Проверьте `secrets/pearlharbor_registry.txt` — в нём должно быть поле `connection_url` и `admin_pass`.

1.2. Собрать образ локально

```bash
docker build -t sless-sample:local -f examples/push-sample/Dockerfile examples/push-sample
```

1.3. Тег и push (пример)

```bash
registry=$(grep -E '^connection_url=' secrets/pearlharbor_registry.txt | cut -d'=' -f2- | sed -E 's~https?://~~; s~/$~~')
admin_pass=$(grep -E '^admin_pass=' secrets/pearlharbor_registry.txt | cut -d'=' -f2-)
echo "$admin_pass" | docker login "$registry" -u admin --password-stdin
docker tag sless-sample:local "$registry/pearlharbor/sless-sample:mytag"
docker push "$registry/pearlharbor/sless-sample:mytag"
```

2) Тестовый набор пушей (рекомендуется запускать без VPN)

- Скрипт: [test_pearlharbor_push.sh](test_pearlharbor_push.sh)
- Пример запуска (5 пушей, с очисткой тегов):

```bash
CLEANUP=true ./test_pearlharbor_push.sh
```

- Параметры (переменные окружения):
  - `NUM_PUSHES` — число пушей (по умолчанию 5)
  - `RETRIES_PER_PUSH` — попыток на пуш (по умолчанию 3)
  - `BACKOFF` — базовый множитель паузы между попытками
  - `PROJECT` — проект/неймспейс в Harbor (по умолчанию `pearlharbor`)
  - `CREATE_PROJECT=true` — создать проект автоматически (если у вас есть права)
  - `CLEANUP=true` — после тестов удалит созданные теги (по API)

3) Частые ошибки и как их исправлять

- Ошибка: "invalid repository name: sless-sample"
  - Причина: формат тега не содержит проект/неймспейс. В Harbor теги должны быть `registry/PROJECT/REPO:TAG`.
  - Решение: используйте `registry/pearlharbor/sless-sample:tag`.

- Ошибка: "project pearlharbor not found"
  - Причина: проект (namespace) ещё не создан в Harbor.
  - Решение: создайте проект через UI или API (пример ниже) или запустите `CREATE_PROJECT=true` в `test_pearlharbor_push.sh`.

- Ошибка: TLS handshake timeout / docker login failed
  - Причина: нестабильная сеть, прокси или VPN мешают TLS. На наших тестах VPN приводил к таймаутам.
  - Решение: временно отключите VPN, проверьте сетевую связность (`ping`, `curl https://.../v2/`), повторите попытку.

- Предупреждение: "Your password will be stored unencrypted in ~/.docker/config.json"
  - Причина: Docker по умолчанию хранит креды в открытом виде, если не настроен credential helper.
  - Решение: установить `docker-credential-helpers` или игнорировать на тестовой машине.

4) Harbor API — полезные команды

- Создать проект `pearlharbor`:

```bash
registry=pearlharbor.registryk8s.services.ngcloud.ru
admin_pass=$(grep -E '^admin_pass=' secrets/pearlharbor_registry.txt | cut -d'=' -f2-)
curl -u "admin:$admin_pass" -X POST "https://$registry/api/v2.0/projects" \
  -H 'Content-Type: application/json' \
  -d '{"project_name":"pearlharbor","metadata":{"public":"true"}}'
```

- Список проектов:

```bash
curl -u "admin:$admin_pass" "https://$registry/api/v2.0/projects"
```

- Удалить репозиторий (удаляет все артефакты/теги в репозитории):

```bash
curl -u "admin:$admin_pass" -X DELETE "https://$registry/api/v2.0/projects/pearlharbor/repositories/sless-sample"
```

5) Советы при отладке

- Всегда проверяйте `https://$REGISTRY/v2/` — корректный ответ `200` или `401` означает, что эндпоинт доступен.
- Если `docker login` выдаёт TLS ошибки — сначала проверьте `curl -v https://$REGISTRY/v2/` и трассу до хоста.
- Для массовых тестов используйте `test_pearlharbor_push.sh`, но запускайте его без VPN.
- Логинимся перед серией пушей и переиспользуем сессию.

6) Права и безопасность

- Для создания проекта и удаления репозиториев нужен административный доступ (`admin`), либо пользователь с соответствующими правами.
- Никогда не встраивайте пароли в публичные репозитории. Используйте `secrets/pearlharbor_registry.txt` только локально и добавьте его в `.gitignore`.

7) Что я изменил в репозитории (для истории)

- Добавлены: `examples/push-sample/Dockerfile`, `examples/push-sample/build_and_push.sh`, `test_pearlharbor_push.sh` (инструмент для тестирования пушей и очистки).
- Временные/фоновые скрипты использовались в ходе отладки и затем удалялись.

8) Быстрый чек-лист перед пушем

- 1) Отключить VPN (если есть)
- 2) Убедиться, что `docker` запущен и вы можете выполнять `docker build`.
- 3) Убедиться, что `secrets/pearlharbor_registry.txt` на месте и содержит `connection_url` + `admin_pass`.
- 4) Выполнить `docker login $REGISTRY`.
- 5) Тегировать как `REGISTRY/PROJECT/REPO:TAG` и `docker push`.

Если нужно, могу дополнить этот документ примерами вывода команд/raw-логами или добавить скрипты для CI/CD (pipeline), которые будут автоматически создавать проект при деплое и чистить тестовые теги.