2GIS CLI (dgCtl)

Утилита 2GIS CLI (также известна как dgCtl) предназначена для загрузки и обновления артефактов, которые необходимы для развёртывания и обновления сервисов On-Premise.

Подробнее об организации процессов обновления и управления данными см. в обзорном разделе.

Архитектура

Утилита позволяет получать артефакты развёртывания из различных источников. В зависимости от наличия доступа в интернет доступные источники данных и режим работы будут различаться.

Полученные артефакты размещаются в хранилище выбранного типа и (при необходимости) в реестре Docker (Docker registry). Поддерживаются два типа хранилища:

S3-совместимое хранилище;
файловая система.

dgctl apps to registry argument behavior

2GIS CLI позволяет контролировать порядок размещения полученных артефактов. Допустим один из вариантов:

Разместить данные для сервисов и прочие вспомогательные артефакты в хранилище выбранного типа, а Docker-образы сервисов - в реестре Docker (registry).

Для этого нужно запустить 2GIS CLI с аргументом --apps-to-registry.

Примечание:

Рекомендуется использовать этот вариант, так как он дает больше контроля над размещением артефактов, позволяя избежать их смешения.
Разместить все артефакты в хранилище выбранного типа (без использования реестра Docker).

Режимы работы

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

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

При использовании файловой системы в качестве хранилища (настройка type: fs) утилита 2GIS CLI также создаёт файл манифеста manifests/latest.json, содержащий информацию обо всех сервисах On-Premise. Файл манифеста можно использовать при последующих запусках 2GIS CLI в режиме restore с аргументом --from-dir или --by-manifest.

Если в режиме pull передан аргумент --service, то утилита загрузит артефакты развёртывания только для указанного сервиса. Обратите внимание, что даже при использовании этого аргумента информация в файле манифеста будет обновлена для всех сервисов On-Premise.

Без доступа в интернет

Без доступа в интернет 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: <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 CLI, имеют предустановленный префикс 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 будут перезаписаны.
- --only-apps — скачать/восстановить только образы сервисов, но не данные для них.
- --only-data — скачать/восстановить только данные для сервисов, но не их образы.
- --service=<сервис> — скачать/восстановить артефакты только для указанного сервиса.
  
  Этот аргумент может использоваться вместе с --only-apps или --only-data, чтобы загрузить только образы или только данные для выбранного сервиса.
- --version=<версия> (только в режиме pull) - версия сервисов On-Premise, которую требуется скачать (например, --version=1.0.0). См. раздел Релизы для списка доступных версий.
- --by-manifest=<путь> (только в режиме pull) - путь к файлу манифеста, с помощью которого следует скачать артефакты развёртывания.
  
  Файл манифеста и директория с артефактами, на которые он указывает, должны быть доступны из Docker-контейнера. Для этого директорию нужно примонтировать (см. использование аргумента -v для Docker выше).
  
  Наиболее простой способ создать манифест и корректную структуру папок - запустить 2GIS CLI в режиме pull, указав файловую систему в качестве хранилища.
- --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 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: /

Запустите одну из следующих команд:

Чтобы загрузить 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
```