2GIS CLI (dgCtl)
Утилита 2GIS CLI (также известна как dgCtl
) предназначена для загрузки и обновления артефактов, которые необходимы для развёртывания и обновления сервисов On-Premise.
Подробнее об организации процессов обновления и управления данными см. в обзорном разделе.
Архитектура
Утилита позволяет получать артефакты развёртывания из различных источников. В зависимости от наличия доступа в интернет доступные источники данных и режим работы будут различаться.
Полученные артефакты размещаются в хранилище выбранного типа и (при необходимости) в реестре Docker (Docker registry). Поддерживаются два типа хранилища:
- S3-совместимое хранилище;
- файловая система.

2GIS CLI позволяет контролировать порядок размещения полученных артефактов. Допустим один из вариантов:
-
Разместить данные для сервисов и прочие вспомогательные артефакты в хранилище выбранного типа, а Docker-образы сервисов - в реестре Docker (registry).
Для этого нужно запустить 2GIS CLI с аргументом
--apps-to-registry
.Примечание:
Рекомендуется использовать этот вариант, так как он дает больше контроля над размещением артефактов, позволяя избежать их смешения.
-
Разместить все артефакты в хранилище выбранного типа (без использования реестра Docker).
Режимы работы
При наличии доступа в интернет

При наличии доступа в интернет 2GIS CLI может работать в режиме pull
: утилита выполнит загрузку актуальных артефактов развёртывания с серверов обновления 2GIS в выбранное хранилище и (при необходимости) в реестр Docker.
Без доступа в интернет

Без доступа в интернет 2GIS CLI может работать в режиме restore
(«восстановление») : утилита выполнит загрузку артефактов развёртывания, которые уже хранятся в файловой системе-источнике, в выбранное хранилище и (при необходимости) в реестр Docker.
Важное примечание:
Артефакты должны быть предварительно загружены в файловую систему-источник с помощью режима pull.
Требования
-
Ключ доступа для 2GIS CLI, который позволяет получать артефакты развёртывания, связанные с приобретёнными продуктами 2GIS.
Чтобы получить этот ключ, заполните форму на dev.2gis.ru/order.
-
Общая инфраструктура:
- Реестр Docker (registry) для хранения Docker-образов.
- В зависимости от выбранного типа хранилища:
- S3-совместимое хранилище артефактов развёртывания.
- Свободное место на файловой системе.
- При выбранном режиме работы
pull
: доступ в интернет для 2GIS CLI (до серверов обновления 2GIS).
Детальные требования для каждого сервиса описаны в обзорном разделе. Дополнительную информацию можно найти в разделе Что нужно учесть перед развертыванием.
Структура конфигурационного файла
Конфигурационный файл имеет следующую структуру:
key: <2GIS CLI access key>
log-format: <Log format: <text | json>
storage:
type: <s3 | fs>
# S3 storage settings
host: <Deployment Artifacts Storage hostname and port>
bucket: <Deployment Artifacts Storage bucket name>
access-key: <Deployment Artifacts Storage access key>
secret-key: <Deployment Artifacts Storage secret key>
# FS (filesystem) storage settings
directory: <target directory on a filesystem>
docker:
registry:
username: <Docker Registry username>
password: <Docker Registry password>
server-address: <Docker Registry URL>
image-prefix: <Additional prefix (optional)>
Где:
-
key
: ключ доступа для 2GIS CLI. -
log-format
: формат логов -text
илиjson
. Все логи выводятся в стандартный поток вывода (stdout
). -
storage
: настройки для используемого типа хранилища.-
Для S3-совместимого хранилища:
type
: тип хранилища. Значение должно бытьs3
.host
: FQDN эндпоинта S3-совместимого хранилища.bucket
: имя бакета для хранения артефактов развёртывания.access-key
: идентификатор ключа (S3 access key).secret-key
: секретный ключ (S3 secret key).
-
Для хранилища на файловой системе:
type
: тип хранилища. Значение должно бытьfs
.directory
: целевая директория в файловой системе, куда будут загружаться артефакты развёртывания. Директория должна существовать и быть примонтированной к Docker-контейнеру (см. Запуск утилиты).
Важное примечание:
В одном конфигурационном файле могут присутствовать настройки только для одного типа хранилища. Если требуется запускать 2GIS CLI для разных типов хранилища - создайте для каждого из них отдельные конфигурационные файлы.
-
-
docker.registry
: настройки для доступа к реестру Docker.-
username
: имя пользователя. -
password
: пароль. -
server-address
: URL реестра. -
image-prefix
: дополнительный префикс, под которым будут храниться образы On-Premise.Хотя эта настройка не является обязательной, в документации сервисов On-Premise предполагается, что задан дополнительный префикс
2gis-on-premise
.
Примечание:
Если выбранный сценарий использования 2GIS CLI не предполагает использование реестра, то эту секцию настроек конфигурационного файла можно опустить.
-
Запуск утилиты
Для запуска 2GIS CLI нужно выполнить следующую команду:
docker run --rm -v <path to YAML config file>:/config.yaml -v /var/run/docker.sock:/var/run/docker.sock -v /mnt/source-dgctl:/source-dgctl 2gis/dgctl:latest <command to execute> --config=/config.yaml <additional arguments>
Где:
-
<path to YAML config file>
- путь до конфигурационного файла. -
-v /var/run/docker.sock:/var/run/docker.sock
- передача сокета Docker внутрь Docker-контейнера.Этот аргумент используется совместно с аргументом
--apps-to-registry
. Если вы не планируете использовать реестр Docker, аргумент с настройками сокета можно опустить. -
-v /mnt/source-dgctl:/source-dgctl
- монтирование директории для хранения артефактов развёртывания.Для режима
pull
, если вы используете тип хранилищаfs
, укажите директорию из параметраstorage.directory
конфигурационного файла.Для режима
restore
укажите директорию из аргумента--from-dir
.В остальных случаях этот аргумент можно опустить.
-
<command to execute>
- одна из команд, определяющих режим работы:-
pull
- применяется при наличии доступа в интернет. Позволяет загрузить актуальные артефакты развёртывания с серверов обновления 2GIS. -
restore
- применяется при отсутствии доступа в интернет. Позволяет восстановить артефакты развёртывания, которые хранятся в файловой системе.
-
-
<additional arguments>
- дополнительные аргументы запуска:-
--apps-to-registry
- если аргумент указан, Docker-образы будут помещены в реестр Docker, а не в хранилище.Рекомендуется всегда указывать этот аргумент, так как иначе все Docker-образы будут помещены в хранилище вместе с прочими артефактами. Подробнее см. в секции Архитектура.
Этот аргумент используется совместно с аргументом
-v /var/run/docker.sock:/var/run/docker.sock
. -
--workers
- число параллельных рабочих потоков, которые выполняют загрузку данных (по умолчанию 3, максимум 8). -
--attempt
- количество попыток восстановления артефактов в случае возникновения ошибок при записи. По умолчанию3
. -
--overwrite
- если аргумент указан, существующие файлы в S3-хранилище и реестре Docker будут перезаписаны. -
--version
(только в режимеpull
) - версия сервисов On-Premise, которую требуется скачать (например,--version=1.0.0
). См. раздел Релизы для списка доступных версий. -
--from-dir
(только в режимеrestore
) - директория файловой системы, из которой следует восстановить артефакты развёртывания.Директория должна быть доступна из Docker-контейнера. Для этого её нужно примонтировать (см. использование аргумента
-v
для Docker выше).Директория должна содержать файл манифеста (
manifests/latest.json
), который описывает структуру папок сервисов. Наиболее простой способ создать манифест и корректную структуру папок - запустить 2GIS CLI в режиме pull, указав файловую систему в качестве хранилища. -
--dry-run
(только в режимеrestore
) - если аргумент указан, шаг загрузки артефактов в хранилище будет пропущен. 2GIS CLI только сформирует список файлов для загрузки и выведет его в стандартный поток вывода.Настоятельно рекомендуется запускать 2GIS CLI с этим аргументом каждый раз перед восстановлением артефактов развёртывания, чтобы отследить планируемые изменения.
-
Примеры использования
При наличии доступа в интернет: загрузка артефактов развёртывания (pull)
-
Создайте один из вариантов конфигурационного файла
config.yaml
с настройками для требуемого типа хранилища:Для загрузки артефактов в S3-хранилище:
# Ключ доступа для 2GIS CLI. key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB # Формат логов. log-format: json storage: type: s3 # FQDN эндпоинта S3-совместимого хранилища. host: artifacts.storage.local # Имя бакета для хранения артефактов развёртывания. bucket: dgctl-store # Идентификатор ключа (S3 access key). access-key: AKIAIOSFODNN7EXAMPLE # Секретный ключ (S3 secret key). secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY docker: registry: # Имя пользователя для реестра Docker. username: registry-user # Пароль для реестра Docker. password: DOCKERregistryP@ssW0rd # URL реестра Docker. server-address: http://docker.registry.local:5000 # Дополнительный префикс, под которым будут храниться образы в реестре Docker. image-prefix: /2gis-on-premise
Для загрузки артефактов в файловую систему:
# Ключ доступа для 2GIS CLI. key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB # Формат логов. log-format: json storage: type: fs # Целевая директория в файловой системе, куда будут загружаться артефакты развёртывания. directory: /source-dgctl docker: registry: # Имя пользователя для реестра Docker. username: registry-user # Пароль для реестра Docker. password: DOCKERregistryP@ssW0rd # URL реестра Docker. server-address: http://docker.registry.local:5000 # Дополнительный префикс, под которым будут храниться образы в реестре Docker. image-prefix: /2gis-on-premise
-
Запустите одну из следующих команд:
Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm -v $(pwd)/config.yaml:/config.yaml -v /mnt/source-dgctl:/source-dgctl -v /var/run/docker.sock:/var/run/docker.sock 2gis/dgctl:latest pull --config=/config.yaml --version=1.0.3 --apps-to-registry
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm -v $(pwd)/config.yaml:/config.yaml -v /mnt/source-dgctl:/source-dgctl 2gis/dgctl:latest pull --config=/config.yaml --version=1.0.3
Без доступа в интернет: восстановление артефактов развёртывания (restore)
Если артефакты развёртывания уже были загружены в файловую систему, их можно скопировать в другое хранилище и (при необходимости) в реестр Docker.
-
Создайте конфигурационный файл
config.yaml
для того типа хранилища, в которое нужно восстановить артефакты (см. шаг 1 в предыдущем подразделе). Ключ доступа для 2GIS CLI в этом случае можно не указывать. -
Запустите одну из следующих команд, указав директорию, в которой находятся загруженные артефакты (например,
/mnt/source-dgctl
):Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm -v $(pwd)/config.yaml:/config.yaml -v /mnt/source-dgctl:/source-dgctl -v /var/run/docker.sock:/var/run/docker.sock 2gis/dgctl:latest restore --config=/config.yaml --from-dir=/source-dgctl --apps-to-registry
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm -v $(pwd)/config.yaml:/config.yaml -v /mnt/source-dgctl:/source-dgctl 2gis/dgctl:latest restore --config=/config.yaml --from-dir=/source-dgctl