Подготовка к установке

Перед установкой любых продуктов программного комплекса 2ГИС необходимо:

1. Получить лицензию на программный комплекс 2ГИС.
2. Подготовить сетевую инфраструктуру.
3. Добавить Helm-репозиторий.
4. Получить артефакты установки.

1. Получите лицензию на программный комплекс 2ГИС

Для доступа к репозиторию с артефактами установки необходима лицензия на программный комплекс 2ГИС (см. Ключи и токены).

1. Заполните форму на dev.2gis.ru.
2. Получив лицензионный ключ, укажите его в конфигурационном файле 2GIS CLI.

2. Подготовьте сетевую инфраструктуру

Рекомендуемая инфраструктура для работы сервисов программного комплекса 2ГИС состоит из публичной и приватной сетей. В таблице ниже описан пример такой инфраструктуры с доменами example.com и example.local. Все компоненты должны быть развёрнуты в одном кластере Kubernetes, управляемом с хоста example.com.

Компонент инфраструктуры	Кто должен иметь доступ	Тип сети	Домены, используемые в документации
Инфраструктура доставки артефактов	Администратор инфраструктуры	Публичная	example.com example-external.com example-internal.com
Реестр Docker для хранения образов сервисов	Утилита 2GIS CLI с хоста example.com	Публичная	docker.example.com
Хранилище артефактов установки	Утилита 2GIS CLI с хоста example.com	Публичная	artifacts.example.com
Фронтенды сервисов	Приложения и конечные пользователи в приватной сети	Приватная	*.example.com
Бэкенды сервисов	Другие сервисы и хранилища из всех подов кластера Kubernetes	Приватная	*.example.local
Хранилища данных	Другие сервисы и хранилища из всех подов кластера Kubernetes	Приватная	*.storage.example.local

Примечание

Если для развёртывания продукта используется Managed Kubernetes (Kubernetes as a Service), убедитесь, что доступ к реестру Docker настроен с использованием протокола HTTPS и сертификата, подписанного доверенным центром сертификации (например, Let’s Encrypt).

3. Добавьте Helm-репозиторий

Для установки каждого конкретного продукта 2ГИС используется Helm-чарт из репозитория программного комплекса 2ГИС. Необходимо добавить этот репозиторий на хосте, с которого будет выполняться установка продуктов. В примере, описанном выше, это хост example.com.

1. Установите в кластер менеджер пакетов Helm. Для этого воспользуйтесь официальными инструкциями по установке.

2. Добавьте репозиторий с Helm-чартами 2ГИС:

   helm repo add 2gis-on-premise https://2gis.github.io/on-premise-helm-charts
   helm repo update

3. Проверьте корректность установки Helm и репозитория, выполнив команду:

   helm search repo 2gis-on-premise

   Если вывод команды содержит непустой список чартов, то всё настроено корректно.

4. Получите артефакты установки

4.1. Настройте хосты

Пример архитектуры хостов On-Premise:

docker.example.com

Этот хост будет обслуживать реестр Docker. Хост должен быть доступен в публичной сети, см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите реестр Docker.

   Реестр должен быть доступен по адресу https://docker.example.com:5000/.

3. Настройте аутентификацию в реестре по имени пользователя и паролю.

   Пример:

   • Имя пользователя: registry
   • Пароль: DOCKERregistryP@ssW0rd

artifacts.example.com

Этот хост будет обслуживать S3-совместимое хранилище артефактов установки. Хост должен быть доступен в публичной сети, см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите подходящее для ваших задач S3-совместимое хранилище. Рекомендуется использовать Ceph.

   Хранилище должно быть доступно по адресу https://artifacts.example.com:443/.

3. В установленном хранилище создайте бакет onpremise-artifacts нужного размера.

4. Назначьте этому бакету сервисный аккаунт с правами на чтение и запись.

   Для этого сервисного аккаунта сгенерируйте ключ, с помощью которого можно будет получить доступ к бакету.

   Пример:

   • Идентификатор ключа: AKIAIOSFODNN7EXAMPLE
   • Секрет ключа: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

example.com

Этот хост будет обслуживать утилиту 2GIS CLI. Хост должен быть доступен в публичной сети, см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите Docker Engine.

3. Убедитесь, что хост может подключаться к ранее настроенным сервисам:

   • https://docker.example.com:5000/
   • https://artifacts.example.com:443/

Теперь вы можете загрузить артефакты установки.

Если один хост не может обеспечить одновременный доступ к публичной сети, реестру Docker и S3-совместимому хранилищу, настройте два хоста:

• example-external.com — с доступом в публичную сеть;
• example-internal.com — с доступом к https://docker.example.com:5000/ и https://artifacts.example.com:443/.

После этого вы можете загрузить артефакты установки с использованием двух хостов.

4.2. Загрузите артефакты установки

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

Использование одного хоста

1. Зайдите по SSH на хост example.com.

2. Создайте конфигурационный файл dgctl-config.yaml. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   dgctl-config.yaml

   key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
   log-format: json
   
   storage:
       type: s3
   
       host: artifacts.example.com:443
       bucket: onpremise-artifacts
       access-key: AKIAIOSFODNN7EXAMPLE
       secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
   
   docker:
       registry:
           username: registry
           password: DOCKERregistryP@ssW0rd
           server-address: https://docker.example.com:5000
           image-prefix: /
   
   # Для утилиты версии 3
   components:
       core:
           version: 1.1.0
       api-platform:
           version: 1.1.0

3. Загрузите артефакты установки в файловую систему с помощью утилиты 2GIS CLI:

   docker run --rm \
       -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v $(pwd)/values:/values \
       --user $(id -u):$(id -g) \
       2gis/dgctl:3 \
       pull --config=/dgctl-config.yaml --apps-to-registry --generate-values

   Загрузка артефактов установки может занять длительное время. Когда процесс завершится, в консольном выводе команды будет указан путь к файлам манифестов для всех компонентов. Пример: manifests/<компонент>/1640661259.json.

   При использовании флага --generate-values файл с параметрами конфигурации general.yaml будет сгенерирован и размещён в локальной директории, которая указана в аргументе -v <путь>:/values/<компонент>/ (в примере: -v $(pwd)/values:/values). Если не указать путь, файл удалится после запуска утилиты.

   Примечание

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

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

При использовании двух хостов загрузите артефакты установки с серверов обновления 2ГИС и перенесите их в S3-совместимое хранилище. Для этого вы можете использовать утилиту 2GIS CLI (рекомендуется) или другой клиент для работы с S3.

1. Зайдите по SSH на хост example-external.com.

2. Cоздайте директорию COPY_DIR для скачивания артефактов установки.

3. Создайте конфигурационный файл dgctl-config.yaml. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   dgctl-config.yaml

   key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
   log-format: json
   storage:
       type: fs
       directory: /data
   
   # Для утилиты версии 3
   components:
       core:
           version: 1.1.0
       api-platform:
           version: 1.1.0

4. Загрузите артефакты установки в файловую систему с помощью утилиты 2GIS CLI:

    docker run --rm \
           -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
           -v $COPY_DIR:/data
           -v $(pwd)/values:/values \
           --user $(id -u):$(id -g) \
           2gis/dgctl:3 \
           pull --config=/dgctl-config.yaml --generate-values

   Загрузка артефактов может занять длительное время. Когда процесс завершится, в консольном выводе команды будет указан путь к файлам манифестов для всех компонентов. Пример: manifests/<компонент>/1640661259.json.

   При использовании флага --generate-values файлы с параметрами конфигурации general.yaml будут сгенерированы для каждого компонента и размещены в локальной директории, которая указана в аргументе -v <путь>:/values/<компонент>/ (в примере: -v $(pwd)/values:/values). Если не указать путь, файлы удалятся после запуска утилиты.

   Примечание

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

5. Перенесите директорию COPY_DIR с example-external.com на example-internal.com.

6. Зайдите по SSH на хост example-internal.com.

7. Создайте конфигурационный файл dgctl-config.yaml. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   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

8. Загрузите артефакты установки в реестр Docker и S3-совместимое хранилище с помощью утилиты 2GIS CLI:

        docker run --rm \
            -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
            -v $COPY_DIR:/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

4.3. Организуйте зеркала инфраструктуры в приватной сети

Создайте зеркала следующих ресурсов в приватной сети:

Ресурс	Хост в публичной сети	Хост-зеркало в приватной сети
Реестр Docker	docker.example.com	docker.storage.example.local
S3-совместимое хранилище артефактов установки	artifacts.example.com	artifacts.storage.example.local

Для зеркал в приватной сети endpoints будут отличаться от endpoints в публичной сети:

Пример:

• Endpoint зеркала реестра: docker.storage.example.local:5000
• Endpoint зеркала хранилища: artifacts.storage.example.local:443

4.4. Создайте секрет Kubernetes для доступа к реестру Docker

Этот секрет нужен, чтобы Helm, с помощью которого устанавливаются сервисы программного комплекса 2ГИС, мог получить доступ к Docker-образам, которые находятся в реестре. Без такого секрета любая операция, связанная с реестром, завершится неудачей.

Пример:

kubectl create secret docker-registry onpremise-registry-creds \
    --docker-server=docker.storage.example.local:5000 \
    --docker-username=registry \
    --docker-password=DOCKERregistryP@ssW0rd