207 lines
11 KiB
Markdown
207 lines
11 KiB
Markdown
Проект содержит скрипты которые обеспечивают сборку контейнера 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
|
|
Доступно два варианта использования:
|
|
а) Использование фиксированной версии сборщика
|
|
б) Использование последней доступной версии
|
|
|
|
Для настройки необходимо:
|
|
1) Однократно выполнить в проекте команду
|
|
|
|
`git submodule add -b master ../../infra/ci-build-image.git ci/build-image`
|
|
|
|
2) В корне проекта разместить `Dockerfile` вида:
|
|
```
|
|
ARG DOCKER_BASEIMAGE
|
|
FROM ${DOCKER_BASEIMAGE}
|
|
|
|
ARG DOCKER_MAINTAINER
|
|
LABEL maintainer="${DOCKER_MAINTAINER}"
|
|
|
|
# Uncomment if you use assets/
|
|
#COPY assets/ /
|
|
```
|
|
3) а) Для использования фиксированной версии в `.gitlab-ci.yml` проекта прописать переменную `GIT_SUBMODULE_STRATEGY=recursive`
|
|
б) Для использования последней доступной версии в `.gitlab-ci.yml` проекта прописать переменную `GIT_SUBMODULE_STRATEGY=none`
|
|
|
|
4) Осуществить вызов сборки в `.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
|
|
```
|
|
|
|
5) Обновление submodule осуществляется командой:
|
|
|
|
`git submodule sync && git submodule update --init --remote`
|
|
|
|
##### Клонирование скриптов при сборке проекта
|
|
|
|
1) В корне проекта разместить `Dockerfile` вида:
|
|
```
|
|
ARG DOCKER_BASEIMAGE
|
|
FROM ${DOCKER_BASEIMAGE}
|
|
|
|
ARG DOCKER_MAINTAINER
|
|
LABEL maintainer="${DOCKER_MAINTAINER}"
|
|
|
|
# Uncomment if you use assets/
|
|
#COPY assets/ /
|
|
```
|
|
|
|
2) Осуществить вызов сборки в `.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` |