Harbor на Ubuntu 22.04: установка и базовая настройка

Harbor — это открытый реестр Docker-образов для облачных нативных сред. Как реестр образов, Harbor используется для хранения и распространения контейнерных артефактов. Для защиты артефактов Harbor предоставляет политики безопасности, ролевой доступ, встроенный сканер уязвимостей и подпись образов, что позволяет гарантировать, что клиенты тянут образы из доверенного реестра.

Harbor — проект CNCF с уровнем graduate и подходящий для корпоративного использования: обеспечивает соответствие политикам и производительность, упрощая управляемое и защищённое управление артефактами в Kubernetes, Docker и других средах.

В этом руководстве показано развертывание Harbor с использованием Docker на Ubuntu 22.04: установка Docker CE, настройка Harbor с HTTPS, запуск установщика и базовые операции администрирования.

Кому пригодится это руководство

• Инженерам DevOps и администраторам, которым нужно развернуть локальный корпоративный реестр.
• Командам разработки, желающим централизовать хранение образов с политиками безопасности.
• Тем, кто хочет понять альтернативы (Helm для Kubernetes) и получить пошаговый SOP для развертывания.

Предварительные требования

Перед началом убедитесь, что у вас есть:

• Сервер с Ubuntu 22.04 (в примерах используется хост с именем harbor-server).
• Пользователь без root (с sudo-привилегиями) или доступ к root.
• Домен или локальное имя хоста, указывающее на IP сервера (например, registry.example.local).
• Действительный сертификат TLS для домена (Let’s Encrypt или самоподписанный — для тестовой среды).
• Прямой доступ в интернет для загрузки пакетов или заранее скачанный офлайн-инсталлер Harbor.

Важно: Harbor не рекомендуется запускать на 127.0.0.1/localhost — реестр должен быть доступен извне для клиентов.

Установить Docker CE на Ubuntu 22.04

Harbor можно развернуть двумя основными способами: через Docker Compose (инсталлер) или через Helm chart в Kubernetes. В этой главе мы устанавливаем Docker CE и плагин docker-compose, чтобы запустить офлайн-инсталлер Harbor.

1. Установите базовые зависимости:

sudo apt install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

Подтвердите установку, введя y при появлении запроса.

2. Добавьте официальный GPG-ключ и репозиторий Docker:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3. Обновите индекс пакетов и установите Docker CE и плагин compose:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

После установки проверьте состояние службы Docker:

sudo systemctl is-enabled docker
sudo systemctl status docker

Совет: если systemctl показывает, что служба не активна, выполните sudo systemctl enable –now docker и проверьте логи через sudo journalctl -u docker -b –no-pager.

Загрузка офлайн-инсталлера Harbor

Harbor выпускается как онлайн- и офлайн-инсталлер. Для изолированных сред чаще используют офлайн-пакет с контейнерными образами внутри tar-архива.

Перейдите в /tmp и скачайте последний офлайн-пакет (пример использует командную цепочку GitHub API для выбора последнего релиза):

cd /tmp
curl -s https://api.github.com/repos/goharbor/harbor/releases/latest | grep browser_download_url | cut -d '"' -f 4 | grep '\.tgz$' | wget -i -

Распакуйте скачанный архив (имя файла в примере — harbor-offline-installer-v2.6.1.tgz; адаптируйте под вашу версию):

tar -xzvf harbor-offline-installer-v2.6.1.tgz

Переместите каталог harbor в /opt:

sudo mv harbor /opt/
cd /opt/harbor

Важно: убедитесь, что на диске достаточно места для хранения образов и томов — для офлайн-пакета требуются десятки гигабайт в зависимости от версии.

Настройка конфигурации harbor.yml

В каталоге /opt/harbor есть шаблон harbor.yml.tmpl. Скопируйте его и отредактируйте harbor.yml, чтобы задать имя хоста, включить HTTPS и задать первоначальный пароль администратора.

cp harbor.yml.tmpl harbor.yml
sudo nano harbor.yml

Ниже — ключевые параметры, которые нужно настроить (пример):

# IP-адрес или hostname для доступа к UI и сервису реестра.
# НЕ используйте localhost или 127.0.0.1, так как Harbor должен быть доступен внешним клиентам.
hostname: registry.howtoforge.local

...

# HTTPS конфигурация
https:
  # порт HTTPS для Harbor, по умолчанию 443
  port: 443
  # путь к сертификату и приватному ключу для nginx
  certificate: /etc/letsencrypt/live/registry.howtoforge.local/fullchain.pem
  private_key: /etc/letsencrypt/live/registry.howtoforge.local/privkey.pem

...

# Начальный пароль для admin (работает только при первой установке)
harbor_admin_password: Harbor_Docker_Ubuntu

...

# Конфигурация базы данных
database:
  # Пароль для root-пользователя БД. Смените на сильный пароль перед использованием в продакшене.
  password: db_pass_harbor

Важно: сохраняйте приватный ключ и сертификат в защищённой директории; корректные права доступа — 600 для приватного ключа и 644 для сертификата.

Разъяснение основных опций:

• hostname — доменное имя, по которому клиенты будут обращаться к реестру.
• https.port и пути certificate/private_key — включают TLS; можно использовать самоподписанные сертификаты для тестов, но для продакшена рекомендуется Let’s Encrypt или корпоративный PKI.
• harbor_admin_password — используется только при первой установке; после запуска поменяйте пароль через веб-интерфейс.
• database.password — пароль для локальной базы данных (PostgreSQL); при использовании внешней БД укажите соответствующие параметры.

Запуск установщика Harbor

После редактирования harbor.yml запустите скрипт install.sh из каталога /opt/harbor:

cd /opt/harbor
sudo ./install.sh

Инсталлер проверит наличие Docker и docker-compose, распакует образы из офлайн-пакета и сгенерирует необходимые конфигурации и тома.

Когда установка завершится, проверьте сервисы через docker compose (в каталоге /opt/harbor):

ls
docker compose ps

Вы увидите список сервисов Harbor (nginx, core, jobservice, registry, chartmuseum и др.) с состоянием Up/Healthy.

Откройте браузер по адресу https://registry.howtoforge.local/ и вы должны увидеть страницу входа Harbor.

Войдите под admin и паролем, указанным в harbor.yml.

После входа вы увидите панель управления и проект по умолчанию library.

Базовая администрирование: пользователи и проекты

Создание пользователя

1. Перейдите в Administration → Users → NEW USER.
2. Введите логин, email и настройки пользователя (можно отключить галочку admin).
3. Нажмите OK.

В примере создаём пользователя alice для доступа через Docker CLI.

После создания пользователь появится в списке.

Добавление пользователя в проект

В Harbor пользователи работают в рамках проектов. По умолчанию существует проект library.

1. Перейдите в Projects → library → Members.
2. Нажмите кнопку USER (Add member).
3. Выберите пользователя alice и назначьте роль (например, Project Admin, Developer или Guest).
4. Подтвердите OK.

После этого alice появится в списке участников проекта.

Вход в Harbor через Docker CLI

На клиентской машине (или на сервере) выполните:

docker login https://registry.howtoforge.local/

Введите username и password (alice/ее пароль). Успешный вход покажет Login Succeeded.

Если используется самоподписанный сертификат, добавьте его в доверенные на клиенте или используйте –insecure-registry в Docker daemon (не рекомендуется для продакшена).

Публикация образов в Harbor

1. Скачайте тестовый образ nginx:alpine:

docker pull nginx:alpine

2. Просмотрите локальные образы:

docker images

3. Перетегируйте образ в формат //::

docker tag nginx:alpine registry.howtoforge.local/library/nginx:alpine

4. Отправьте образ в реестр:

docker push registry.howtoforge.local/library/nginx:alpine

5. В веб-интерфейсе Projects → library → Repositories вы увидите загруженный nginx.

Что делать, если что‑то идёт не так — распространённые проблемы и решения

• Службы не запускаются после install.sh — проверьте docker compose ps и логи: sudo docker compose logs core nginx registry jobservice. Частая причина — занятый порт 443 или некорректные права на сертификаты.
• Ошибка доступа к БД — проверьте параметры database.password и свободное место на диске; проверьте сетевые политики и SELinux/AppArmor.
• Login Succeeded, но push не проходит — проверьте, доверяет ли Docker TLS-сертификату реестра. Для самоподписанных сертификатов добавьте корневой сертификат в /etc/docker/certs.d/registry.howtoforge.local/ca.crt на клиенте.
• Проблемы с ресурсами — Harbor использует несколько контейнеров; убедитесь, что у вас хватает RAM и IOPS для баз данных и хранения образов.

Важно: для поиска корневой причины используйте логи контейнеров и системные логи. Команда для просмотра логов конкретного сервиса в каталоге /opt/harbor:

sudo docker compose logs -f 

Альтернативные способы развертывания

• Helm chart в Kubernetes — рекомендуемый подход для production в кластерных средах: обеспечивает масштабирование, управляемость и интеграцию с Ingress, хранилищем и секретами.
• Развёртывание в Docker Swarm — менее распространено, но возможно.
• Использование управляемых реестров (Artifact Registry, ECR, ACR) — если нет требования на локальный реестр.

Критерии выбора: если вам нужен централизованный реестр с политиками и сканером, и вы управляете Kubernetes, рассмотрите Helm; для простых установок на одном хосте — Docker Compose удобнее.

Безопасность и рекомендации по защите Harbor

• TLS: всегда использовать сертификаты от доверенного центра (Let’s Encrypt или CA компании). Для тестов можно применять самоподписанные сертификаты, но на проде — нет.
• Аутентификация: интеграция с LDAP/AD/OIDC позволяет упростить управление пользователями.
• Роли: используйте принцип наименьших привилегий — назначайте Project Developer или Guest, когда админ-права не нужны.
• Сканирование: включите встроенный сканер уязвимостей (Clair/Trivy) и настраивайте политики блокировки для уязвимых образов.
• Подпись образов (notary/clair) — гарантирует целостность и источник образа.
• Бэкапы: регулярно снимайте резервные копии базы данных и томов (особенно /data и /var/lib/pgdata, если используются тома Docker).
• Логи: централизуйте логи в ELK/Graylog и настраивайте оповещения о сбоях сервисов и ошибках аутентификации.

Роль‑ориентованные чек‑листы

Администратор (перед установкой):

• Убедиться в наличии домена и DNS-записи.
• Подготовить TLS-сертификат и приватный ключ.
• Проверить ресурсы хоста: диск, RAM, сеть.
• Установить Docker CE и проверить доступ к репозиториям.

Администратор (после установки):

• Сменить пароль admin через UI.
• Настроить LDAP/OIDC при необходимости.
• Включить сканирование уязвимостей и политики retention.
• Настроить backup-процедуру и мониторинг.

Разработчик:

• Получить учетную запись и доступ к проекту.
• Опробовать docker login/push/pull.
• Ознакомиться с политиками именования и тегирования образов.

Playbook: пошаговая инструкция для установки (SOP)

1. Подготовка сервера: обновить систему, настроить hostname, DNS.
2. Установить Docker CE по инструкции выше.
3. Скачать офлайн-инсталлер Harbor и распаковать его в /opt/harbor.
4. Скопировать harbor.yml.tmpl → harbor.yml и настроить ключи: hostname, https, admin пароль, database.пароль.
5. Разместить TLS-сертификаты по указанным путям и выставить права доступа.
6. Запустить sudo ./install.sh и дождаться завершения.
7. Проверить docker compose ps и доступ к UI.
8. Сменить пароль admin в UI и настроить проекты/пользователей.
9. Настроить бэкап БД и томов, включить сканирование уязвимостей.

Инцидентный план и откат (runbook)

Симптом: Harbor не отвечает после обновления.

1. Проверить состояние контейнеров: sudo docker compose ps.
2. Просмотреть логи критичных сервисов: sudo docker compose logs -f core nginx registry.
3. Если проблема в БД: остановить сервисы → восстановить резервную копию БД → запустить сервисы.
4. Если проблема в сертификатах: вернуть предыдущие файлы сертификатов, перезапустить nginx.
5. Если образцы или тома повреждены: восстановить /data/registry и /data/database из резервной копии.
6. Тестировать восстановление на тестовой машине минимум раз в квартал.

Критерии успешного восстановления:

• UI отвечает и принимает логины.
• Docker push/pull работают для тестового образа.
• Сканер уязвимостей запускается и отправляет отчёт.

Критерии приёмки

• Доступ по HTTPS к hostname и переход на страницу логина.
• Успешный вход под админом и смена пароля.
• Создание проекта и добавление пользователя.
• Успешный docker login, docker push и docker pull тестового образа.
• Наличие работающих сервисов docker compose ps без ошибок (Up/Healthy).

Тестовые случаи и приёмочные проверки

• TC-01: Установка Docker CE — docker –version возвращает версию.
• TC-02: Install.sh завершает работу без фатальной ошибки; docker compose ps показывает все сервисы.
• TC-03: Веб-интерфейс отвечает по HTTPS и загружается корректно.
• TC-04: docker login + docker push nginx:alpine успешны.
• TC-05: Сканер уязвимостей запускается и возвращает результат для загруженного образа.

Шаблон harbor.yml (минимальная конфигурация для примера)

hostname: registry.example.local
# expose nginx on 443
https:
  port: 443
  certificate: /etc/letsencrypt/live/registry.example.local/fullchain.pem
  private_key: /etc/letsencrypt/live/registry.example.local/privkey.pem
harbor_admin_password: ReplaceWithStrongAdminPassword
database:
  password: ReplaceWithStrongDBPassword

Совет: храните производственный harbor.yml в системе управления конфигурацией (Ansible/Vault/Secrets Manager) с ограниченным доступом.

Ментальные модели и эвристики

• Разделение обязанностей: Harbor — реестр; Kubernetes/CI — потребители. Не смешивайте функции реестра и CI/CD на одном узле без контроля ресурсов.
• Минимизация доверия: храните минимальный набор привилегий; используйте robot-аккаунты для автоматизированных систем.
• Слой абстракции: маршрутизируйте трафик через Ingress/Nginx/LoadBalancer для централизованного управления TLS.

Совместимость, миграция и обновления

• При обновлении Harbor читайте Release Notes: возможны изменения в базе данных и образах.
• Перед обновлением снимайте бэкап БД и томов.
• Для миграции с другого реестра: экспорт/импорт отдельных образов через docker pull/tag/push или использовать инструменты миграции registries-sync.

Скорость и ресурсы (факто-бокс)

• Порт по умолчанию HTTPS: 443.
• Минимальные ресурсы для простого развертывания: 2 CPU, 4 GB RAM (для тестов). Для продакшена рекомендуют ≥4 CPU и ≥8–16 GB RAM в зависимости от нагрузки.

Краткий глоссарий

• Registry: сервис для хранения контейнерных образов.
• Project: логическая область в Harbor для группировки репозиториев.
• Robot account: учётная запись для автоматизированных систем с ограниченными правами.
• Scan: проверка образа на уязвимости.

Локальные особенности и рекомендации для RU‑окружения

• Если вы используете внутренний корпоративный CA, добавьте CA в доверенные хранилища ОС и Docker на всех клиентах.
• При интеграции с AD используйте корректный DN и тестируйте соединение с учетной записью сервисного пользователя.

Короткий чеклист после установки

• Сменить пароль admin.
• Настроить бэкап БД и томов.
• Включить сканирование уязвимостей.
• Настроить уведомления и мониторинг.
• Документировать политики проектов и правила именования.

Заключение

Вы успешно установили Harbor на Ubuntu 22.04 с использованием Docker и офлайн-инсталлятора. Вы настроили TLS, создали пользователей и проект, выполнили docker login и загрузили образ. Дальше рекомендуем интегрировать Harbor в ваш CI/CD, включить регулярное сканирование уязвимостей и настроить резервное копирование.

Важно: тестируйте процесс восстановления и обновления в тестовом окружении прежде, чем применять изменения в продуктиве.

Короткое напоминание: Harbor удобен для обеспечения контроля и безопасности контейнерных образов — используйте ролевую модель и политики для снижения рисков.

Сводка действий на ближайшие шаги: завершить интеграцию с LDAP/AD (если требуется), настроить мониторинг и автоматические бэкапы, обучить команду работе с проектами и robot-аккаунтами.