2GIS CLI (dgCtl) | On-Premise | 2GIS Documentation
On-Premisebeta
Карты
Поиск
Навигация
On-Premise
ру
en

2GIS CLI (dgCtl)

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

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

Архитектура

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

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

  • S3-совместимое хранилище;
  • файловая система.
dgctl apps to registry argument behavior

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

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

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

    Примечание:

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

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

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

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

dgctl pull mode

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

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

dgctl restore mode

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

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

Артефакты должны быть предварительно загружены в файловую систему-источник с помощью режима pull.

Требования

  1. Ключ доступа для 2GIS CLI, который позволяет получать артефакты развёртывания, связанные с приобретёнными продуктами 2GIS.

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

  2. Общая инфраструктура:

    • Реестр 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> - одна из команд, определяющих режим работы:

  • <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)

  1. Создайте один из вариантов конфигурационного файла 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

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

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

  1. Создайте конфигурационный файл config.yaml для того типа хранилища, в которое нужно восстановить артефакты (см. шаг 1 в предыдущем подразделе). Ключ доступа для 2GIS CLI в этом случае можно не указывать.

  2. Запустите одну из следующих команд, указав директорию, в которой находятся загруженные артефакты (например, /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