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

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

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

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

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

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

Базовые операции

pull в S3-совместимое хранилище

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

# Для утилиты версии 3
components:
    core:
        version: 1.1.0
    api-platform:
        version: 1.1.0

Запустите одну из следующих команд:
- Чтобы загрузить 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:3 \
    pull --config=/dgctl-config.yaml --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:3 \
    pull --config=/dgctl-config.yaml
```
Если вы используете утилиту 2GIS CLI версии 2, дополнительно укажите параметр --version в нужной версией программного комплекса On-Premise. Подробнее см. в Справке по командам и аргументам 2GIS CLI.

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

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

# Для утилиты версии 3
components:
    core:
        version: 1.1.0
    api-platform:
        version: 1.1.0

Запустите одну из следующих команд:
- Чтобы загрузить 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:3 \
    pull --config=/dgctl-config.yaml --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:3 \
    pull --config=/dgctl-config.yaml
```
Если вы используете утилиту 2GIS CLI версии 2, дополнительно укажите параметр --version в нужной версией программного комплекса On-Premise. Подробнее см. в Справке по командам и аргументам 2GIS CLI.

restore из S3-совместимого хранилища

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

# Для утилиты версии 3
components:
    core:
        version: 1.1.0
    api-platform:
        version: 1.1.0

Запустите одну из следующих команд:
- Чтобы выгрузить 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:3 \
    restore --config=/dgctl-config.yaml --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:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды, а также используйте аргументы --only-apps и/или --only-data для выгрузки образов сервисов и/или данных соответственно.

restore из файловой системы

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

# Для утилиты версии 3
components:
    core:
        version: 1.1.0
    api-platform:
        version: 1.1.0

Запустите одну из следующих команд:
- Чтобы выгрузить 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:3 \
    restore --config=/dgctl-config.yaml --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:3 \
    restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды, а также используйте аргументы --only-apps и/или --only-data для выгрузки образов сервисов и/или данных соответственно.

Использование системных сертификатов

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

Запуск в Docker

Чтобы обеспечить работу сертификата внутри Docker-контейнера с утилитой 2GIS CLI, добавляйте следующий аргумент во все команды запуска контейнера, чтобы подключить сертификат к утилите:

-v <path-to-cert>:/etc/ssl/cert.pem

Где <path-to-cert> — путь к установленному сертификату.

Пример полной команды для запуска утилиты с системным сертификатом безопасности:

docker run -it \
    -v <path-to-cert>:/etc/ssl/cert.pem \
    -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:3 \
    pull --config=/dgctl-config.yaml --apps-to-registry

Если вы используете утилиту 2GIS CLI версии 2, дополнительно укажите параметр --version в нужной версией программного комплекса On-Premise. Подробнее см. в Справке по командам и аргументам 2GIS CLI.

Запуск бинарного файла

При запуске бинарного файла утилиты вы можете получить ошибку следующего вида:

ERRO[0004] failed to upload object: unable to put object into s3

Это может свидетельствовать о проблемах с сертификатом для доступа к S3-совместимому хранилищу. Чтобы решить эту проблему:

Убедитесь, что эта проблема связана именно с сертификатом. Выполните следующую команду через S3cmd:
```
s3cmd ls s3://bucket --host https://s3.my-host.com
```
Примечание

Для запуска S3cmd необходим конфигурационный файл с учетными данными для доступа к S3-совместимому хранилищу.

Если вы получаете ошибку следующего вида, то проблема действительно связана с сертификатом:
```
ERROR: SSL certificate verification failure: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1007)
```
Скачайте необходимый сертификат безопасности.
Установите сертификат в системе:

Для UNIX-подобных систем (Linux, macOS):
1. Запустите терминал.
2. Скопируйте сертификат в системное хранилище сертификатов при помощи команды ниже:
```
sudo cp /<path-to-cert>/sert.crt /usr/local/share/ca-certificates/
```
  Где <path-to-cert> — путь к скачанному сертификату.
3. Обновите список доверенных сертификатов:
```
sudo update-ca-certificates
```
Для Windows:
1. Откройте меню Пуск, начните вводить в поиске Управление сертификатами компьютера и выберите соответствующее приложение.
2. В дереве папок слева выберите Личное → Сертификаты.
3. В верхнем меню выберите Действие → Все задачи → Импорт.
4. Следуйте инструкциям мастера импорта сертификатов для установки скачанного сертификата.

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

Базовые операции​

pull в S3-совместимое хранилище​

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

restore из S3-совместимого хранилища​

restore из файловой системы​

Использование системных сертификатов​

Запуск в Docker​

Запуск бинарного файла​

Базовые операции

pull в S3-совместимое хранилище

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

restore из S3-совместимого хранилища

restore из файловой системы

Использование системных сертификатов

Запуск в Docker

Запуск бинарного файла