Привет, Хабр!


Это четвертая и заключительная часть серии статей "Учимся разворачивать микросервисы", и сегодня мы настроим Jenkins и создадим пайплайн для микросервисов нашего учебного проекта. Jenkins будет получать файл конфигурации из отдельного репозитория, собирать и тестировать проект в Docker-контейнере, а затем собирать Docker-образ приложения и пушить его в реестр. Последней операцией Jenkins будет обновлять кластер, взаимодействуя с Helm (более подробно о нем в прошлой части).


План серии статей:


  1. Создание сервисов на Spring Boot, работа с Docker


    Ключевые слова: Java 11, Spring Boot, Docker, image optimization


  2. Разработка Kubernetes конфигурации и деплой системы в Google Kubernetes Engine


    Ключевые слова: Kubernetes, GKE, resource management, autoscaling, secrets


  3. Создание чарта с помощью Helm 3 для более эффективного управления кластером


    Ключевые слова: Helm 3, chart deployment


  4. Настройка Jenkins и пайплайна для автоматической доставки кода в кластер


    Ключевые слова: Jenkins configuration, plugins, separate configs repository



Jenkins — это сервер непрерывной интеграции, написанный на Java. Он является чрезвычайно расширяемой системой из-за внушительной экосистемы разнообразных плагинов. Настройка пайплайна осуществляется в декларативном или императивном стиле на языке Groovy, а сам файл конфигурации (Jenkinsfile) располагается в системе контроля версий вместе с исходным кодом. Это удобно для небольших проектов, однако, часто более практично хранить конфигурации всех сервисов в отдельном репозитории.


Код проекта доступен на GitHub по ссылке.


Установка и настройка Jenkins


Установка


Существует несколько способов установить Jenkins:


  • Из war-архива
  • Напрямую из Docker-образа
  • Развернуть в Kubernetes

War-архив с программой можно запустить из командной строки или же в контейнере сервлетов (№ Apache Tomcat). Этот вариант мы не будем рассматривать, так как он не обеспечивает достаточной изолированности системы.


Устранить этот недостаток можно, установив Jenkins в Docker. Из коробки Jenkins поддерживает использование докера в пайплайнах, что позволяет дополнительно изолировать билды друг от друга. Запуск докера в докере — плохая идея (здесь можно почитать почему), поэтому необходимо установить дополнительный контейнер 'docker:dind', который будет запускать новые контейнеры параллельно контейнеру Jenkins'а.


Также возможно развернуть Jenkins в кластере Kubernetes. В этом случае и Jenkins, и дочерние контейнеры будет работать как отдельные поды. Любой билд будет полностью выполняться в собственном контейнере, что максимально изолирует выполнения друг от друга. Из недостатков этот способ имеет довольно специфичную конфигурацию. Из приятных бонусов Jenkins в Google Kubernetes Engine может быть развернут одним кликом.


Хоть третий способ и кажется наиболее продвинутым, мы выберем прямолинейный путь и развернем Jenkins в Docker напрямую. Это упростит настройку, а также избавит нас от нюансов работы со stateful приложениями в Kubernetes. Хорошая статья для любопытствующих про Jenkins в Kubernetes.


Так как проект учебный, то мы установим Jenkins на локальной машине. В реальной обстановке можно посмотреть в сторону, например, Google Compute Engine. В дополнение замечу, что изначально я пробовал использовать Jenkins на Raspberry Pi, но из-за разной архитектуры "малинки" и машин кластера они не могут использовать одни и те же Docker-образы. Это делает невозможным применение Raspberry Pi для подобных вещей.


Команды для установки
docker network create jenkins

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

docker container run   --name jenkins-docker   --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

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

После установки Jenkins открываем http://localhost:8080/ и следуем инструкциям. Настроить Jenkins можно через UI, либо программно. Последний подход иногда называют "инфраструктура как код" (IaC). Он подразумевает описание конфигурации сервера с помощью хуков — скриптов на Groovy. Оставим этот способ настройки за рамками данной статьи. Для интересующихся ссылка.


Плагины


Меню работы плагинов доступно из настроек (Manage Jenkins -> Manage Plugins). Многие полезные плагины уже установлены. Особо среди них выделю 'Blue Ocean', предоставляющий удобный интерфейс для работы с вашими пайплайнами.


Для нашего проекта нам понадобится установить два плагина: Remote File Plugin и Kubernetes CLI. Remote File Plugin позволяет хранить Jenkinsfile в отдельном репозитории, а Kubernetes CLI предоставит доступ к kubectl внутри нашего пайплайна.


Установка Helm


Так как наше приложение развернуто с помощью Helm-чарта, то для обновления кластера нам нужно установить еще и Helm. Плагина для Helm я не нашел, поэтому стоит установить его вручную. Для этого коннектимся к контейнеру (docker exec -it jenkins-blueocean bash), скачиваем бинарник по ссылке с официального сайта и помещаем его в /usr/bin. Далее надо зарегистрировать наш Helm-репозиторий:


helm repo add msvc-repo https://anshelen.github.io/microservices-deploy/
helm repo update

Глобальные переменные среды


Так как у нас два сервиса, то мы создадим два пайплайна. Некоторые данные у них будут совпадать, поэтому логично вынести их в одно место. Это можно сделать, задав глобальные переменные среды, которые будут установлены перед выполнением любого билда на сервере Jenkins. Отмечу, что не стоит с помощью этого механизма передавать пароли — для этого существуют секреты.


Установим следующие глобальные переменные среды (Manage Jenkins -> Configure System -> Global properties -> Environment Variables):


  • CLUSTER_URL — адрес мастер-ноды Kubernetes. Можно получить командой kubectl cluster-info
  • CLUSTER_NAMESPACE — неймспейс нашего кластера
  • HELM_PROJECT — имя инсталляции Helm
  • HELM_CHART — имя Helm-чарта. В нашем случае это 'msvc-repo/msvc-chart'

Секреты


В Jenkins для хранения конфиденциальной информации существуют секреты нескольких типов, например, связка логин-пароль, секретный текст, секретный файл и др. Установим следующие секреты через меню Credentials -> System -> Global credentials -> Add Credentials:


Имя секрета Тип Описание
github-creds username with password Логин/пароль от git-репозиториев
dockerhub-creds username with password Логин/пароль от реестра Docker-образов
kubernetes-creds secret text Токен сервисного аккаунта нашего кластера

В предыдущей части в файле NOTES.txt нашего чарта мы описали последовательность команд для получения токена сервисного аккаунта. Вывести эти команды для кластера можно, запросив статус Helm-инсталляции (helm status msvc-project).


Конфигурация пайплайна


Как уже было упомянуто ранее, пайплайны описываются на Groovy, и могут быть написаны в декларативном и императивном стилях. Мы будем придерживаться декларативного подхода.


В Jenkins процесс выполнения пайплайна (билд) поделен на ряд шагов (stage). Каждый шаг выполняется определенным агентом (agent).


Наши пайплайны будут состоять из следующих шагов:


  1. Build. Компиляция проекта
  2. Test. Выполнение тестов. В проекте у нас только модульные тесты, но с помощью Maven нетрудно сделать отдельный шаг и для интеграционных тестов
  3. Package. Сборка jar-архива
  4. Push Images. Создание Docker-образов и их загрузка в реестр образов. Мы будем пушить два образа — с тегом latest и конкретной версией
  5. Trigger Kubernetes. Команда Kubernetes обновить Docker-образ в подах кластера


Структура файла конфигурации


Файл конфигурации будет иметь следующую структуру:


pipeline {
  agent none
  options { ... }
  environment { ... }
  stages {
    stage("Prepare container") {
      agent {
        docker {
          image 'openjdk:11.0.5-slim'
          args '-v $HOME/.m2:/root/.m2'
        }
      }
      stages {
        stage('Build') { ... }
        stage('Test') { ... }
        stage('Package') { ... }
      }
    }

    stage('Push images') {
      agent any
      when { branch 'master' }
      steps { ... }
    }

    stage('Trigger kubernetes') {
      agent any
      when { branch 'master' }
      steps { ... }
    }
  }
}

Агенты в Jenkins подчиняются типичным правилам "наследования" — если в шаге не определен агент, то будет использован агент родительского шага. Тег pipeline может рассматриваться как корневой шаг для всех остальных. Корневой шаг мы используем для объявления переменных среды и опций, которые по тому же правилу наследования будут иметь силу для всех вложенных шагов. Поэтому для тега pipeline установлен агент 'none'. Использование этого агента подразумевает, что вложенные шаги обязаны переопределить этот агент для выполнения каких-либо полезных действий.


Шаги Build, Test и Package будут выполняться в отдельном Docker-контейнере для изоляции билдов друг от друга. Также использование Docker-образа избавляет нас от необходимости настраивать для наших сервисов Java 11 (Jenkins поставляется с Java 8). Для того чтобы выполнить эти шаги в едином контейнере, мы вложим их в шаг 'Prepare container' с агентом 'docker'. В параметре args мы привяжем директорию .m2 в создаваемом контейнере к одноименной директории в контейнере Jenkins'а. В папке .m2 содержатся зависимости системы сборки Maven, которые будет переиспользоваться между билдами, что здорово сократит время выполнения.


Агент в шагах Push Images и Trigger Kubernetes равен 'any'. Это значит, что шаг может быть выполнен на любом доступном агенте. В простейшем случае это означает выполнение в контейнере Jenkins'а. Также эти шаги будут выполнены только для коммитов в мастер-ветку (when { branch 'master' }).


Далее мы более пристально посмотрим на каждый из шагов, а также на блоки options и environment.


Опции


options {
  skipStagesAfterUnstable()
  skipDefaultCheckout()
}

Блок опций может быть использован для настройки выполнения пайплайна или же отдельного шага. Мы используем следующие опции:


  • skipStagesAfterUnstable заставит Jenkins сразу прервать билд, eсли тесты были провалены. Поведение по умолчанию предусматривает установку статуса билда в UNSTABLE и продолжение выполнения. Это позволяет в сложных случаях более гибко обрабатывать подобные ситуации.


  • skipDefaultCheckout отключает автоматический чекаут репозитория проекта. Дефолтно Jenkins делает force чекаут репозитория для каждого шага с собственным агентом (в нашем случае Prepare Checkout, Push images и Trigger Kubernetes). То есть по сути затирает все изменения. Это может быть полезно при использовании пайплайна с несколькими различными образами. Однако нам нажно получить исходники с репозитория только единожды — на шаге Build. Применив опцию skipDefaultCheckout, мы получаем возможность произвести чекаут вручную. Также стоит заметить, что Jenkins будет автоматически переносить артефакты между шагами. Так, например, скомпилированные исходники из шага Build будут полностью доступны в шаге Test.



Переменные среды


environment {
  IMAGE_BASE = 'anshelen/microservices-backend'
  IMAGE_TAG = "v$BUILD_NUMBER"
  IMAGE_NAME = "${env.IMAGE_BASE}:${env.IMAGE_TAG}"
  IMAGE_NAME_LATEST = "${env.IMAGE_BASE}:latest"
  DOCKERFILE_NAME = "Dockerfile-packaged"
}

Переменные среды могут быть также объявлены как для всего пайплайна, так и для отдельного шага. Их можно использовать, чтобы вынести какие-то редкоизменяемый свойства. В этом блоке мы определим имя файла докера и имена создаваемых Docker-образов.


В предыдущих статьях при работе с кластером мы всегда использовали наиболее свежие latest образы, но напомню, что это не лучший вариант из-за проблем при откатах к предыдущим версиям. Поэтому мы предполагаем, что в начальный момент времени кластер создается из самых свежих образов, а потом уже будет обновляться на конкретную версию. Тег IMAGE_TAG будет зависеть только от номера билда, который можно получить из предустановленной глобальной переменной среды BUILD_NUMBER. Таким образом наши версии будут составлять монотонную последовательность при условии того, что пайплайн не будет пересоздаваться (это приведет к сбросу номера билда). При неуспешных билдах BUILD_NUMBER также будет инкрементирован, следовательно последовательность версий образов может содержать "пробелы". Основное преимущество такого подхода к версионированию — его простота и удобство восприятия человеком. В качестве альтернативы можно подумать об использовании метки времени, чексуммы коммита или даже внешних сервисов.


Компиляция, тестирование, сборка


stage("Prepare container") {
  agent {
    docker {
      image 'openjdk:11.0.5-slim'
      args '-v $HOME/.m2:/root/.m2'
    }
  }
  stages {
    stage('Build') {
      steps {
        checkout scm
        sh './mvnw compile'
      }
    }
    stage('Test') {
      steps {
        sh './mvnw test'
        junit '**/target/surefire-reports/TEST-*.xml'
      }
    }
    stage('Package') {
      steps {
        sh './mvnw package -DskipTests'
      }
    }
  }
}

Чисто технически фазы компиляции, тестирования и сборки возможно объединить в один шаг, но для лучшей наглядности мы опишем их как отдельные шаги. С помощью плагинов Maven можно с легкостью добавлять дополнительные фазы, такие как статический анализ кода или интеграционное тестирование.


На первом шаге мы выполняем чекаут репозитория проекта командой checkout scm. Адрес репозитория мы укажем после, при настройке пайплайна в Jenkins. Далее запускаем bash-команду на компиляцию проекта.


В фазе тестирования командой junit '**/target/surefire-reports/TEST-*.xml' мы указываем Jenkins'у на файл с результатами тестов. Это позволит их отобразить прямо в веб-интерфейсе.


На последнем шаге мы генерируем jar-архив с нашим приложением.


Создание и отправка Docker-образа в реестр


На следующем шаге мы должны собрать Docker-образы и запушить их в реестр. Мы будем делать это средствами Jenkins, но в качестве альтернативы можно реализовать это и с помощью Maven-плагина.


Для начала нам надо доработать докер-файлы наших сервисов, которые мы разработали в первой статье цикла. Эти докер-файлы собирали приложение из исходников прямо в процессе создания образа. Сейчас же у нас имеется протестированный архив, следовательно один из шагов создания образа уже выполнен средствами Jenkins. Мы назовем этот новый файл Dockerfile-packaged.


Старый Dockerfile
FROM adoptopenjdk/openjdk11:jdk-11.0.5_10-alpine as builder
ADD . /src
WORKDIR /src
RUN ./mvnw package -DskipTests

FROM alpine:3.10.3 as packager
RUN apk --no-cache add openjdk11-jdk openjdk11-jmods
ENV JAVA_MINIMAL="/opt/java-minimal"
# build minimal JRE
RUN /usr/lib/jvm/java-11-openjdk/bin/jlink     --verbose     --add-modules         java.base,java.sql,java.naming,java.desktop,java.management,java.security.jgss,java.instrument     --compress 2 --strip-debug --no-header-files --no-man-pages     --release-info="add:IMPLEMENTOR=radistao:IMPLEMENTOR_VERSION=radistao_JRE"     --output "$JAVA_MINIMAL"

FROM alpine:3.10.3
LABEL maintainer="Anton Shelenkov anshelen@yandex.ru"
ENV JAVA_HOME=/opt/java-minimal
ENV PATH="$PATH:$JAVA_HOME/bin"
COPY --from=packager "$JAVA_HOME" "$JAVA_HOME"
COPY --from=builder /src/target/microservices-backend-*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app.jar"]

Dockerfile-packaged:


FROM alpine:3.10.3 as packager
RUN apk --no-cache add openjdk11-jdk openjdk11-jmods
ENV JAVA_MINIMAL="/opt/java-minimal"
# build minimal JRE
RUN /usr/lib/jvm/java-11-openjdk/bin/jlink     --verbose     --add-modules         java.base,java.sql,java.naming,java.desktop,java.management,java.security.jgss,java.instrument     --compress 2 --strip-debug --no-header-files --no-man-pages     --release-info="add:IMPLEMENTOR=radistao:IMPLEMENTOR_VERSION=radistao_JRE"     --output "$JAVA_MINIMAL"

FROM alpine:3.10.3
LABEL maintainer="Anton Shelenkov anshelen@yandex.ru"
ENV JAVA_HOME=/opt/java-minimal
ENV PATH="$PATH:$JAVA_HOME/bin"
COPY --from=packager "$JAVA_HOME" "$JAVA_HOME"
COPY /target/microservices-backend-*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app.jar"]

Докер-файл для микросервиса шлюза аналогичен.


Шаг Push Images:


stage('Push images') {
  agent any
  when {
    branch 'master'
  }
  steps {
    script {
      def dockerImage = docker.build("${env.IMAGE_NAME}", "-f ${env.DOCKERFILE_NAME} .")
      docker.withRegistry('', 'dockerhub-creds') {
        dockerImage.push()
        dockerImage.push("latest")
      }
      echo "Pushed Docker Image: ${env.IMAGE_NAME}"
    }
    sh "docker rmi ${env.IMAGE_NAME} ${env.IMAGE_NAME_LATEST}"
  }
}

Изначально Jenkins поддерживал описание пайплайна только в императивном стиле, а поддержка декларативного подхода появилась намного позже. Разработчики Jenkins рекомендуют использовать именно декларативный подход как более выразительный, однако некоторые функции удобно вызывать внутри блока императивного кода командой script.


Командой docker.build мы собираем образ. Имя образа (уже включающее тег) может быть получено из переменных среды конструкцией ${env.IMAGE_NAME}. Во втором аргументе команды docker.build мы передаем опции для команды докера, а именно имя используемого докер-файла.


Команда docker.withRegistry('', 'dockerhub-creds') осуществляет подключение к реестру образов, используя данные из секрета 'dockerhub-creds'. Внутри этого блока мы пушим образ дважды, во втором случае переопределяя тег на 'latest'. Далее выводится диагностическое сообщение командой echo.


В конце шага происходит удаление установленных локально образов.


Обновление кластера Kubernetes


Финальным шагом осталось сообщить Kubernetes, что в реестре появился новый образ, и необходимо запустить процедуру обновления подов одного из микросервисов.


stage('Trigger kubernetes') {
  agent any
  when {
    branch 'master'
  }
  steps {
    withKubeConfig([credentialsId: 'kubernetes-creds', serverUrl: "${CLUSTER_URL}", namespace: "${CLUSTER_NAMESPACE}"]) {
      sh "helm upgrade ${HELM_PROJECT} ${HELM_CHART} --reuse-values --set backend.image.tag=${env.IMAGE_TAG}"
    }
  }
}

Команда withKubeConfig предоставляется плагином Kubernetes CLI и позволяет подключить kubectl к кластеру. После остается только прописать команду обновления свойств Helm-инсталляции. Также обращу внимание на использование предварительно объявленных глобальных переменных Jenkins, как, например, ${CLUSTER_URL}.


Итоговый Jenkinsfile


Jenkins-backend
pipeline {
  agent none
  options {
    skipStagesAfterUnstable()
    skipDefaultCheckout()
  }
  environment {
    IMAGE_BASE = 'anshelen/microservices-backend'
    IMAGE_TAG = "v$BUILD_NUMBER"
    IMAGE_NAME = "${env.IMAGE_BASE}:${env.IMAGE_TAG}"
    IMAGE_NAME_LATEST = "${env.IMAGE_BASE}:latest"
    DOCKERFILE_NAME = "Dockerfile-packaged"
  }
  stages {
    stage("Prepare container") {
      agent {
        docker {
          image 'openjdk:11.0.5-slim'
          args '-v $HOME/.m2:/root/.m2'
        }
      }
      stages {
        stage('Build') {
          steps {
            checkout scm
            sh './mvnw compile'
          }
        }
        stage('Test') {
          steps {
            sh './mvnw test'
            junit '**/target/surefire-reports/TEST-*.xml'
          }
        }
        stage('Package') {
          steps {
            sh './mvnw package -DskipTests'
          }
        }
      }
    }

    stage('Push images') {
      agent any
      when {
        branch 'master'
      }
      steps {
        script {
          def dockerImage = docker.build("${env.IMAGE_NAME}", "-f ${env.DOCKERFILE_NAME} .")
          docker.withRegistry('', 'dockerhub-creds') {
            dockerImage.push()
            dockerImage.push("latest")
          }
          echo "Pushed Docker Image: ${env.IMAGE_NAME}"
        }
        sh "docker rmi ${env.IMAGE_NAME} ${env.IMAGE_NAME_LATEST}"
      }
    }

    stage('Trigger kubernetes') {
      agent any
      when {
        branch 'master'
      }
      steps {
        withKubeConfig([credentialsId: 'kubernetes-creds', serverUrl: "${CLUSTER_URL}", namespace: "${CLUSTER_NAMESPACE}"]) {
          sh "helm upgrade ${HELM_PROJECT} ${HELM_CHART} --reuse-values --set backend.image.tag=${env.IMAGE_TAG}"
        }
      }
    }
  }
}


Jenkinsfile для микросервиса шлюза полностью аналогичен.


Подключение пайплайна


В Jenkins существует несколько видов пайплайнов. В данном проекте мы используем Multibranch pipeline. Как и следует из названия, билд будет запускаться для любого коммита в произвольной ветке.


После того как файлы конфигурации готовы, осталось настроить пайплайн в Jenkins. Это можно сделать в меню New Item -> Multibranch Pipeline. Интересующие нас разделы:


  • Branch sources. Выбираем GitHub, в графе 'Credentials' выбираем секрет с логином/паролем от аккаунта и указываем URL репозитория с исходным кодом микросервиса.


  • Build Configuration. В Mode выбираем 'by Remote File Plugin', основное поле — Repository URL, в котором надо указать адрес репозитория с Jenkinsfile, а также Script Path с путем к этому файлу.



  • Scan Repository Triggers. В этом разделе настроим период, с которым Jenkins будет проверять, появились ли какие-то изменения в отслеживаемом репозитории. Недостаток этого подхода в том, что Jenkins будет генерировать трафик, даже когда в репозитории ничего не менялось. Более грамотный подход — настроить веб-хуки. При этом хранилище исходного кода само будет инициировать запуск билда. Очевидно, что сделать это можно, только если Jenkins доступен по сети для хранилища исходных кодов (они должны быть либо в одной сети, либо Jenkins должен иметь публичный IP-адрес). Подключение веб-хуков оставим за рамками данной статьи.



Запуск


После того как наш пайплайн настроен, можно его запустить. Наиболее удобно это сделать из меню Blue Ocean (Open Blue Ocean). Первый запуск может занять продолжительное время, так как потребуется время на загрузку Maven-зависимостей. После выполнения билда можно подключиться к кластеру и убедиться в том, что тег образа микросервиса был изменен (helm get values msvc-project).


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


Заключение


Jenkins — очень гибкая система, позволяющая реализовывать процесс непрерывной интеграции и развертывания любой сложности. В этой статье мы только коснулись этого инструмента, создав простенький пайплайн для микросервисов нашего проекта. В будущем этот пайплайн можно значительно дорабатывать и улучшать, например, добавив уведомления, дополнительные шаги, веб-хуки и многое-многое другое.