Руководство по установке и настройке Jenkins (Blue Ocean) в Docker

Быстрая навигация

• Что такое Jenkins?
• Установка Jenkins
• Установка Docker
• Настройка Jenkins в Docker
• Создание пайплайна
• Пример Jenkinsfile
• Лучшие практики и безопасность
• Руководство по инцидентам и откату
• Чек-листы для ролей
• Краткое резюме

Что такое Jenkins?

Jenkins — это сервер автоматизации для CI/CD (continuous integration / continuous delivery). Кратко: задача Jenkins — автоматически запускать шаги сборки, тестирования и доставки при изменениях в репозитории. Пайплайн в Jenkins описывает последовательность этапов (stages) и шагов (steps), которые выполняются по триггеру.

Определения:

• CI — непрерывная интеграция: частая интеграция кода в общую ветку и автоматические тесты.
• CD — непрерывная доставка/развёртывание: автоматизация передачи артефактов в тестовую или продакшн-среду.

Важно: Jenkins расширяем через плагины; Blue Ocean — современный UI, упрощающий создание пайплайнов.

Установка Jenkins — обзор подходов

Варианты развёртывания Jenkins:

• Установка нативных пакетов (apt/yum) — подходит для контролируемых VM.
• Развёртывание в Docker — портативно и рекомендуется Jenkins-командой для стандартизации образа.
• Kubernetes — для масштабируемых сред с динамическими агентами.

В этом руководстве используем Docker + DinD (Docker-in-Docker) и образ jenkinsci/blueocean.

Установка Docker (пример для Ubuntu)

Docker упрощает запуск Jenkins в изолированном окружении. Перед установкой Docker убедитесь, что система обновлена.

Установите зависимости:

sudo apt install apt-transport-https ca-certificates curl software-properties-common

Добавьте GPG-ключ Docker:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Добавьте репозиторий Docker (пример для Ubuntu 18.04/Bionic; при другой версии укажите соответствующий кодовое имя):

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"

Обновите индексы пакетов и установите Docker:

apt update
sudo apt install docker-ce

Проверьте работу службы Docker:

systemctl status docker

Примечание: для других дистрибутивов используйте официальную инструкцию Docker.

Запуск Jenkins в Docker — подготовка сетей и томов

Docker-контейнеры по умолчанию эфемерны. Создадим сеть и тома для хранения данных Jenkins и TLS-сертификатов.

Создаём мостовую сеть для взаимодействия контейнеров:

docker network create jenkins

Создаём тома для сертификатов и данных Jenkins:

docker volume create jenkins-docker-certs
docker volume create jenkins-data

Почему тома? Данные в /var/jenkins_home должны сохраняться между перезапусками контейнера.

DinD: запуск Docker-in-Docker (контейнера docker:dind)

Jenkins часто запускает сборки внутри Docker-контейнеров. Для этого контейнер Jenkins должен иметь доступ к Docker-демону. Один из безопасных способов — запускать отдельный сервис docker:dind и подключать к нему Jenkins по сети.

Запустите DinD-сервис (пример):

docker container run --name jenkins-docker --rm --detach \
--privileged --network jenkins --network-alias docker \
--env DOCKER_TLS_CERTDIR=/certs \
--volume jenkins-docker-certs:/certs/client \
--volume jenkins-data:/var/jenkins_home \
--publish 2376:2376 docker:dind

Пояснения:

• –privileged — требуется для DinD (права повышенные).
• –network-alias docker и –publish 2376:2376 — открывают Docker API для контейнера Jenkins.
• DOCKER_TLS_CERTDIR и volume для certs — для TLS-подключения между Jenkins и DinD.

Важно: DinD с –privileged несёт риски безопасности. В продакшне рассмотрите альтернативы: привязка хоста Docker socket (внимательно к правам), или использование удалённого Docker API на отдельном управляемом узле.

Запуск Jenkins Blue Ocean

После подготовки запускаем контейнер с Blue Ocean интерфейсом:

docker container run --name jenkins-blueocean --rm --detach \
--network jenkins --env DOCKER_HOST=tcp://docker:2376 \
--env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 \
--volume jenkins-data:/var/jenkins_home \
--volume jenkins-docker-certs:/certs/client:ro \
--publish 8080:8080 --publish 50000:50000 jenkinsci/blueocean

Что делает команда:

• Подключает контейнер к сети jenkins.
• Указывает переменные DOCKER_HOST/DOCKER_CERT_PATH/DOCKER_TLS_VERIFY, чтобы Jenkins мог обращаться к DinD.
• Монтирует том с данными и сертификатами.
• Публикует порты: 8080 — веб-интерфейс Blue Ocean; 50000 — служебное соединение для агентов Jenkins.

После запуска откройте в браузере: http://:8080

На первом старте система просит initialAdminPassword. Получить его можно из тома Jenkins:

docker container exec -it jenkins-blueocean cat /var/jenkins_home/secrets/initialAdminPassword

Скопируйте пароль, завершите мастер настройки: создайте администратора и установите рекомендованные плагины (Install Suggested Plugins) или вручную подберите нужные.

Important: храните доступы и backup тома jenkins-data отдельно.

Создание и управление пайплайном

Blue Ocean предлагает интерфейс «Create A New Pipeline» для быстрого старта.

Выберите хранилище кода: GitHub, Bitbucket или Generic Git.

Рекомендуемая практика: используйте Generic Git и добавьте сервисного пользователя (service account) с SSH-ключом, к которому Jenkins будет иметь доступ. Jenkins генерирует публичный ключ — добавьте его в репозиторий с правами записи, если Jenkins должен обновлять Jenkinsfile.

Jenkins хранит конфигурацию пайплайнов в Jenkinsfile в корне репозитория. При редактировании через UI Jenkins сам коммитит изменения в Jenkinsfile.

Пример простого Jenkinsfile для Node.js

Ниже — пример декларативного Jenkinsfile, который устанавливает зависимости, собирает и тестирует приложение, и выполняет параллельные тесты.

pipeline {
  agent { docker { image 'node:14' } }
  environment {
    CI = 'true'
  }
  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }
    stage('Install') {
      steps {
        sh 'npm install'
      }
    }
    stage('Build') {
      steps {
        sh 'npm run build'
        archiveArtifacts artifacts: 'build/**', fingerprint: true
      }
    }
    stage('Test') {
      parallel {
        stage('Unit Tests') {
          steps { sh 'npm run test:unit' }
        }
        stage('Integration Tests') {
          steps { sh 'npm run test:int' }
        }
      }
    }
    stage('Deploy to staging') {
      when { branch 'master' }
      steps {
        echo 'Deploying to staging...'
        // добавьте команды деплоймента
      }
    }
  }
  post {
    success { echo 'Pipeline passed' }
    failure { mail to: 'dev-team@example.com', subject: 'Build failed', body: 'Check Jenkins' }
  }
}

Ключевые моменты:

• agent { docker { image ‘…’ } } — запускает шаги внутри указанного Docker-образа.
• archiveArtifacts — сохраняет артефакты сборки в Jenkins.
• post — действия после завершения пайплайна (уведомления, отчёты).

Отладка сборки

• Нажмите на ошибочный stage, чтобы открыть консольный вывод (Console Output).
• Проверяйте переменные окружения и используемый образ агента.
• Логируйте артефакты и тестовые отчёты (JUnit/XML) для улучшенной аналитики.

Лучшие практики для Jenkins в Docker

• Храните Jenkinsfile в репозитории кода — версия пайплайна вместе с кодом.
• Избегайте запуска Jenkins с –privileged без строгой необходимости; для DinD оцените риски.
• Создайте отдельного сервисного пользователя в Git с ограниченными правами.
• Регулярно бэкапьте том jenkins-data и секреты.
• Управляйте плагинами: обновляйте, но тестируйте в стенде.
• Используйте агенты (distributed builds) для изоляции сборок и масштабирования.

Безопасность и жёсткая настройка

Рекомендации по безопасности:

• Включите HTTPS и используйте валидный TLS-сертификат для веб-интерфейса.
• Отключите доступ к Jenkins снаружи, если не требуется; используйте VPN или прокси.
• Минимизируйте набор плагинов — каждый плагин расширяет поверхность атаки.
• Отключите скриптовые сниппеты от пользователей без доверия (Script Security Plugin).
• Разграничивайте права доступа: ролям — минимум прав.
• Шифруйте секреты (Credentials bindings) и храните их в безопасном хранилище.

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

Руководство по инцидентам и откату

Kраткий план действий при отказе Jenkins:

1. Проверка статуса контейнера и ресурсов хоста:

docker ps
docker logs jenkins-blueocean --tail 200

2. Восстановление из бэкапа тома jenkins-data (если повреждён):

• Остановите контейнер jenkins-blueocean.
• Восстановите содержимое тома (scp/rsync из бэкапа на узел).
• Перезапустите контейнер.

3. Откат конфигурации плагина или Jenkins до предыдущей версии: восстановите том из бэкапа, где была рабочая версия.

4. Если DinD упал, проверьте наличие тома jenkins-docker-certs и заново запустите docker:dind.

Критерии приёмки после восстановления:

• Веб-интерфейс доступен на порту 8080.
• Агентские соединения принимаются на порту 50000.
• Минимум один успешный билд запускается и проходит стадии Checkout/Build/Test.

Чек-листы для ролей

DevOps (ответственный за развёртывание):

• Создать сеть и тома Docker.
• Настроить DinD или альтернативу с учётом безопасности.
• Настроить HTTPS и бэкапы тома.
• Настроить мониторинг и alerting (CPU, диск, память).

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

• Хранить Jenkinsfile в корне репозитория.
• Локально воспроизводить сборку с тем же Docker-образом.
• Писать юнит- и интеграционные тесты, отдавать JUnit-отчёты.

QA / тестировщик:

• Настроить отдельный этап тестирования в пайплайне.
• Включать артефакты и тестовые отчёты в каждый билд.
• Поддерживать тестовую среду для ручной проверки артефактов.

Альтернативные подходы и когда Jenkins подходит не лучшим образом

Альтернативы Jenkins:

• GitHub Actions — интегрируется напрямую с GitHub; удобен для публичных репозиториев и простых задач.
• GitLab CI — встроен в GitLab, удобен при использовании GitLab как платформы.
• CircleCI, Travis CI — облачные CI, меньше затрат на поддержку инфраструктуры.

Когда не выбирать Jenkins:

• Нужна минимальная настройка и вы используете исключительно GitHub — GitHub Actions может быть проще.
• Не хотите поддерживать собственную инфраструктуру CI — предпочтите облачные CI-поставщики.

Тестовые сценарии и критерии приёмки

Примеры тест-кейсов для пайплайна:

• TC1: Пайплайн успешно проходит на ветке feature с прохождением unit-tests.
• TC2: При падении unit-tests пайплайн завершает выполнение с ошибкой и отправляет уведомление.
• TC3: На ветке master пайплайн выполняет деплой в staging и артефакты доступны в staging-окружении.

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

• Jenkinsfile в репозитории, корректно выполняется на агенте.
• Логи читаемы и содержат шаги сборки и тестов.
• Артефакты архивируются и доступны через UI.

Модель зрелости пайплайна (mini-maturity model)

• Уровень 0 — вручную: нет автоматизации; билды локально.
• Уровень 1 — базовый CI: автоматическая сборка и юнит-тесты на каждом коммите.
• Уровень 2 — расширенный CI: параллельные тесты, сбор артефактов, статический анализ.
• Уровень 3 — CD: автоматический деплой в staging; ручной промоут в production.
• Уровень 4 — полностью автоматический CD: автоматический деплой в production с контролями и SLO.

Decision flowchart для выбора варианта развёртывания (Mermaid)

flowchart TD
  A[Нужна ли быстрая настройка?] -->|Да| B[Cloud CI 'GitHub Actions / CircleCI']
  A -->|Нет| C[Управляемая собственная инфраструктура]
  C --> D{Используете Kubernetes?}
  D -->|Да| E[Kubernetes + Jenkins/Kubernetes Agents]
  D -->|Нет| F[Docker + Jenkins Blue Ocean]
  E --> G[Масштабируемость, динамические агенты]
  F --> H[Простота, DinD или socket binding]

Частые ошибки и как их решать (Edge-case gallery)

• Проблема: Jenkins не подключается к DinD по 2376. Решение: проверьте network-alias и переменную DOCKER_HOST; проверьте, что DinD слушает tcp и сертификаты доступны.

• Проблема: сборка падает с ошибкой «permission denied» при использовани Docker inside agent. Решение: проверьте права пользователя внутри контейнера; избегайте запуска в –privileged, если можно; используйте правильного пользователя в образе.

• Проблема: плагины сломались после обновления. Решение: восстановите том из бэкапа перед обновлением; тестируйте обновления в тестовом окружении.

Краткое резюме

• Jenkins — мощный инструмент CI/CD; Blue Ocean упрощает создание пайплайнов.
• Для переносимости полезно запускать Jenkins в Docker; DinD позволяет собирать образы внутри Jenkins, но несёт риски.
• Храните Jenkinsfile в репозитории, делайте бэкапы тома jenkins-data и управляйте плагинами.
• Настройте безопасность: HTTPS, ограниченные права, шифрование учётных данных.

FAQ

Q: Можно ли подключить существующий GitHub-репозиторий?
A: Да — используйте GitHub или Generic Git; рекомендуется service user с SSH-ключом.

Q: Нужно ли запускать DinD в production?
A: DinD удобен для локальной разработки и тестов, но в production лучше рассматривать изолированные агенты или управляемые Docker-сервисы.

Q: Как бэкапить Jenkins? A: Резервный копирование тома jenkins-data (rsync/cron) + экспорт настроек и секретов.

1-line glossary:

• Jenkinsfile — декларативный или скриптовый файл в репозитории, описывающий пайплайн.