Использование Docker образов

GitLab CI в сочетании с GitLab Runner может использовать Docker Engine для тестирования и сборки любого приложения.

Docker — это открытое программное обеспечение, которое позволяет использовать предопределённые образы для запуска приложений в независимых "контейнерах", которые выполняются внутри одного экземпляра Linux. [Docker Hub][hub] имеет богатую базу данных предварительно построенных образов, которые можно использовать для тестирования и сборки ваших приложений.

Docker, когда используется с GitLab CI, запускает каждую задачу в отдельном и изолированном контейнере, используя предопределённый образ, который настроен в .gitlab-ci.yml.

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

Регистрация Docker Runner

Чтобы использовать GitLab Runner с Docker, вам нужно [зарегистрировать новый Runner][register] для использования docker executor.

Пример одной строки можно увидеть ниже:

sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --description "docker-ruby-2.1" \
  --executor "docker" \
  --docker-image ruby:2.1 \
  --docker-postgres latest \
  --docker-mysql latest
```Зарегистрированный runner будет использовать Docker образ `ruby:2.1` и будет запускать два сервиса, `postgres:latest` и `mysql:latest`, которые будут доступны во время процесса сборки.

## Что такое образ

Ключевое слово `image` — это имя Docker образа, который Docker executor будет использовать для выполнения задач CI.

По умолчанию, executor будет запрашивать образы только с [Docker Hub][hub], но это можно настроить в `gitlab-runner/config.toml` путем установки [Docker pull policy][] для разрешения использования локальных образов.

Для получения дополнительной информации об образах и Docker Hub прочитайте документацию [Docker Fundamentals][].

## Что такое сервис

Ключевое слово `services` определяет еще один Docker образ, который запускается во время вашей задачи и связан с Docker образом, определенным ключевым словом `image`. Это позволяет вам обращаться к образу сервиса во время сборки.

Образ сервиса может запускать любое приложение, но наиболее распространенным сценарием является запуск контейнера базы данных, например, `mysql`. Это проще и быстрее использовать существующий образ и запускать его как дополнительный контейнер, вместо установки `mysql` каждый раз при сборке проекта. Вы не ограничены только базовыми сервисами. Вы можете добавить столько сервисов, сколько вам нужно, в файл `.gitlab-ci.yml` или вручную изменить `config.toml`.

Любой образ, найденный на [Docker Hub][hub] или в вашем личном реестре контейнеров, может быть использован как сервис.Вы можете посмотреть примеры широко используемых сервисов в соответствующей документации
[примеры CI сервисов](../services/README.md).

### Как сервисы связаны с задачей

Чтобы лучше понять, как работает связывание контейнеров, прочитайте
[Связывание контейнеров вместе][linking-containers].

Кратко, если вы добавите `mysql` как сервис к вашему приложению, образ будет использован для создания контейнера, который будет связан с контейнером задачи.

Контейнер сервиса для MySQL будет доступен под именем хоста `mysql`.
Поэтому, чтобы получить доступ к вашему сервису базы данных, вам нужно подключиться к хосту с именем `mysql`, а не к сокету или `localhost`.
Подробнее в [доступе к сервисам](#accessing-the-services).

### Доступ к сервисам

Предположим, что вам нужен образ Wordpress для тестирования интеграции API с вашим приложением.

Вы можете использовать, например, образ [tutum/wordpress][] в вашем файле `.gitlab-ci.yml`:

```yaml
services:
- tutum/wordpress:latest

Если вы не указываете псевдоним сервиса, когда задача выполняется, tutum/wordpress будет запущен, и вы сможете получить доступ к нему из вашего контейнера сборки под двумя именами хоста:

tutum-wordpress
tutum__wordpress

Примечание: Имена хостов с подчеркиваниями не соответствуют стандарту RFC и могут вызвать проблемы в приложениях сторонних разработчиков.По умолчанию псевдонимы для имени хоста сервиса создаются из имени образа, следуя этим правилам:

Все после двоеточия (:) удаляется.
Символ слеша (/) заменяется на двойные подчеркивания (__) и создается основной псевдоним.
Символ слеша (/) заменяется на одинарный дефис (-) и создается дополнительный псевдоним (требуется GitLab Runner версии 1.1.0 или выше).

Чтобы переопределить поведение по умолчанию, вы можете указать псевдоним сервиса.

Определение `image` и `services` в `.gitlab-ci.yml`

Вы можете просто определить образ, который будет использоваться для всех задач, и список сервисов, которые вы хотите использовать во время сборки:

image: ruby:2.2
services:
  - postgres:9.3

before_script:
  - bundle install

test:
  script:
  - bundle exec rake spec

Также можно определить разные изображения и службы для каждого задания:

before_script:
  - bundle install

test:2.1:
  image: ruby:2.1
  services:
  - postgres:9.3
  script:
  - bundle exec rake spec

test:2.2:
  image: ruby:2.2
  services:
  - postgres:9.4
  script:
  - bundle exec rake spec

Или вы можете передать некоторые расширенные конфигурационные опции для image и services:

image:
  name: ruby:2.2
  entrypoint: ["/bin/bash"]

services:
- name: my-postgres:9.4
  alias: db-postgres
  entrypoint: ["/usr/local/bin/db-postgres"]
  command: ["start"]

before_script:
- bundle install

test:
  script:
  - bundle exec rake spec

Расширенные опции конфигурации Docker

Примечание: Эта функция требует GitLab 9.4 и GitLab Runner 9.4 или выше.При настройке image или services можно использовать строку или карту как опции:

при использовании строки как опции, она должна быть полным именем изображения для использования (включая часть реестра, если вы хотите скачать изображение из реестра, отличного от Docker Hub)
при использовании карты как опции, она должна содержать по крайней мере опцию name, которая является тем же именем изображения, что и используется для строки

Например, следующие два определения равнозначны:

Использование строки как опции для image и services:

image: "registry.example.com/my/image:latest"

services:
- postgresql:9.4
- redis:latest

Использование карты как опции для image и services. Использование image:name обязательно:
```
image:
  name: "registry.example.com/my/image:latest"

services:
- name: postgresql:9.4
- name: redis:latest
```

Доступные параметры для `image`> Примечание:

Эта функция требует GitLab 9.4 и GitLab Runner 9.4 или выше.| Настройка | Обязательная | Описание | |------------|-------------|----------| | name | да, если используется вместе с любым другим параметром | Полное имя изображения, которое должно быть использовано. Оно должно содержать часть реестра, если это необходимо. | | entrypoint | нет | Команда или скрипт, которые должны быть выполнены как точка входа контейнера. Она будет переведена в опцию Docker --entrypoint при создании контейнера. Синтаксис аналогичен директиве [Dockerfile's ENTRYPOINT][entrypoint], где каждый токен оболочки является отдельной строкой в массиве. |### Доступные параметры для services> Примечание: Эта функция требует GitLab 9.4 и GitLab Runner 9.4 или более поздних версий.

Параметр	Обязательный	Описание
`name`	да, когда используется вместе с любым другим параметром	Полное имя образа, который должен быть использован. Должно содержать часть реестра, если это необходимо.
`entrypoint`	нет	Команда или скрипт, который должен быть выполнен как точка входа контейнера. Будет переведен в опцию `--entrypoint` Docker при создании контейнера. Синтаксис аналогичен [указанию `ENTRYPOINT` в `Dockerfile`][entrypoint], где каждый токен командной строки является отдельной строкой в массиве.
`command`	нет	Команда или скрипт, который должен быть использован как команда контейнера. Будет переведен в аргументы, передаваемые Docker после имени образа. Синтаксис аналогичен [указанию `CMD` в `Dockerfile`][cmd], где каждый токен командной строки является отдельной строкой в массиве.
`alias`	нет	Дополнительный псевдоним, который можно использовать для доступа к сервису из контейнера задания. См. Доступ к сервисам для получения дополнительной информации.

Запуск нескольких сервисов из одного образа

До новых расширенных опций конфигурации Docker следующая конфигурация не работала корректно:

services:
- mysql:latest
- mysql:latest
```Runner запускал бы два контейнера с использованием образа `mysql:latest`, но оба
были бы добавлены в контейнер задания с псевдонимом `mysql` на основе
[по умолчанию именования хоста](#accessing-the-services). Это привело бы к тому, что один из сервисов не будет доступен.

После новых расширенных опций конфигурации Docker, вышеупомянутый пример выглядел бы следующим образом:

```yaml
services:
- name: mysql:latest
  alias: mysql-1
- name: mysql:latest
  alias: mysql-2

Runner все еще запускает два контейнера с использованием образа mysql:latest, но теперь каждый из них также будет доступен с псевдонимом, настроенным в файле .gitlab-ci.yml.

Установка команды для сервиса

Предположим, что у вас есть образ super/sql:latest с некоторой базой данных SQL внутри него, и вы хотите использовать его как сервис для вашего задания. Предположим также, что этот образ не запускает процесс базы данных при запуске контейнера, и пользователь должен вручную использовать /usr/bin/super-sql run как команду для запуска базы данных. До новых расширенных опций конфигурации Docker вам нужно было создать собственное изображение на основе изображения super/sql:latest, добавить стандартную команду и затем использовать его в конфигурации задания, например:

# Dockerfile изображения my-super-sql:latest

FROM super/sql:latest
CMD ["/usr/bin/super-sql", "run"]

# .gitlab-ci.yml

services:
- my-super-sql:latest
```После новых расширенных опций конфигурации Docker вы теперь можете просто установить `command` в `.gitlab-ci.yml`, например:

```yaml
# .gitlab-ci.yml

services:
- name: super/sql:latest
  command: ["/usr/bin/super-sql", "run"]

Как можно заметить, синтаксис command похож на [синтаксис CMD в Dockerfile][cmd].

Переопределение точки входа изображения

Предположим, что у вас есть изображение super/sql:experimental с некоторой SQL-базой данных внутри и вы хотите использовать его как базовое изображение для вашего задания, так как вы хотите выполнить некоторые тесты с этим бинарным файлом базы данных. Предположим также, что это изображение настроено с точкой входа /usr/bin/super-sql run. Это означает, что при запуске контейнера без дополнительных опций будет запущен процесс базы данных, в то время как Runner ожидает, что изображение не имеет точки входа или по крайней мере запускается с помощью оболочки.

Ранее вам нужно было создать собственное изображение на основе изображения super/sql:experimental, установить точку входа на оболочку и затем использовать его в конфигурации задания, например:

До новых расширенных опций конфигурации Docker вам нужно было создать собственное изображение на основе изображения super/sql:experimental, установить точку входа на оболочку и затем использовать его в конфигурации задания, например:```Dockerfile

Dockerfile изображения my-super-sql:experimental

FROM super/sql:experimental ENTRYPOINT ["/bin/sh"]


```yaml
# .gitlab-ci.yml

image: my-super-sql:experimental

После новых расширенных опций конфигурации Docker вы теперь можете просто установить entrypoint в .gitlab-ci.yml, например:

# .gitlab-ci.yml

image:
  name: super/sql:experimental
  entrypoint: ["/bin/sh"]

Как можно заметить, синтаксис entrypoint похож на [синтаксис ENTRYPOINT в Dockerfile][entrypoint].

Определение изображения и служб в `config.toml`

Найдите раздел [runners.docker]:

[runners.docker]
  image = "ruby:2.1"
  services = ["mysql:latest", "postgres:latest"]

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

Определение изображения из приватного Container Registry

Примечания:

Эта функция требует GitLab Runner 1.8 или выше
Для версий GitLab Runner >= 0.6, <1.8 частичная поддержка использования приватных регистров была доступна, что требовало ручной настройки учетных данных на хосте запускателя. Мы рекомендуем обновить ваш запускатель до версии 1.8 или выше, если вы хотите использовать приватные регистры.
Если репозиторий приватный, вам нужно аутентифицировать ваш GitLab Runner в регистре. Узнайте больше о том, как [GitLab Runner работает в этом случае][runner-priv-reg]. ```В качестве примера предположим, что вы хотите использовать изображение registry.example.com/private/image:latest, которое является приватным и требует входа в приватный контейнерный регистр. Чтобы настроить доступ к `registry.example.com`, выполните следующие шаги:1. Выполните `docker login` на вашем компьютере:
```
docker login registry.example.com --username my_username --password my_password
```

Скопируйте содержимое файла ~/.docker/config.json
Создайте [секретную переменную] DOCKER_AUTH_CONFIG с содержимым файла конфигурации Docker в качестве значения:
```
{
    "auths": {
        "registry.example.com": {
            "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
        }
    }
}
```
Выполните docker logout на вашем компьютере, если вам не требуется доступ к регистру с него:
```
docker logout registry.example.com
```
Вы можете теперь использовать любое приватное изображение из registry.example.com, определенное в image и/или services в вашем файле [.gitlab-ci.yml][yaml-priv-reg]:
```
image: my.registry.tld:5000/namespace/image:tag
```
В приведенном выше примере GitLab Runner будет искать изображение namespace/image:tag в my.registry.tld:5000.

Вы можете добавить конфигурацию для любого количества регистров, добавляя больше регистров в хэш "auths" как описано выше.

Настройка служб

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

GitLab Runner 0.5.0 и выше передает все YAML-определенные переменные в созданные контейнеры служб. Для всех возможных конфигурационных переменных проверьте документацию каждого образа, предоставленную на соответствующей странице Docker Hub.Примечание: Все переменные будут переданы во все контейнеры сервисов. Это не предназначено для различения, какие переменные должны быть где.

Пример сервиса PostgreSQL

См. специфическую документацию для использования PostgreSQL как сервиса здесь.

Пример сервиса MySQL

См. специфическую документацию для использования MySQL как сервиса здесь.

Как работает интеграция с Docker

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

Создание контейнеров сервисов: mysql, postgresql, mongodb, redis.
Создание кеш-контейнера для хранения всех томов, как определено в config.toml и Dockerfile образа сборки (ruby:2.1 в приведенном выше примере).
Создание контейнера сборки и связывание всех контейнеров сервисов с контейнером сборки.
Запуск контейнера сборки и отправка скрипта задачи в контейнер.
Выполнение скрипта задачи.
Получение кода из: /builds/имя-группы/имя-проекта/.
Выполнение любого шага, определенного в .gitlab-ci.yml.
Проверка статуса завершения скрипта сборки.
Удаление контейнера сборки и всех созданных контейнеров сервисов.

Как отладить задачу локально

*Примечание: Следующие команды выполняются без привилегий root. Вы должны иметь возможность запускать Docker с вашего обычного пользователя.*Сначала создайте файл с именем build_script:

cat <<EOF > build_script
git clone https://gitlab.com/gitlab-org/gitlab-ci-multi-runner.git /builds/gitlab-org/gitlab-ci-multi-runner
cd /builds/gitlab-org/gitlab-ci-multi-runner
make
EOF

В этом примере используется репозиторий GitLab Runner, который содержит Makefile, поэтому выполнение make выполнит команды, определенные в Makefile. Ваш результат может отличаться, поэтому вместо make вы можете выполнить команду, специфичную для вашего проекта.

Затем создайте некоторые контейнеры сервисов:

docker run -d --name service-mysql mysql:latest
docker run -d --name service-postgres postgres:latest

Это создаст два контейнера сервисов, названных service-mysql и service-postgres, которые используют последние образы MySQL и PostgreSQL соответственно. Они будут запущены в фоновом режиме (-d).

Наконец, создайте контейнер сборки, выполнив файл build_script, который мы создали ранее:

docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.1 /bin/bash < build_script

Вышеуказанный командный запрос создает контейнер с именем build, который основан на образе ruby:2.1 и имеет две привязанные к нему службы. Скрипт build_script передается через стандартный ввод (STDIN) интерпретатору Bash, который в свою очередь выполняет build_script в контейнере build.

После завершения тестирования и если больше не требуется использование контейнеров, их можно удалить следующей командой:

docker rm -f -v build service-mysql service-postgres
```Эта команда удаляет контейнер `build` и два служебных контейнера, а также все созданные с ними тома (`-v`) с использованием силы (`-f`).

[Docker Fundamentals]: https://docs.docker.com/engine/understanding-docker/
[docker pull policy]: https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work
[hub]: https://hub.docker.com/
[linking-containers]: https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/
[tutum/wordpress]: https://hub.docker.com/r/tutum/wordpress/
[postgres-hub]: https://hub.docker.com/r/_/postgres/
[mysql-hub]: https://hub.docker.com/r/_/mysql/
[runner-priv-reg]: http://docs.gitlab.com/runner/configuration/advanced-configuration.html#using-a-private-container-registry
[secret variable]: ../variables/README.md#secret-variables
[entrypoint]: https://docs.docker.com/engine/reference/builder/#entrypoint
[cmd]: https://docs.docker.com/engine/reference/builder/#cmd
[register]: https://docs.gitlab.com/runner/register/

OSCHINA-MIRROR/panda26-gitlab

Использование Docker образов

Регистрация Docker Runner

Определение `image` и `services` в `.gitlab-ci.yml`

Расширенные опции конфигурации Docker

Доступные параметры для `image`> Примечание:

Запуск нескольких сервисов из одного образа

Установка команды для сервиса

Переопределение точки входа изображения

Dockerfile изображения my-super-sql:experimental

Определение изображения и служб в `config.toml`

Определение изображения из приватного Container Registry

Настройка служб

Пример сервиса PostgreSQL

Пример сервиса MySQL

Как работает интеграция с Docker

Как отладить задачу локально

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/panda26-gitlab .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Использование Docker образов

Регистрация Docker Runner

Определение image и services в .gitlab-ci.yml

Расширенные опции конфигурации Docker

Доступные параметры для image> Примечание:

Запуск нескольких сервисов из одного образа

Установка команды для сервиса

Переопределение точки входа изображения

Dockerfile изображения my-super-sql:experimental

Определение изображения и служб в config.toml

Определение изображения из приватного Container Registry

Настройка служб

Пример сервиса PostgreSQL

Пример сервиса MySQL

Как работает интеграция с Docker

Как отладить задачу локально

Опубликовать ( 0 )

Введение

Обновления

Участники

Язык

Недавние действия

OSCHINA-MIRROR/panda26-gitlab

Определение `image` и `services` в `.gitlab-ci.yml`

Доступные параметры для `image`> Примечание:

Определение изображения и служб в `config.toml`