chore: staged files from prev session (gitignore, examples, harbor guide)

2026-03-11 14:36:32 +04:00
parent f033ae0de0
commit 869d728684
5 changed files with 157 additions and 2 deletions
@@ -0,0 +1,119 @@
+# Руководство по использованию 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), которые будут автоматически создавать проект при деплое и чистить тестовые теги.