Статья писалась в начале 2023 года и публиковалась на личном сайте который канул в лету, чтобы данный туториал не потанул вместе с сайтом публикую его здесь.

В этой статье описан “универсальный” пайплайн для сборки golang приложений. Универсальный в кавычках, потому что для сборки десятков разных приложений при помощи одного пайплайна нужно придерживаться  общих стандартов разработки. Которые как бывает не всегда соблюдаются даже в рамках одного проекта.

Шаги сборки 

Ниже описаны шаги которые могут присутствовать в вашем пайплайне, которые должен пройти ваш код для попадания из тестовой ветки в прод. В данной статье будут рассмотрены примеры реализации шагов выделенных жирным шрифтом.

• Получение кода;

• Запуск тестов;

• Статический анализ кода;

• Сборка кода;

• Сборка докер образа:

• Деплой деплой образа в registry;

• Деплой приложения на тестовую среду;

• Запуск интеграционных тестов;

• Запуск нагрузочного тестирования;

• Запуск любых дополнительных проверок которые вы посчитаете нужными;

• Деплой на прод. 

Инструменты 

Для реализации пайплайна будут использоваться следующие инструменты:

• Jenkins - для запуска пайплайна;
  * generic webhook trigger plugin
  * pipeline plugin
  * ssh agent plugin
  * sonarqube scanner plugin

• Harbor - для хранения docker образов;

• Sonarqube - для статического анализа кода;

• Github - для хранения исходников.

В статье не описано развертывание jenkins, harbor, SonarQube.

Пайплайн будет написан при помощи jenkins declarative pipeline.

Сборка будет производится на примере node_exporter

Требования к jenkins нодам

На нодах jenkins должны быть установлены:

• git;

• docker;

• java.

Получение кода

Для доступа к репозиторию нужно сгенерировать ssh ключ:

• Генерируем ключи;

• Заходим в Настроить jenkins > Manage credentials;

• Выбираем где будет хранится токен. У нас только 1 вариант. System > Global credentials (unrestricted)

• Нажимаем Add credentials и выбираем ssh username with ptivate key

Вводим ключ  id и описание. В id лучше вводить что то осмысленное;

• Добавляем публичный ключ в репозиторий.

На данном этапе получаем исходники из репозитория. Также определяем переменные для дальнейшего использования.

• sonarProject = код проекта в sonarqube;

• sonarProjectName = название проекта в sonarqube;

• gitCommitHash - короткий хэш коммита для использования в качестве версии докер образа;

• GIT_REPO_BRANCH и GIT_REPO_URL определяются в параметрах запуска.

• credentialsId: 'jenkins-jenkins' наш ssh ключ созданный выше.

    stages {
        stage('Get sources') {  //название этапа пайплайна
            steps {
                cleanWs() // очистка каталога сборки
                checkout([$class: 'GitSCM', branches: [[name: params.GIT_REPO_BRANCH]], extensions: [], userRemoteConfigs: [[credentialsId: 'jenkins-jenkins', url: params.GIT_REPO_URL]]])  // клонирование репозитория
                script { 
                    // получение информации из git для дальнейшего использования при сборке и в sonarqube
                    gitRepoPath = params.GIT_REPO_URL.substring(params.GIT_REPO_URL.lastIndexOf(":") + 1)
                    sonarProject = gitRepoPath.minus(".git").minus("-").minus("_").minus("/") 
                    sonarProjectName = gitRepoPath.minus(".git")
                    gitCommitHash = sh (script: "git log -n 1 --pretty=format:'%h'", returnStdout: true)
                    
                    currentBuild.displayName = sonarProjectName + " " + params.GIT_REPO_BRANCH 
                    currentBuild.description = sonarProjectName + " " + params.GIT_REPO_BRANCH + " " + gitCommitHash
                }
            }
        }

Запуск тестов

На данном этапе запускаются юнит тесты.

•  when  выполнение только при определенном значении переменной которая задается в параметрах запуска;

• beforeAgent true проверка условия запуска перед загрузкой образа агента;

• image params.BUILDER_IMAGE - контейнер в котором будут запускатся тесты, задается в параметрах;

• agent запуск этапа в докер контейнере;

• args  '-v /home/jenkins/.cache:/home/jenkins/.cache ' монтируется каталог с библиотеками go, для того чтобы не скачивать их при повторном запуске;

• reuseNode true - запуск на той же ноде, на которой запускались предыдущие шаги.

        stage ('Run tests') {
            when {  
                environment name: 'RUN_TESTS',
                value: 'true'
                beforeAgent true
            }
            agent {  
                docker {
                    image params.BUILDER_IMAGE
                    args  '-v /home/jenkins/.cache:/home/jenkins/.cache '
                    registryCredentialsId 'docker-registry'
                    registryUrl "https://harbor.iops-test.com"
                    reuseNode true
                }
            }
            steps {
                sh """
                make test
                """
            }
        }

Тесты на данном этапе запускаются в докер контейнере. Делается это для того чтобы не держать различные инструменты сборки всевозможных версий на одной ноде. В качестве registry используется harbor.

Статический анализ кода

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

После сканирования кода обработка результатов на стороне сервера sonarqube занимает некоторое время. Обработка может длится довольно долго при большом объеме кода. Так же webhook от сервера sonarqube с результатами  может провалится. Поэтому нужно всегда выставить таймаут.

Настройка SonarQube quality gate

• Заходим в SonarQube;

• В верхней панели навигации переходим на вкладку quality gate;

• Нажимаем Create;

• Вводим название нашего qg и нажимаем save;

• В открывшемся окне нажимаем add condition и вводим интересующие нас критерии. При несоответствии этим критериям qg будет считаться не пройденным и наш пайплайн завершится с ошибкой.

• Нажимаем кнопку set as default. Теперь все проекты будут по умолчанию привязаны к этому qg

Настройка SonarQube webhook

Для того чтобы jenkins мог получать результаты проверки quality gate нужно настроить webhook.

На стороне jenkins:

• Добавляем токен в credentials c типом secret text, как это было описано выше. токен вводим произвольный.

• Заходим в Настроить jenkins > Конфигурация системы;

• В разделе SonarQube servers наш токен в Webhook Secret;

• Остальные параметры также должны быть заполнены. Server authentication token - берется из настроек пользователя SonarQube;

На стороне SonarQube:

• Заходим в administration > configurations > webhooks

• Нажимаем Create;

• Вводим название, адрес jenkins, токен который мы указывали как Webhook Secret выше. адрес в формате  <jenkins>/sonarqube-webhook/

   stage ('Run sonar checks') {
            when {
                environment name: 'SONAR_CHECKS',
                value: 'true'
                beforeAgent true
            }
            agent {
                docker {
                    image 'sonarsource/sonar-scanner-cli'
                    args  '--rm  '
                    reuseNode true
                }
            }
            steps{
                script{
                    withSonarQubeEnv('sonar-server') { 
                        sh """
                        curl -u ${SONAR_AUTH_TOKEN}:  ${SONAR_HOST_URL}/api/projects/create -d 'project=${sonarProject}&name=${sonarProjectName}' # Создаем проект, если его еще нет
                        /opt/sonar-scanner/bin/sonar-scanner \ # запуск сканера
                        -Dsonar.projectKey=${sonarProject} \
                        -Dsonar.sources=./
                        """
                    }
                    timeout(time: 5, unit: 'MINUTES') { // таймаут на ожидание результатов
                        def qg = waitForQualityGate() // Reuse taskId previously collected by withSonarQubeEnv
                        if (qg.status != 'OK') { // завершение пайплайна при непрохождении qualitygate
                            error "Pipeline aborted due to quality gate failure: ${qg.status}"
                        }
                    }
                }
            }
        }

Сборка кода

На данном этапе собираем наше приложение. Здесь все аналогично этапу запуски тестов.

stage ('build service') {
    when {
        environment name: 'BUILD_SERVICE',
        value: 'true'
        beforeAgent true
    }
    agent {
        docker {
            image params.BUILDER_IMAGE
            args  '-v /home/jenkins/.cache:/home/jenkins/.cache '
            registryCredentialsId 'docker-registry'
            registryUrl "https://harbor.iops-test.com"
            reuseNode true
        }
    }
    steps {
        sh """
        make build
        """
    }
}

Сборка докер образа

Это последний этап сборки docker образа и его деплоя в harbor.

в качестве сборщика можно использовать образы из dockrhub или любых других внешних registry. Для этого в harbor нужно предварительно создать проект который проксирует запросы во внешние registry.

stage ('build docker image') {
    when { 
        environment name: 'BUILD_IMAGE',
        value: 'true'
        beforeAgent true
    }
    steps {
        script {
            docker.withRegistry('https://harbor.iops-test.com/', 'docker-registry') {
               sh """#!/bin/bash
               docker build -t harbor.iops-test.com/internal/sgapp:${gitCommitHash} . 
               docker push harbor.iops-test.com/internal/sgapp:${gitCommitHash}
               docker rmi harbor.iops-test.com/internal/sgapp:${gitCommitHash}
               """
            }
        }  
    }
}

Как результат мы имеем собранный образ в нашем registry. Там же его можно проверить на уязвимости.

Для примера взят другой образ.

Создание пайплайна

• Создаем item c типом pipeline.

• добавляем наш jenkinsfile c пайплайном который лежит в git.

сохраняем.

Запуск пайплайна

Запускаем пайплайн. Первый раз он провалится. т.к. при первом запуске наш джоб не знает ничего о параметрах запуска.

При втором запуске появляются параметры выполнения. Заполняем их.

Видно что все кроме сборки образа завершились  успешно. Это произошло потому что dockerfile учитывает сборку находящуюся в его репозитории. Она при выполнении копирует бинарники по другим путям. Конечно если вы пишете автоматизацию сборки сами у вас все это должно совпадать. Для того чтобы это обойти можно написать дополнительные этапы пайплайна для получения dockerfile из отдельного репозитория.

слева на экране мы видимо историю сборок.

щелкнув по значку SonarQube  перейдем в проект  и увидим результаты проверки.

Но все таки давайте проверим что наш пайплайн работает полностью. Для этого напишем простое приложение и попробуем его собрать. Так же, вероятно вам не захочется каждый раз запускать руками сборку. Добавим автосборку по пушу. Для этого будем использовать generic webhook plugin.

Для создания вебхука который будет запускать наш пайплайн зайдем в настройки репозитория с нашим приложением - https://github.com/kilin-s/sgapp/.

• Заходим в настройки settings > webhook > add webhook;

• Добавляем ссылку на jenkins в формате <jenkins>/generic-webhook-trigger/invoke?token=abc123

Кроме доступа к jenkins По токену будет определятся пайплайн для запуска.

В нашем пайплайне добавляем следующие строки

triggers {
    GenericTrigger(
        genericVariables: [
            [key: 'GIT_REPO_URL', value: '$.repository.ssh_url'],
            [key: 'GIT_REPO_BRANCH', value: '$.ref']
        ],
        causeString: 'Triggered on $ref',
        tokenCredentialId: 'go-build-common-hook',
        printContributedVariables: true,
        printPostContent: false,
        silentResponse: false,
        shouldNotFlattern: false
    )
}

• tokenCredentialId - токен используемый дя запуска, берется из credentials;

• genericVariables - запись значений полей из json запроса в параметры запуска.

Для того чтобы webhook начал работать пайплайн нужно запустить еще раз.

Сделаем еще 1 коммит в наш репозиторий для проверки запуска и сборки.

Пайплайн завершился успешно.

Заключение

Данный пайплайн можно использовать как отправную точку для построения своего ci. 

Добавлять любые шаги и проверки. С доработкой использовать его как проверку пул реквестов или просто сборки своих приложений. 

ссылки:

sonarqube jenkins extension

 репозиторий собираемого приложения

Репозиторий с пайплайном

jenkins pipeline syntax

node exporter

harbor