add ci

2020-07-17 14:15:01 +07:00
parent 6fd349b776
commit 20c0baa3b5
13 changed files with 422 additions and 1 deletions
@@ -0,0 +1,207 @@
+Проект содержит скрипты которые обеспечивают сборку контейнера 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`