Установка API для работы с картами

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

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

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

1. Перед установкой

По возможности познакомьтесь с:
- Документацией сервисов карт
- Архитектурой программного комплекса 2ГИС
Убедитесь, что выполнены необходимые предварительные шаги:

Ознакомьтесь с важными значениями, заданными или полученными на предыдущих шагах:

Объект	Пример значения	Как получить значение
Эндпоинт зеркала реестра Docker	`docker.storage.example.local:5000`	См. Получение артефактов установки
Секрет Kubernetes для доступа к зеркалу реестра Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Домен S3-хранилища с артефактами установки	`artifacts.example.com`	См. Получение артефактов установки
Название бакета с артефактами установки	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Путь к файлу манифеста	`manifests/1640661259.json`	См. Получение артефактов установки
Эндпоинт сервиса лицензий	`HTTP(S)://HOST`	См. Установка сервиса лицензий
Эндпоинт API сервиса ключей	`keys.example.local`	См. Установка сервиса ключей
Эндпоинт прокси для API пробок	`traffic-proxy.example.local`	См. Установка прокси для API пробок
Сервисные токены	`TILES_TOKEN`	См. Установка сервиса ключей

Убедитесь, что удовлетворены следующие требования к ресурсам (требования приведены с учётом минимального числа реплик):

Для testing-окружения:

Сервис	vCPU	RAM	Хранилище
MapGL JS API	2	4 ГБ	—
Tiles API Backend	2	1 ГБ	Apache Cassandra
Apache Cassandra	3	48 ГБ	500 ГБ
Задание импорта Kubernetes	1	4 ГБ	—
Итоговое количество:	8	57 ГБ	500 ГБ

Для production-окружения:

Сервис	vCPU	RAM	Хранилище
MapGL JS API	4	4 ГБ	—
Tiles API Backend	8	1 ГБ	Apache Cassandra
Apache Cassandra	12	48 ГБ	500 ГБ
Задание импорта Kubernetes	4	4 ГБ	—
Итоговое количество:	28	57 ГБ	500 ГБ

Примечание:

Подробная информация о системных требованиях для отдельных сервисов и компонентов программного комплекса 2ГИС приведена в документе Системные требования.

Определите доменные имена для сервисов карт.

Пример:
- Доменное имя для Tiles API: tiles.example.com
- Доменное имя для MapGL JS API: mapgl.example.com

2. Подготовьте инфраструктуру, необходимую для работы сервисов

Настройка Apache Cassandra

Разместите один или несколько инстансов хранилища Apache Cassandra в приватной сети.

Рекомендуется включить доступ к Apache Cassandra по протоколу JMX, чтобы разрешить очистку снимков хранилища (см. Обновление сервиса Tiles API).

Если настройки безопасности не разрешают автоматическое создание пространств ключей (keyspace), то для хранения данных о тайлах создайте пространство ключей вручную.

Пример:

Хосты:
- tiles-cassandra-1.storage.example.local
- tiles-cassandra-2.storage.example.local
- tiles-cassandra-3.storage.example.local
Имя пользователя: cassandrauser
Пароль: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
Имя пользователя для JMX: jmxuser
Пароль для JMX: JMXPASSWORD-MNZLQTFH0MDDHIX8

3. Установите сервисы карт

Установка сервиса Tiles API

Выберите вариант Tiles API, который нужно установить: для векторных или растровых тайлов.
Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-tiles.yaml
```
dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise

dgctlStorage:
    host: artifacts.example.com
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json

warningText: License expiring in %d days.\nPlease contact your account manager.\n%s
errorText: License expired.\nPlease contact your account manager.\n%s
emailManager: on-premise@2gis.com

types:
    - kind: web

cassandra:
    hosts:
        - tiles-cassandra-1.storage.example.local
        - tiles-cassandra-2.storage.example.local
        - tiles-cassandra-3.storage.example.local
    replicaFactor: 3
    consistencyLevelRead: LOCAL_QUORUM
    consistencyLevelWrite: LOCAL_QUORUM
    credentials:
        user: cassandrauser
        password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
        jmxUser: jmxuser
        jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8

importer:
    workerNum: 20
    writerNum: 8
    workerResources:
        requests:
            cpu: 256m
            memory: 512Mi
        limits:
            cpu: 2
            memory: 2048Mi
    cleaner:
        enabled: true
        limit: 3
    clearSnapshots: true

api:
    imagePullSecrets: [onpremise-registry-creds]
    pdb:
        enabled: false
    ingress:
        hosts:
            - host: tiles.example.com

proxy:
    access:
        enabled: true
        url: http://keys.example.local
        token: TILES_TOKEN

license:
    url: ''
    retryPeriod: 30s
```
Где:
- dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- dgctlStorage: настройки хранилища артефактов установки.
  - Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
  - manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
- warningText: предупреждающее сообщение о скорой блокировке при работе с растровыми тайлами. Должно содержать: %d — плейсхолдер для количества дней до полной блокировки, %s — плейсхолдер для контакта менеджера аккаунта.
- errorText: сообщение о полной блокировке при работе с растровыми тайлами. Должно содержать %s — плейсхолдер для контакта менеджера аккаунта.
- emailManager: контакт менеджера аккаунта, который используется в сообщениях при работе с растровыми тайлами.
- types: массив из одного и более типов тайлов которые будет предоставлять сервис.
  - types[0].kind: задаёт тип возвращаемых тайлов. Возможные значения:
    - web — векторные тайлы для MapGL JS API
    - raster — растровые тайлы
    - native — векторные тайлы для Mobile SDK
- cassandra: настройки хранилища данных Apache Cassandra.
  - hosts: массив из одного и более IP-адресов инсталляции Apache Cassandra.
  - replicaFactor: фактор репликации. Задайте подходящее значение для этой настройки в соответствии с вашей инсталляцией Apache Cassandra.
  - При необходимости задайте подходящее значение для настроек консистентности данных в соответствии с вашей инсталляцией Apache Cassandra.
  - credentials: учётные данные для аутентификации. Значения user и password являются обязательными, а jmxUser и jmxPassword используются только для очистки снимков хранилища (см. Обновление сервиса Tiles API). Значение по умолчанию каждого из параметров - cassandra.
- importer: настройки воркеров процесса импорта (Kubernetes Importer job).
  - workerNum: число воркеров (параллельных процессов импорта).
  - writerNum: число процессов-писателей на один воркер.
    
    Примечание:
    
    При установке Tiles API с поддержкой растровых тайлов, рекомендуется уменьшить значения настроек workerNum (по умолчанию: 20) и writerNum (по умолчанию: 8)
    
    Импорт данных для растровых тайлов может занять длительное время. Использование относительно высоких значений по умолчанию может привести к преждевременному завершению задания из-за истечения таймаута.
  - workerResources: настройки вычислительных ресурсов для воркера. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
  - cleaner и clearSnapshots: настройки автоматического удаления старых данных. Подробнее см. в разделе Обновление сервиса Tiles API.
  См. Жизненный цикл артефактов установки для получения дополнительной информации о работе процесса импорта.
- api: Настройки бэкенд-сервиса API.
  - imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
  - pdb.enabled: включена ли защита сервиса с использованием Pod Disruption Budget.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- proxy: настройки сервиса ключей. Используйте эти настройки, если вы хотите ограничить доступ к сервису Tiles API для конечных пользователей.
  - access.enabled: флаг, определяющий, проверять ли действие ограничений для ключей доступа.
  - access.url: URL API-эндпоинта сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - access.token: отдельный сервисный API-ключ сервиса Tiles API. Этот ключ можно получить с помощью утилиты keysctl.
- license: настройки сервиса лицензий.
  - url: URL-адрес сервиса лицензий. Пример: HTTP(S)://HOST.
  - retryPeriod: как часто Tiles API должен пытаться обновить статус лицензии, если ему не удается его получить.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-tiles.yaml.
```
helm upgrade --install --version=1.4.5 --atomic --wait --timeout 7200 --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
```
Процесс импорта (Kubernetes Importer job) получит все необходимые данные из хранилища артефактов установки и далее импортирует эти данные в Apache Casssandra. Затем Helm выполнит установку самого сервиса.

Установка сервиса MapGL JS API

Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-mapgl.yaml
```
dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise

env:
    MAPGL_HOST: mapgl.example.com
    MAPGL_TILES_API: tiles.example.com
    MAPGL_KEYSERVER: keys.example.com
    MAPGL_TRAFFICSERVER: traffic-proxy.example.com

resources:
    requests:
        cpu: 30m
        memory: 32M
    limits:
        cpu: 100m
        memory: 64M

ingress:
    hosts:
        - host: mapgl.example.com
    tls:
        - hosts:
              - mapgl.example.com
          secretName: mapgl-js-api
```
Где:
- dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- env: переменные среды окружения.
  - MAPGL_HOST: FQDN сервиса. Ваши приложения должны использовать это доменное имя (или IP-адрес) для коммуникаций с сервисами карт.
  - MAPGL_TILES_API: доменное имя сервиса Tiles API.
  - MAPGL_KEYSERVER: доменное имя сервиса ключей.
  - MAPGL_TRAFFICSERVER: доменное имя публичного сервера 2ГИС, предоставляющего данные о пробках, или прокси для API пробок. Сервер по умолчанию: traffic-jams.2gis.com.
- resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
- ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. Обратите внимание, что для использования TLS необходимо создать секрет, содержащий сертификат и приватный ключ.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-mapgl.yaml:
```
helm upgrade --install --version=1.4.5 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
```

4. Проверьте работоспособность установленных сервисов

Проверка сервиса MapGL JS API

Чтобы проверить работу сервисов MapGL JS API и Tiles API, выполните одно из следующих действий:

Перейдите в браузере по доменному имени или IP-адресу сервиса:
```
http://mapgl.example.com
```

Напишите код для отображения демонстрационной векторной карты, затем откройте его в браузере:

<html>
    <head>
        <title>MapGL JS API. On-Premise</title>
        <style>
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="map"></div>
        <script src="//mapgl.example.com/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                style: '//mapgl.example.com/style/',
                styleOptions: {
                    iconsPath: '//mapgl.example.com/style/images/',
                    fontsPath: '//mapgl.example.com/style/fonts/',
                },
                useRtlTextPlugin: 'always-on',
                zoom: 13,
            });
        </script>
    </body>
</html>

Примечание:

Этот код немного отличается от кода, размещенного в документации MapGL JS API. Если вы планируете использовать примеры кода из этой документации, не забудьте адаптировать их к вашей инсталляции сервисов карт, как показано выше.

Должна отобразиться демонстрационная векторная карта, которая использует векторные тайлы, получаемые от сервиса Tiles API.

Проверка сервиса Tiles API с поддержкой растровых тайлов

Чтобы проверить работу сервиса Tiles API, который работает с растровыми тайлами, перейдите в браузере по адресу (приведён пример для Москвы):

http://tiles.example.com/tiles?x=1237&y=640&z=11&v=1

Должен отобразиться демонстрационный растровый тайл.

Что дальше?

Узнайте, как обновить сервисы карт:
- Обновление API для работы с картами
Установите другие продукты программного комплекса 2ГИС: