Обзор утилиты | On-Premise | 2GIS Documentation
On-Premise
Карты
Поиск
Навигация
On-Premise
2ГИС Про
ру
en

2GIS CLI

Утилита 2GIS CLI (также известна как dgCtl) предназначена для получения файла с лицензией, а также для загрузки, сохранения и восстановления артефактов, которые необходимы для установки и обновления сервисов программного комплекса 2ГИС.

Артефакты установки включают в себя:

  • Docker-образы сервисов.
  • данные, необходимые для работы сервисов.

Подробнее о жизненном цикле артефактов установки см. здесь.

Архитектура

dgctl apps to registry argument behavior

2GIS CLI позволяет разделить получение артефактов установки на два этапа.

  1. Загрузка артефактов установки из интернета (режим pull)
  2. Установка сервисов из загруженных артефактов (режим restore)

В качестве хранилища артефактов могут быть использованы S3-совместимое хранилище или файловая система, см. настройку storage.type в конфигурационном файле.

При любом выбранном режиме и типе хранилища рекомендуется разделять артефакты установки с помощью аргумента --apps-to-registry (см. справку по командам и аргументам). В этом случае Docker-образы сервисов будут помещены в реестр Docker, а все прочие артефакты — в хранилище выбранного типа. Такой подход дает больше контроля над размещением артефактов и позволяет избежать их смешения.

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

2GIS CLI запускается в одном из следующих режимов: license, pull или restore.

Режим Нужен доступ в интернет Откуда загружать Типы целевых хранилищ
license Да Серверы лицензирования 2ГИС S3-совместимое хранилище
Файловая система
pull Да Серверы обновления 2ГИС S3-совместимое хранилище и реестр Docker
Файловая система и реестр Docker
restore Нет Файловая система S3-совместимое хранилище и реестр Docker
Файловая система и реестр Docker

Режим license

В режиме license утилита запросит файл лицензии с серверов 2ГИС и запишет его в выбранное хранилище. Подробнее см. Установка сервиса лицензий.

Режим pull

В режиме pull утилита выполнит загрузку актуальных артефактов установки с серверов обновления 2ГИС в выбранное хранилище и (при необходимости) в реестр Docker.

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

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

Режим restore

В режиме restore утилита выполнит загрузку артефактов установки, которые уже хранятся в файловой системе-источнике, в выбранное хранилище и (при необходимости) в реестр Docker. Артефакты должны быть предварительно загружены в файловую систему-источник с помощью режима pull.

Обратите внимание, что при использовании файловой системы в качестве целевого хранилища (настройка storage.type: fs) запуск утилиты в режиме restore требует монтирования двух папок: исходной и целевой. Подробнее см. в справке по командам и аргументам.

Зависимости

Для работы с утилитой 2GIS CLI вам понадобится:

  • Лицензия на программный комплекс 2ГИС, которая позволяет получать артефакты установки, связанные с приобретёнными продуктами 2ГИС.

    Чтобы получить лицензию, заполните форму на dev.2gis.ru/order.

  • Хост с установленным Docker Engine. На этом хосте будет работать 2GIS CLI.

    Для работы утилиты в режимах license или pull этот хост должен иметь доступ в интернет (до серверов 2ГИС).

  • В зависимости от выбранного типа хранилища:

    • S3-совместимое хранилище артефактов установки.
    • Свободное место на файловой системе хоста, предназначенного для 2GIS CLI.

  • Реестр Docker, если он будет использоваться для хранения Docker-образов.

Сценарии использования

Ниже приведены несколько примеров файлов конфигурации и команд запуска утилиты 2GIS CLI.

Более полная документация, включая все доступные настройки, приведена в разделах Конфигурационный файл 2GIS CLI и Справка по командам и аргументам 2GIS CLI.

Важное примечание:

Все пароли в этом разделе приведены в иллюстративных целях.

При реальной установке рекомендуется использовать более сложные и надёжные пароли.

pull в S3-хранилище

  1. Создайте файл конфигурации dgctl-config.yaml:

    dgctl-config.yaml 
    key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: s3
    host: artifacts.storage.local
    bucket: dgctl-store
    access-key: AKIAIOSFODNN7EXAMPLE
    secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

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

    • Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    pull --config=/dgctl-config.yaml --version=1.21.0 --apps-to-registry

    • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    pull --config=/dgctl-config.yaml --version=1.21.0

pull в файловую систему

  1. Создайте файл конфигурации dgctl-config.yaml:

    dgctl-config.yaml 
    key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: fs
    directory: /dgctl-source
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

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

    • Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    pull --config=/dgctl-config.yaml --version=1.21.0 --apps-to-registry

    • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    pull --config=/dgctl-config.yaml --version=1.21.0

restore в S3-хранилище

  1. Создайте файл конфигурации dgctl-config.yaml:

    dgctl-config.yaml 
    key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: s3
    host: artifacts.storage.local
    bucket: dgctl-store
    access-key: AKIAIOSFODNN7EXAMPLE
    secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

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

    • Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --version=1.21.0 --from-dir=/dgctl-source --apps-to-registry

    • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --version=1.21.0 --from-dir=/dgctl-source

restore в файловую систему

  1. Создайте файл конфигурации dgctl-config.yaml:

    dgctl-config.yaml 
    key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
log-format: json
storage:
    type: fs
    directory: /dgctl-target
docker:
    registry:
        username: registry-user
        password: DOCKERregistryP@ssW0rd
        server-address: http://docker.registry.local:5000
        image-prefix: /

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

    • Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /mnt/dgctl-target:/dgctl-target \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --version=1.21.0 --from-dir=/dgctl-source --apps-to-registry

    • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

      docker run --rm \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /mnt/dgctl-target:/dgctl-target \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    restore --config=/dgctl-config.yaml --version=1.21.0 --from-dir=/dgctl-source