backup-2/ci/build-image/README.md at 20c0baa3b5af3450f6ac6d2490537c85cb9219a4

pub/backup-2

Fork 0

Files

T

Vassiliy Yegorov 20c0baa3b5 add ci

2020-07-17 14:15:01 +07:00

11 KiB

Raw Blame History

Проект содержит скрипты которые обеспечивают сборку контейнера docker и загрузку его в docker registry.

Состав:

build.sh - скрипт сборки образа
import.sh - скрипт загрузки образа в docker registry
.env - конфигурационный файл для запуска сборки в ручном режиме

Сборка контейнера

Контейнер собирается с использованием Dockerfile либо файла, определяемого переменной DOCKER_FILE, из корня проекта. При этом в него передаются параметры:
- Контекст сборки может быть определен переменной DOCKER_BUILD_CONTEXT, по умолчанию .
- Для успешной сборки образа, контейнер, в котором происходит сборка (директива image: в .gitlab-ci.yml файле) должен иметь установленный bash и git. Для этих целей можно использовать образ docker.ds.mlmsoft.cloud/images/docker.
- Имя базового образа, определяется переменной DOCKER_BASEIMAGE (по умолчанию используется ubuntu:18.04)
- Установка переменной DOCKER_NO_PULL_BASEIMAGE в непустое значение позволяет не осуществлять принудительный docker pull базового образа
- Префикс собираемого локально образа задается переменной DOCKER_IMAGE_PREFIX
  (по умолчанию mlmsoft)
- Версия базового образа определяется (в порядке приоритета) либо переменной VERSION, либо содержимым файла VERSION из корня проекта, если файл отсутствует, берется версия latest
- Maintainer контейнера определяется переменной DOCKER_MAINTAINER (по умолчанию указывается email пользователя в gitlab или service@ds.mlmsoft.cloud при локальном запуске, если иное не указано в Dockerfile)
- Имя собираемого образа оперделяется переменной DOCKER_IMAGE_NAME. По умолчанию используется короткое имя проекта в Gitlab (${CI_PROJECT_PATH#*/})
- Тег собираемого образа определяется переменной DOCKER_IMAGE_TAG. При отсутствии переменной берется переменная ${VERSION} и тд
- Для передачи произвольных аргументов в Dockerfile можно использовать набор переменных DOCKER_ARG0...DOCKER_ARG9 (соблюдение нумерации не обязательно), в секции before_script: .gitlab-ci.yml:
  
  export DOCKER_ARG1="VERSION=1.0.0"
  
  Переменная VERSION будет доступна в Dockerfile через конструкцию ARG VERSION
  
  Альтернативно можно передевать аргументы в сборку как параметры сборочного скрипта в формате ARG=value.
Контейнер выкладывается в docker registry docker.ds.mlmsoft.cloud, полный путь к контейнеру:

docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}:${VERSION} если имя образа совпадает с именем проекта, либо
docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}/${IMAGE_NAME}:${VERSION} если имя образа отлично от имени проекта

где:
- ${CI_PROJECT_NAME} полный путь проекта вида <группа>/имя проекта> или <пользователь>/имя проекта>
- ${VERSION} это версия образа или latest в случае ее отсутствия.

Версионность образа

Правила формирования версии образа:

Версия образа берется из файла VERSION, который должен располагаться в корне проекта
В случае отсутствия файла, берется версия :latest

Правила определения версии базового образа (DOCKER_BASEIMAGE):

Если в DOCKER_BASEIMAGE есть тег образа, в качестве DOCKER_BASEIMAGE берется значение переменной ${DOCKER_BASEIMAGE} без изменений
Если в DOCKER_BASEIMAGE отсутствует тег образа, то берется ${DOCKER_BASEIMAGE}:${VERSION}

Правила определения версии итогового образа:

Образ тегируется как ${IMAGE}:${VERSION}
В случае импорта в регистри, образ тегируется как docker.ds.mlmsoft.cloud/${CI_PROJECT_NAME}:${VERSION}
В случае, если сборка происходит не из ветки master, образ принудительно тегируется по имени ветки, из которой производится сборка.
Если происходит сборка не из ветки master и переменная DOCKER_IMAGE_TAG не пустая, то образ тегируется как $DOCKER_IMAGE_TAG_$BRANCH.
Даннове поведение можно отменить установив переменную DOCKER_NO_BRANCH_TAG в непустое значение.

Дополнительно возможно указать переменную DOCKER_TAG_AS_LATEST, которая отвечает за дополнительное тегирование образа тегом latest в регистри.

Подключение скриптов к проекту

Проект предполагает использование через механизм gitlab submodules или клонирование скриптов при сборке проекта. Примеры файлов и команды находятся в каталоге example/.

Подключение через механизм git submodules

Доступно два варианта использования:
а) Использование фиксированной версии сборщика
б) Использование последней доступной версии

Для настройки необходимо:

Однократно выполнить в проекте команду

git submodule add -b master ../../infra/ci-build-image.git ci/build-image

В корне проекта разместить Dockerfile вида:

ARG DOCKER_BASEIMAGE
FROM ${DOCKER_BASEIMAGE}

ARG DOCKER_MAINTAINER
LABEL maintainer="${DOCKER_MAINTAINER}"

# Uncomment if you use assets/
#COPY assets/ /

а) Для использования фиксированной версии в .gitlab-ci.yml проекта прописать переменную GIT_SUBMODULE_STRATEGY=recursive
б) Для использования последней доступной версии в .gitlab-ci.yml проекта прописать переменную GIT_SUBMODULE_STRATEGY=none
Осуществить вызов сборки в .gitlab-ci.yml:
а) Вариант фиксированной версии:

image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh
  GIT_SUBMODULE_STRATEGY: recursive

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual

б) Вариант последней доступной версии:

image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh
  GIT_SUBMODULE_STRATEGY: none

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - git submodule sync
    - git submodule update --init --remote --force
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual

Обновление submodule осуществляется командой:

git submodule sync && git submodule update --init --remote

Клонирование скриптов при сборке проекта

В корне проекта разместить Dockerfile вида:

ARG DOCKER_BASEIMAGE
FROM ${DOCKER_BASEIMAGE}

ARG DOCKER_MAINTAINER
LABEL maintainer="${DOCKER_MAINTAINER}"

# Uncomment if you use assets/
#COPY assets/ /

Осуществить вызов сборки в .gitlab-ci.yml:

image: docker.ds.mlmsoft.cloud/images/docker

variables:
  DOCKER_BASEIMAGE: ubuntu:18.04
#  DOCKER_IMAGE_NAME: ${CI_PROJECT_PATH#*/}
#  DOCKER_IMAGE_TAG: latest 
  BUILD_SCRIPT: ci/build-image/build.sh

#before_script:
#  - export DOCKER_ARG0="key=value" 
#  - export DOCKER_ARG1="key=value"
  
stages:
  - build

build:
  stage: build
  script:
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.ds.mlmsoft.cloud/infra/ci-build-image.git ${BUILD_SCRIPT%/*}
    - chmod +x "${BUILD_SCRIPT}" && "./${BUILD_SCRIPT}"
  when: manual

Ручной запуск

Возможен запуск сборки на локальной машине и выкладывание его в docker registry без внесения изменений в проект. Для этого рядом со сборочными скриптами в /ci/build-images должен находиться конфиг с именем .env (пример конфига см. в файле sample.env):

# Your project target image name and tag
DOCKER_IMAGE_NAME=image
DOCKER_IMAGE_TAG=latest

# Base image name and tag
DOCKER_BASEIMAGE=ubuntu:18.04

# Docker build context (leave it as is if not know that it is)
DOCKER_BUILD_CONTEXT=.
DOCKER_PROJECT=external/project
CI_COMMIT_REF_SLUG=master

# Registry credentials (need only if docker registry upload required)
REGISTRY_USER=%YOUR_GITLAB_USERNAME%
REGISTRY_PASSWORD=%YOUR_GITLAB_PASSWORD%
REGISTRY_URL=docker.ds.mlmsoft.cloud

Запуск сборки из каталога проекта: ./ci/build-image/build.sh

При ручном запуске автоматическая загрузка в docker registry не происходит, необходимо использовать скрипт import.sh:

DOCKER_IMAGE=image ./import.sh

11 KiB Raw Blame History