Подключение и конфигурирование#

Оглавление#

• Конфигурирование pipeline (pipeline.yml)

  • Настройка инструментов сборки

  • Конфигурирование блока fp

  • Настройка блока distribution

  • Заполнение раздела qgm

  • Заполнение раздела docker

  • Заполнение разделов bh, db

  • Заполнение раздела pl

  • Заполнение раздела Jenkinsfiles

  • Описание зависимостей дистрибутива

  • Подключение и настройка расширений

  • Конфигурирование блока downloads

  • Пример файла конфигурации (с указанием назначения параметров в комментариях)

  • Параметризация pipeline.yml

  • Объявление переменных окружения через pipeline.yml

• Настройка Jenkins job

  • Параметр PLAYBOOKS

  • Параметр type: String Parameter

  • Параметр type: Boolean Parameter

• Заполнение конфигурации скриптов развертывания

Конфигурирование pipeline (pipeline.yml)#

Сборка дистрибутива в библиотеке ufs-pipeline управляется с помощью конфигурации, описанной в файле pipeline.yml, и содержащей:

1. Настройки инструментов сборки (maven, npm).

2. Реквизиты дистрибутива (maven-координаты) (fp).

3. Адреса и параметры учетной записи доступа для загрузки (distribution).

4. Реквизиты дистрибутива для установки флагов (qgm).

5. Реквизиты сборки Docker-образов (docker).

6. Описание зависимостей дистрибутива (с разбивкой по профилям) (profiles).

7. Описание подключения и сборки компонентов дистрибутива (bh, pl, db, jenkinsfiles).

8. Описание загрузки дополнительных артефактов (downloads).

9. Подключение и настройки расширений (extensions).

Файл pipeline.yml может также быть параметризирован переменными окружения.

Настройка инструментов сборки#

В файле конфигурации сборки доступна настройка нескольких инструментов сборки: maven, npm и sonar, причем:

• настройка maven обязательна и требуется в любом случае

• настройку npm необходимо выполнять только в том случае, если используется блок pl

• настройку sonar рекомендуется выполнить, но при ее отсутствии будет использована инсталляция SonarQube с токеном доступа по умолчанию

Примеры настройки:

### Настройки MAVEN ###
maven:
  # Идентификатор файла в folder, который следует подключить через configFileProvider. Рекомендуемый вариант подключения
  settings_id: 'maven-settings'
  # Maven настроенный в Jenkins. Доступные версии можно посмотреть в Pipeline Syntax - snippet generator - tool - Maven
  home: 'Maven 3.6.3'
  # JDK настроенный в Jenkins. Доступные версии можно посмотреть в Pipeline Syntax - snippet generator - tool - JDK
  jdk: 'jdk-11.0.10_linux'
  # Опции, которые будут прокинуты во все maven-сборки
  options: '-Xmx100m'
  
### Настройки NodeJS ###
npm:
  # Идентификатор файла в folder, который следует подключить через configFileProvider. Рекомендуемый вариант подключения
  config_id: "npm-settings"
  # Версия NodeJS, настроенная в Jenkins. Доступные версии можно посмотреть в Pipeline Syntax - snippet generator - tool - NodeJS
  version: "v7.5.0-linux-x64"

### Настройки SonarQube ###
sonar: 
   credentialsId: sonar-token-cred # Идентификатор credentials с типом Secret text
   installationName: SonarQube # Название инсталляции SonarQube следует уточнить у владельцев Jenkins
   sonar_timeout: 20 # Если параметр задан: изменить в минутах время ожидания ответа Quality Gate статуса от SonarQube сервиса

Список версий JDK, maven, nodejs и т.д. можно посмотреть, зайдя в конфигурацию любой Jenkins job, и нажав Pipeline Syntax в самом низу, далее Snippet Generator и выбрать в списке tool:

Также для управления инструментами можно использовать гибкий туллинг. Для использования гибкого туллинга необходимо прописать секцию tools в pipeline.yml в виде словаря инструментов, где ключом будет variable. Вы также можете использовать в имени переменной синтаксис PATH+WHATEVER=/something для добавления /something к $PATH.

Обязательные параметры:

• tool - имя инсталляции инструмента. Можно получить из Pipeline Syntax Jenkins Job.

• variable - имя переменной окружения, по которому можно обратится к инструменту. Необязательные параметры:

• subPath - дополнительный путь, который используется для обращения к инструменту.

  Пример заполнения:

tools:
  PATH+MAVEN:
    tool: "Maven 3.8.1"
    subPath: "bin"
  JAVA_HOME:
    tool: "openjdk-13"

Конфигурирование блока fp#

Блок fp содержит maven-координаты дистрибутива, который включает следующие опции для заполнения:

• groupId - Group ID дистрибутива.

• artifactId - Artifact ID дистрибутива.

• version - Версия дистрибутива. Данный параметр может иметь любое значение, к которому будет добавлен номер сборки. Разделитель номера сборки - знак «минус», который также можно переопределить с помощью переменной окружения BUILD_NUMBER_SEPARATOR. (Например, D-01.000.00-123, где 123 - номер сборки)

• version_meta - Параметр, значение которого добавляется к указанной версии дистрибутива через разделитель _.

• component_code - 4-х буквенный код компонента дистрибутива.

• templating - Значение типа boolean, по умолчанию равна true. Если установлена в false, этап шаблонизации будет пропущен.

Если вы не знаете свой component_code, то можете указать artifactId в качестве его значения (ограничение на 4 символа в этом случае не действует)

Пример:

fp:
  groupId: distribution.group.id
  artifactId: distribution-artifact-id
  # Maven version для артефакта инсталляционного пакета. К нему будет добавляться номер сборки. В результате для build с номером 123 в Nexus будет выгружен артефакт с версией D-01.000.00-123
  version: "D-01.000.00"
  # Добавляет постфикс к версии дистрибутива в формате version-BUILD_NUMBER_version_meta, например D-01.000.00-472_SECTOR_1
  version_meta: "SECTOR_1"
  component_code: cije # Код компонента вашего дистрибутива.

Настройка блока distribution#

Блок distribution включает в себя набор репозиториев, в которые необходимо загрузить собранный дистрибутив. Для каждого репозитория нужно указать параметры:

• url - ссылка на репозиторий для выгрузки;

• serverId - запись в settings.xml, в которой хранятся данные учетной записи с правами на запись в указанный репозиторий;

• classifiers - классификаторы для выгрузки. Название классификатора является ключом объекта. Для каждого классификатора нужно указать следующие параметры:

  • file - путь к файлу для выгрузки. Допустимо использовать bash- маски, но с тем ограничением, что под маску должен попадать только один файл,

  • type - тип файла - тот тип, под которым он будет загружен в репозиторий.

для обеспечения обратной совместимости, в случаях, когда classifiers отсутствует, он заполняется значением по умолчанию: {"distrib":{"file":"tmp/*-distrib.zip","type":"zip"}}

Пример заполнения:

distribution:
  - url: https://your.company.maven.server/repo/your-repo
    serverId: cdp # В settings.xml есть server с id=cdp
    classifiers:
       distrib: 
          file: distribution-artifact-id-*.zip
          type: zip
    '': # Для загрузки артефакта без классификатора, следует указать пустой
      file: some-jar.jar
      type: jar
      

Заполнение раздела qgm#

Помимо загрузки дистрибутива в хранилище библиотека сборки также отправляет данные в QGM (Release Notes и флаги).

В разделе qgm указываются credentials, под которыми должна производиться отправка данных артефактов, а также параметр repository.

Пример заполнения:

qgm:
  repository: my-repo
  creds: my-qgm-creds

Заполнение раздела docker#

Раздел docker содержит следующие опции:

• registry_address - адрес registry, в который должны быть загружены образы;

• builder_token - credentials с доступом в registry на запись в registry_address;

• image_path - путь образов внутри registry_address;

• args - добавляет дополнительные пользовательские параметры при исполнении команды docker build, по умолчанию выставлен флаг –no-cache=true;

• additional_registries - список дополнительных registry, вход в которые будет осущеcтвлен помимо registry_address (это может потребоваться, если, например, базовый образ лежит в registry, отличном от registry_address).

• builder - билдер, допустимые значения: docker, buildx, buildctl, по умолчанию автоопределяется;

• build_args - список дополнительных пользовательских аргументов для сборки формат которых не зависит от билдера;

• image_manifest - при значении true опция позволяет образу кеша быть совместимым со всеми registry посредством добавления image-manifest=true в команду сборки buildctl;

Опции для работы с разделом dockefiles, определяемые в подразделе cache:

• registry - адрес registry, в который должен быть загружен кеш образа;

• path - путь до папки, в которой будет лежать кеш образов.

• credential_id - идентификатор Jenkins Credentials, который будет использован для авторизации в registry кеширования. Если параметр не задан, будет использоваться builder_token из секции docker.

docker:
  registry_address: "registry.<...>.ru"
  builder_token: "b65d28a6-056a-444c-a25f-8d2b222b5d60"
  additional_registries:
    - registry_address1
    - registry_address2
  image_path: some/path/to/my/images
  args: "--no-cache=true"
  build_args:
    TEST_VAR: "test_value,test_value1,test_value2"
    SOME_VAR: "some_value"
    
  # Опции для работы с разделом `with_docker`
  cache:
    registry: "registry.<...>.ru"
    path: "some/path/to/my/cache/folder"

Динамические команды сборки для docker и buildctl из примера заполнения: docker –config /u01/jenkins_agent/workspace/cije/AT/regress-test/tmp/containerConfig build . –file - –tag <…>/test_app/test_app_backend:D-01.000.02.25419 --build-arg TEST_VAR=test_value,test_value1,test_value2 --build-arg SOME_VAR=some_value –no-cache=true buildctl –addr=unix:///run/buildkit/buildkitd.sock build –frontend dockerfile.v0 –progress=plain –local context=. –local dockerfile=conf/openshift/test_app_backend/ –opt filename=./Dockerfile –metadata-file hash_test_app_backend.json –output type=image,name=s<…>/test_app/test_app_backend:D-01.000.02.25423,push=true --opt build-arg:TEST_VAR=test_value,test_value1,test_value2 --opt build-arg:SOME_VAR=some_value –no-cache=true

Есть возможность отключить сборку докер-образа, добавив в Jenkins job сборки дистрибутива boolean параметр SKIP_BUILD_DOCKER, либо добавив в pipeline.yml в раздел docker параметр skip_build_docker. Значение у параметров должно быть true.

Заполнение разделов bh, db#

Разделы bh и db сдержит список репозиториев, в которых надо выполнить сборку. Каждый элемент этого списка содержит следующие параметры:

• name - название элемента (рекомендуется использовать уникальные значения всех name во всех блоках);

• repo - адрес репозитория, содержащего maven-проект;

• branch - ветка репозитория;

• cmd - maven-цели или плагины, которые надо вызвать (например, package);

• args - дополнительные аргументы, которые необходимо добавить в каждую команду запуска (в том числе в команду запуска SonarQube);

• outputs - список файлов, которые нужно скопировать в дистрибутив после сборки (выполнения всех команд из cmd). Для раздела bh предусмотрена возможность переместить артефакты вручную посредством опций:

  • source - путь до артефакта (может быть указана маска). Задается относительно корня обрабатываемого репозитория; dest - директория назначения выбранного артефакта. Задается относительно workspace;

• create_tag - значение типа boolean, по умолчанию false (если значение параметра выставлено в true, то создается аннотированный тег с версией, декларированной разделом fp);

• sonar_cmd (только для bh) - возможность переопределить команду запуска SonarQube-сканирования (рекомендуется использовать данный параметр, т.к. иначе работает довольно незаурядная логика, которая оставлена в угоду обратной совместимости);

• sonarPomConfigured (только для bh) - если значение true, в команду запуска SonarQube-сканирования не будут внедрены дополнительные параметры;

• sonarSkip - если true, пропустить SonarQube-сканирование;

• issue_pattern - регулярное выражение, по которому определяется идентификатор запроса в JIRA из commit (по стандарту '[A-Za-z][A-Za-z0-9]+-[0-9]+').

• sonar (только для bh) - составной параметр, содержит опции:

  • mainBranch - основная ветка в SonarQube;

  • longLivingBranchesPattern - шаблон долгоживущих веток (в терминах SonarQube).

• parallel - опция использования параллельной сборки.

  Если для двух приложений будет указано одинаковое значение parallel, то они будут запускаться в общем потоке. (может использоваться для сборки Dockerfiles, PL’s, Jenkinsfiles, DB’s и BH’s).

• skip - если установить в true сборка данного артефакта будет пропущена.

Отличия сборки bh и db:

• Для db не выполняется запуск SonarQube;

• В результате сборки db должен появиться ZIP-архив со скриптами Liquibase.

Требования к репозиториям в разделе db и bh описаны в соответствующих разделах (db, bh).

Примеры:

bh:
  - name: "bh-app-1"
    repo: "project/bh-app-1.git"
    branch: "release/pir1024"
    args: "-f myproject/pom.xml"
    cmd:
      - "clean test"
      - "install"
    outputs:
      - source: "myproject/bh-app-1-ear/target/*.ear"
        dest: "package/bh"
    sonarPomConfigured: true
    sonar:
      mainBranch: 'master'
db:
  - name: "db-1"
    repo: "dbufs/db-1.git"
    branch: "release/pir1024"
    cmd: "clean package -P!liquibase,packageOnly"
    outputs:
      - "./target/efsct-db*.zip"

Заполнение раздела pl#

Раздел pl содержит список nodejs-репозиториев, в которых надо выполнить сборку с помощью npm. Перед сборкой будет выполнена подгрузка зависимостей (npm ci). Каждый элемент списка содержит следующие параметры:

• name - название элемента (рекомендуется использовать уникальные значения всех name во всех блоках);

• repo - адрес репозитория, содержащего maven-проект;

• branch - ветка репозитория;

• create_tag - значение типа boolean, по умолчанию false (если значение параметра выставлено в true, то создается аннотированный тег с версией, декларированной разделом fp);

• cmd - команда сборки проекта (например, npm build );

• install - альтернатива стандартной команде подгрузки зависимостей (если задана, будет выполнена вместо npm ci);

• link_sshpk - если true, перед сборкой будет выполнена команда npm link sshpk;

• link_sass - если true, перед сборкой будет выполнена команда npm link node-sass;

• sonarSkip - если true, пропустить SonarQube-сканирование;

• issue_pattern - регулярное выражение, по которому определяется идентификатор запроса в JIRA из commit (по стандарту '[A-Za-z][A-Za-z0-9]+-[0-9]+').

• outputs - список файлов, которые нужно скопировать в дистрибутив после сборки (выполнения команды из cmd) (файлы попадут в папку package/pl дистрибутива).

• parallel - опция использования параллельной сборки.

  Если для двух приложений будет указано одинаковое значение parallel, то они будут запускаться в общем потоке (может использоваться для сборки Dockerfiles, PL’s, Jenkinsfiles, DB’s и BH’s).

• skip - если установить в true, сборка данного артефакта будет пропущена.

Пример заполнения:

pl:
  - name: my-pl
    repo: cije/test.app.frontend.git
    branch: develop
    cmd: 'npm pack'
    outputs: 
      - '*.tgz'

Требования к самим репозиториям, перечисленным в pl, описаны в соответствующем разделе.

Заполнение раздела Jenkinsfiles#

Для подключения сборки Jenkinsfiles необходимо в файле pipeline.yml добавить блок jenkinsfiles, в котором нужно указать список репозиториев, содержащих исполняемые Jenkins файлы.

Каждый элемент из этого списка содержит следующие параметры:

• name - название элемента. Рекомендуется использовать уникальные значения всех name во всех блоках;

• repo - адрес репозитория, содержащего Jenkinsfile;

• branch - ветка репозитория с Jenkinsfile;

• sonarSkip - если true, пропустить SonarQube-сканирование;

• issue_pattern - регулярное выражение, по которому определяется идентификатор запроса в JIRA из commit (по стандарту '[A-Za-z][A-Za-z0-9]+-[0-9]+').

• create_tag - значение типа boolean, по умолчанию false (если значение параметра выставлено в true, то создается аннотированный тег с версией, декларированной разделом fp);

• script_path - относительный путь к файлу с описанием сборки компонентов - jenkinsfile (по умолчанию: Jenkinsfile);

• parallel - опция использования параллельной сборки. Если для двух приложений будет указано одинаковое значение parallel, то они будут запускаться в общем потоке. (может использоваться для сборки Dockerfiles, PL’s, Jenkinsfiles, DB’s и BH’s.);

• skip - если установить в true, то сборка данного Jenkinsfile будет пропущена;

• Любой дополнительный набор параметров, которые нужно передать в Jenkinsfile.

Для ускорения сборки дистрибутива существует возможность параллельной сборки Jenkinsfile. Для этого необходимо использовать опцию parallel, в значении которой указывается строка.

Если для двух приложений будет указано одинаковое значение parallel, то они будут запускаться в общем потоке.

### Ссылки на сборочные Jenkins-файлы ###

jenkinsfiles:
  - name: "test.app.backend" # любое
    repo: "<...>/test.app.backend.git" # url без хоста
    branch: "develop" # ветка сборки
  - name: "test.app.frontend" # любое
    repo: "<...>/test.app.frontend.git" # url без хоста
    branch: "develop" # ветка сборки
    parallel: front
    # параметры, описанные ниже, могут быть использованы в jenkinsfile
    param1: value1 # app.param1
    param2: value2 # app.param2
    complexParam:
      attr1: value3 # app.complexParam.attr1
      attr2: value4 # app.complexParam.attr2

Требования к содержимому Jenkinsfile описаны в соответствующем разделе.

Описание зависимостей дистрибутива#

Зависимости дистрибутива описываются в секции profiles. Такое название дано, поскольку все зависимости должны быть помещены под соответствующие профили, и в каждом профиле должен быть описан набор зависимостей.

Каждая зависимость описывается maven-координатами:

• groupId

• artifactId

• version

• type (необязательная координата, по умолчанию jar)

• classifier (необязательная координата)

Пример:

profiles:
  some-profile: # название профиля (some-profile)
    - groupId: some.group.id
      artifactId: some-artifact-id
      version: some-version
      type: zip # если зависимость - это дистрибутив - то ее type=zip
      classifier: distrib # если это дистрибутив - то classifier=distrib
  some-another-profile:
    - groupId: some.another.group.id
      artifactId: some-another-artifact-id
      version: some-another-version
      type: zip 
      classifier: distrib 

Все эти зависимости будут добавлены в файл pom.xml дистрибутива.

Подключение и настройка расширений#

В конфигурации сборки есть секции, позволяющие подключать и отключать точки расширения.
Список существующих точек расширения следует смотреть в документации репозитория jenkinsfiles (репозиторий с точками расширения).
Для подключения расширения используется секция extensions. В этой секции списком указываются расширения, которые нужно подключить. Каждый элемент списка может содержать следующие параметры:

• name - название расширения. По сути, единственный обязательный параметр. Если элемент - это строка, то эта строка - значение поля name. Все остальные поля имеют дефолтные значения (указаны в скобках):

• repo (<…>/jenkinsfiles.git) - репозиторий, из которого нужно взять расширение;

• branch (master) - ветка, из которой нужно взять расширение;

• script_path (<name>.groovy) - название скрипта, реализующего расширение;

• stage (берется из getDefaultConfig расширения) - название этапа (stage), к которому привязывается расширение (список вариантов ниже);

• phase (берется из getDefaultConfig расширения) - фаза (до или после), в которую нужно вызвать расширение;

• skip (false) - опция для выключения расширения из pipeline.yml;

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

Список stage:

• prepare

• build

• downloads

• docker

• templating

• pack

• upload

• finally

Список phase:

• before

• after

Если в качестве элемента списка указано только название расширения, все остальные параметры рассчитываются по следующим правилам:

• script_path = <имя расширения>.groovy;

• repo = <проект этого репозитория (ufs-pipeline)>/jenkinsfiles.git;

• branch = master. Также существует возможность более гибкой настройки расширения.

extensions:
  - generateJenkinsFile # будет взято расширение generateJenkinsFile.groovy из репозитория jenkinsfiles
  - name: MoveDockerfile
    branch: feature/superfeature # будет взято расширение MoveDockerfile.groovy из ветки feature/superfeature
  - name: securityChecks
    devsec_repo: 'repo' # репозиторий с библиотекой sast/oss
    run_sast: true
    run_oss: true
  - name: MyCustomExtension
    repo: myproject/myrepo.git
    branch: master
    script_path: superEx.groovy
    stage: pack
    phase: before
    # ниже представлен набор параметров, которые может использовать расширение
    param1: value1
    param2: value2
    param3: value3
    complexParam:
      someAttr1: value4
      someAttr2: value5
    check_rn: true
    checked_flags:
      - oss
      - sast

Ряд расширений включен по умолчанию:

• updateVersionConf - добавляет в дистрибутив актуальный файл version.conf

• AddDescription - добавляет в сборку описание со ссылками на загруженные артефакты

• analyzeDependencies - добавляет этап анализа зависимостей собранных Docker-образов

• makeReleaseNotes - добавляет сборку ReleaseNotes

Для их отключения используется секция disabled_extensions (при этом расширения, явно подключенные в разделе extensions, выключены не будут):

disabled_extensions: 
  - AddDescription
  - analyzeDependencies

Также для поддержки обратной совместимости автоматически подключается расширение legacyMavenCoordinates в случае наличия устаревшего параметра artifact_type.

Для подключения точек расширения, не имеющих дополнительных параметров, достаточно в списке extensions указать только их название, например:

extensions:
  - generateJenkinsFile
  - MoveDockerfile

Рекомендации по разработке собственных точек расширения описаны в соответствующем разделе. Точки расширения, привязанные к stage finally, будут выполнены в любом случае, даже при ошибке выполнения любого из предыдущих этапов.

Конфигурирование блока downloads#

Блок downloads содержит список параметров загрузки различных файлов. Обязательные параметры:

1. type - тип файла. От него зависит в какую папку инсталляционного пакета он попадет. Возможные варианты описаны ниже.

2. source - источник файла. Набор параметров для конфигурации различается для разных источников.

3. dest - назначение файла. Параметр, указывающий путь назначения файла из параметра source.

Необязательный параметр:

1. • skip - если установить в true, сборка артефакта, если она подразумевается, будет пропущена.

Типы файлов бывают следующими:

1. bh - файлы с backend двоичными данными (business hub);

2. pl - файлы с frontend (presentation layer);

3. db - файлы с liquibase-скриптами настройки БД;

4. conf - файлы конфигурации (различные YAML, CONF, JSON файлы);

   Внимание

   Если есть хотя бы один такой файл, то исходный репозиторий с конфигурацией в дистрибутив скопирован не будет. Чтобы сохранить в дистрибутив содержимое репозитория конфигурации, нужно добавить параметр copyMainConfig: true.

5. docs - файлы документации;

6. sdk_mvn - файлы библиотек maven, распространяемых вместе с дистрибутивом. Допустимый source - только nexus, причем помимо файла будет также скачан pom-файл;

7. sdk_npm - файлы библиотек npm, распространяемых вместе с дистрибутивом. Допустимый source - только filesystem, причем параметры в этом случае используются иначе:

   1. используется только параметр subdir;

   2. файл копируется из пути [workspace]/[subdir];

   3. требуется добавить настройку coordinates: {name: '[name]', version: '[version]'}.

Источники файлов могут быть следующими:

1. filesystem - текущая нода сборки. Позволяет скопировать любой файл из собранных репозиториев (jenkinsfile/bh/pl и т.д.). Связка с собранным элементом осуществляется с помощью параметра name - будет использован элемент с таким же name. При этом настройки того, какие конкретно файлы копировать, аналогичны источнику git (кроме cmd).

2. git - репозиторий. Для настройки используются следующие параметры:

   1. repo - path репозитория

   2. branch - ветка, из которой требуется скопировать файл(ы)

   3. name - название элемента (может быть использовано для копирования элементов при source: filesystem)

   4. subdir - будут скопированы файлы из заданной директории репозитория

   5. files - маска, по которой будут скопированы файлы

   6. cmd (необязательный) - при желании можно вызывать maven-команду перед копированием

   7. issue_pattern (необязательный) - регулярное выражение, по которому определяется идентификатор запроса в JIRA из commit (по стандарту '[A-Za-z][A-Za-z0-9]+-[0-9]+').

3. nexus - maven-артефакт, который можно скачать с помощью settings.xml, указанного в разделе maven. Параметры:

   1. groupId - groupId артефакта

   2. artifactId - artifactId артефакта

   3. version - версия артефакта. Если необходимо указать версию неявно (например, чтобы Jenkins job брал какую-то последнюю), следует указывать ее в формате Maven Dependency Version Ranges

   4. classifier (необязательный) - classifier артефакта

   5. packaging (необязательный, по умолчанию jar) - packaging/type артефакта

4. confluence - скачать страничку из confluence. Для работы данного источника, нужно настроить раздел confluence.

Пример файла конфигурации (с указанием назначения параметров в комментариях)#

### Настройки NodeJS ###
npm:
  # Идентификатор файла в вашем folder, который следует подключить через configFileProvider. Рекомендуемый вариант подключения. Настройка npm-settings в Jenkins
  config_id: "npm-settings"
  # Версия NodeJS, настроенный в Jenkins. Доступные версии можно посмотреть в Pipeline Syntax - snippet generator - tool - NodeJS
  version: "v7.5.0-linux-x64"

### Настройки MAVEN ###
maven:
  # Идентификатор файла в вашем folder, который следует подключить через configFileProvider. Рекомендуемый вариант подключения.
  settings_id: "maven-settings" # Настройка maven-settigns в Jenkins
  # Maven настроенный в Jenkins. Один на все проекты, меняться не должен
  home: "Maven 3.2.5"
  # JDK настроенный в Jenkins. Один на все проекты, меняться не должен
  jdk: "JDK_1.7_45_Linux"

distribution:
  - url: "..."
    serverId: "..."
  - url: "..."
    serverId: "..."
qgm:
  repository: "..." # Имя репозитория Nexus
  creds: "..."

profiles:
  some_profile:
    - groupId: "some.group.id"
      artifactId: "some-artifact"
      version: "D-ver"
      type: zip
      classifier: distrib
  # Профиль binaries обязателен для дистрибутива конфигураций. При сборке binary загружаются и распакуются в папку дистрибутива
  binaries:
    - groupId: "some.group.id"
      artifactId: "some-artifactId-bin"
      version: "D-01.004.05-765"
      type: zip
      classifier: distrib

extensions:
  - name: std5Configuration

### Настройки CONFLUENCE ###
confluence:
  # ID данных авторизации в Confluence. Используем credentialsId, полученный на шаге Настройка Jenkins
  creds: "ad50b262-dda8-4fae-a0d5-45b9e16041b8"
  # Корневую ссылку Confluence можно задать в виде root_url. Один на все проекты - можно не менять
  root_url: "https://confluence.ca.<host-name>"

### Настройки SW.META ###
meta:
  # ID данных авторизации в SW.META. Используем credentialsId ТУЗ с правами загрузки модели
  creds: "ad50b262-dda8-4fae-a0d5-45b9e16041b8"
  # Корневая ссылка API SW.META
  # Если не указана будет использована https://meta.<domain>/basic для ALPHA,
  # для SIGMA: https://meta.<domain>
  root_url: "https://meta.<domain>/basic"
  # Код компонента из ARIS. Также можно посмотреть на портале META в карточке своей АС.
  code: "ad50b262-dda8-4fae-a0d5-45b9e16041b8"

### Настройки сборки приложения ###
fp:
  # Maven groupId для артефакта инсталляционного пакета.
  groupId: "AS_EFS.AS_EFS_???.Distrib"
  # Maven artifactId для артефакта инсталляционного пакета.
  artifactId: "AS_EFS_???"
  # Maven version для артефакта инсталляционного пакета. К нему будет добавляться номер сборки, в результате для собрки с номером 123 в Nexus будет выгружен артефакт с версией D-01.000.00-123
  version: "D-01.000.00"
  # Добавляет постфикс к версии дистрибутива в формате version-BUILD_NUMBER_version_meta, например D-01.000.00-472_SECTOR_1
  version_meta: "SECTOR_1"

### Список приложений BH, которые нужно собрать из исходников ###
bh:
  # ID приложения. Используется при сборке как название папки куда клонируется репозиторий
  - name: "bh-app-1"
    # путь к репозиторию в Bitbucket, где лежат исходники приложения
    repo: "project/bh-app-1.git"
    # ветка, которую нужно собирать
    branch: "release/pir1024"
    # аргументы Maven, например, можно указать относительный путь к pom.xml, который нужно собрать
    args: "-f subfolder/pom.xml"
    # команды Maven, которыми собираем проект
    cmd:
      - "clean test"
      - "install"
    # Список шаблонов файлов, которые нужно скопировать в инсталляционный пакет после сборки (задается относительно корня репозитория)
    outputs:
      - "./bh-app-1-ear/target/*.ear"
    # Необязательный параметр. По умолчанию: false. true - в случае, если для запуска проверки SonarQube QG достаточно выполнить sonar:sonar
    sonarPomConfigured: false,
    # Необязательный параметр. По умолчанию false. true - в случае для модулей, не попадающих в ПРОМ и не требующих прохождения QG (например, envelope ear для развертывания jar на тестовые стенды)
    sonarSkip: false,
    skip_rn: true, # Используется для того, чтобы пропустить сбор Release Notes для данного репозитория
    prod_branch: 'release/18.5', #если хотим указать для репозитория версию ПРОМ
    issue_pattern: '[A-Za-z][A-Za-z0-9]+-[0-9]+' # Регулярное выражение, по которому определяется идентификатор запроса в JIRA из commit. Если хотим отличное от приведенного - указываем его.
    sast_skip: true # По умолчанию: false. При значении true отключает сканирование репозитория sast/oss
    parallel: parallel # Запустить параллельную сборку с именем потока parallel

### Список приложений PL, которые нужно собрать из исходников ###
pl:
  # ID приложения. Используется при сборке как название папки куда клонируется репозиторий
  - name: "pl-app-1"
    # Путь к репозиторию в BitBucket, где лежат исходники приложения
    repo: "project/pl-app-1.git"
    # Ветка, которую нужно собирать
    branch: "release/pir1024"
    # Команда которой осуществляется сборка
    # cmd: "npm run build"
    cmd: "node ./scripts/profile.js"
    # Создавать ли символическую ссылку (симлинк) на локальный node-sass, установленный в Jenkins
    link_sass: false
    # Создавать ли симлинк на локальный sshpk установленный в Jenkins
    link_sshpk: false
    # Пропустить сбор Release Notes для данного репозитория
    skip_rn: true
    # Список шаблонов файлов, которые нужно скопировать в инсталляционный пакет после сборки (задается относительно корня репозитория)
    outputs:
      - "./archive/dist*.zip"
    sast_skip: true # По умолчанию false. При значении true отключает сканирование репозитория sast/oss
    parallel: parallel # Запустить параллельную сборку с именем потока parallel

### Список скриптов БД, которые нужно собрать из исходников ###
db:
  # Сборка осуществляется так же как и сборка BH, все параметры аналогичны
  - name: "db-1"
    repo: "dbufs/db-1.git"
    branch: "release/pir1024"
    # Команда для сборки только одного подпроекта в многомодульном проекте
    cmd: "clean package -P!liquibase,packageOnly"
    args: "-f project/pom.xml",
    outputs:
      - "./project/target/efsct-db*.zip"
    parallel: parallel # Запустить параллельную сборку с именем потока parallel

### Список артефактов, которые нужно загрузить из Nexus ###
downloads:
  - {source: "confluence", type: "docs", pages: ['98876674']}
  - {source: "nexus", type: "db", repoId: "efs_release_db", groupId: "ru.<host-name>.database", artifactId: "project-db", version: "26.*", packaging: "zip"}
  - {source: "git", type: "docs", repo: "smefs/startmanager-bh.git", branch: "develop", subdir: "authorization-parent/docs", files: "*.docx", sast_skip: true}
  - {source: "git", dest: "$WORKSPACE/sources/", repo: "smefs/startmanager-bh.git", branch: "develop", subdir: "tmp/source", files: "*.txt", sast_skip: true}
  - {source: "git", type: "docs", repo: "smefs/startmanager-bh.git", branch: "develop", subdir: "authorization-parent/docs", files: "\"Инструкция по сборке.docx\""}
  # Следующая директива позволит взять каталог (вместе со своим содержимым) {WORKSPACE}/sources/sm-uko-root/sm-uko/target/conf и положить его в дистрибутив
  - {source: "filesystem", type: "conf", subdir: "sm-uko/target/conf", files: "*", name: "sm-uko-root", copyMainConfig: true}
  # Добавление sdk для архива компонента происходит через nexus, файлы помещаются в репозиторий в package/sdk/mvn/
  - { source: "nexus", type: "sdk_mvn", repoId: "ufs-platform_thirdparty", groupId: "com.github.qwazer", artifactId: "markdown-confluence-gradle-plugin", version: "0.8.999", packaging: "jar" }
  # Добавление sdk для архива бинарных артефактов происходит через filesystem, файлы помещаются в репозиторий в package/sdk/npm/
  - { source: "filesystem", type: "sdk_npm", subdir: ".npm/commander/2.20.3/package.tgz", coordinates: { name: commander, version: 2.20.3 } }

docker:
  # Токен для логина в registry
  #builder_token: "ose_openshift_devopsefs_key"
  builder_token: "token"
  # Ссылка на registry
  #registry_address: "docker-registry-default.apps.test-ose.ca.<host-name>"
  registry_address: "registry.<host-name>"
  # адрес Nexus3 registry
  image_path: "registry_url"
  # массив из дополнительных ссылок на registry, для чтения; используется единый Credential для доступа во все Nexus репозитории, указанный в builder_token
  additional_registries:
    - "registry_address1"
    - "registry_address2"

### Настройки DevSecOps ###
### Общая информация о командах ###
team:
  - {
    # Код команды в МУС.
    # Если не сработает код команды в МУС, то можно попробовать прописать логин ТУЗа, который используется для сканирования
    mus_code: "command_code",
    # название команды в МУС
    mus_name: "command_name",
    # Почтовый адрес Product Owner в МУС для уведомлений с результатами сканирования
    # !!! Почта должна быть валидной для текущего домена, чтобы корректно определить пользователя, которому впоследствии предоставятся права на доступ к АС в SALM !!!
    # !!! Возможно указание нескольких почт через знаки ";" или "," внутри одной строки !!!
    # Пример: "user1@mycompany.ru; user2@mycompany.ru, user3@mycompany.ru"
    mus_po_mail: "user1@mycompany.ru; user2@mycompany.ru, user3@mycompany.ru",
  }
  # Возможно добавление нескольких команд
  # !!! Вторую и последующие команды необходимо добавить по формату, аналогичному первой !!!
  #  - {
  #      mus_code: "00040018",
  #      mus_name: "Web",
  #      mus_po_mail: "sspetrov@mycompany.ru",
  #    }

### Общая информация о приложении ###
app:
  # Конфигурационный элемент (КЭ) приложения / модуля ПО в Service Manager.
  # !!! КЭ должен быть строкой, состоящей исключительно из цифр без лидирующих нулей !!!
  sm_id: "number_id"
  # название КЭ приложения / модуля ПО в Service Manager
  sm_name: "app_name"

### Настройки SAST ###
sast_cx:
  # Credentials ID в Jenkins для учетной записи одной команды, под которой будет проводиться сканирование
  creds_id: "creds"
  # проектная область в JIRA для заведения и синхронизации дефектов
  jira_area: "area"
  # Маски файлов и директорий для включения (**/*) в скан и исключения (!**/*) из скана.
  # Пример: "!**/utils/**/*.xml" - исключение всех xml файлов в папке utils
  masks: ""
  # ID профиля сканирования, по умолчанию 36. 14 - для мобильного приложения. 100003 - Smoke
  preset_id: "36"
  # Максимальное время ожидания статуса QG в минутах
  wait_qg: "2"

### Настройки OSS
oss:
  # Маски файлов и директорий для исключения из сканирования
  # Пример: "**/utils/**/*.xml" - исключение всех xml файлов во всех папках utils
  # !!! Перечисление нескольких масок возможно через знаки "," или ";" внутри одной строки, например, "**/*test*/**; **/*.txt, .git/**" !!!
  # !!! Пропуски в каждой маске справа и слева автоматически удалятся (trim) !!!
  excludes: ""

Параметризация pipeline.yml#

В любой параметр в файле pipeline.yml есть возможность подставить значение переменной из environment.

Допустим, необходимо параметризовать секцию distribution в файле pipeline.yml.

Тогда конфигурация должна выглядеть следующим образом:

distribution:
  - url: "${DISTRIBUTION_URL}"
    serverId: "${DISTRIBUTION_SERVER_ID}"

В Jenkins job сборки дистрибутива необходимо добавить значения для одноименных параметров:

• DISTRIBUTION_URL

• DISTRIBUTION_SERVER_ID

По умолчанию параметризация конфигурации выключена. Для ее использования добавьте в Jenkins job сборки скрипта параметр «PARAMETERIZATION_YML» со значением true.

В случаях, когда необходимо одновременно использовать параметризацию и сохранить плейсхолдеры в файле pipeline.yml, строки следует экранировать. Например:

docker:
  build_args:
    CACHEBUST: "\\$(date +%s)"

Объявление переменных окружения через pipeline.yml#

Для объявления переменных окружения необходимо определить раздел env в pipeline.yml и произвести перечисление определений в формате key: value:

env:
  ENV_KEY_0: env-value-0
  ENV_KEY_1: env-value-1
  ...

Объявленные через pipeline.yml переменные окружения не могут быть использованы для параметризации самого pipeline.yml.

Список переменных окружения (с подробным описанием можно ознакомиться в разделе Параметр type: String Parameter), которые не должны быть объявлены через pipeline.yml:

• IMAGE_CREATOR_BRANCH;

• BASE_BRANCH;

• EXTENSION_BRANCH;

• JENKINS_NODE;

• CONFIG_FILE;

• CONFIG_BRANCH;

• CONFIG_REPO;

• CONFIG_DIR;

• GIT_CREDS;

• GIT_URL;

• PLAYBOOKS.

Настройка Jenkins job#

В данном разделе описаны этапы настройки Jenkins job, которые могут быть использованы. Создание job (с нуля) описано в соответствующем разделе.

Параметр PLAYBOOKS#

Параметр PLAYBOOKS позволяет выбрать, какие именно операции при сборке дистрибутива следует выполнить.

Ниже указаны возможные варианты сценариев (playbooks). Сценарии, отличные от fp-deploy-<...>, run-sast, run-oss, предназначены для целей отладки, т.к. позволяют выполнять сборку отдельных разделов файла pipeline.yml без публикации дистрибутива.

Подробнее о build-:

• Для сборки всех Jenkins-файлов, перечисленных в конфигурационном файле pipeline.yml, необходимо в параметр PLAYBOOKS добавить значение build-jenkinsfiles и выбрать его при запуске Jenkins job.

• Для сборки определенного Jenkins-файла необходимо в параметр PLAYBOOKS добавить и выбрать при запуске значение, равное build-$jenkinsfiles.name из файла pipeline.yml.

Данное поведение доступно, только если выключен сценарий fp-deploy-<...>

Параметр type: String Parameter#

Настройки этого типа могут быть указаны как в параметрах Jenkins job, так и в настройках ее окружения (опция Prepare an environment for the run).

Параметр type: Boolean Parameter#

Данные параметры НЕ могут быть настроены с помощью переменных окружения Jenkins job и должны быть строго ограничены параметрами типа Boolean.

Заполнение конфигурации скриптов развертывания#

Чтобы pipeline мог установить приложения на стенд, также необходимо заполнить конфигурацию скриптов развертывания.

В репозитории конфигурации проекта (рядом с файлом pipeline.yml) необходимо добавить файлы:

• config-was-app.yml;

• distrib.yml;

• locations.conf.j2.