Карты

Сервисы карт позволяют отображать карты 2GIS в веб-приложениях и на сайтах.

В этой статье описывается, как развернуть и настроить сервисы карт в вашем окружении. Чтобы узнать, как использовать API, предоставляемые сервисами карт, обратитесь к документации Map JS API.

Архитектура

Сервисы карт могут быть развернуты в двух разных конфигурациях:

Используя сервисы MapGL JS API и Tiles API.

В этой конфигурации MapGL JS API реализует JavaScript API для отображения карт, используя векторные тайлы, полученные от Tiles API.

Чтобы использовать API, необходимо загрузить с веб-сервера основной файл библиотеки (api.js) и светлый стиль карты, который используется по умолчанию (находится в директории style).

Дополнительно может быть настроен прокси для пробок, чтобы получать данные о пробках в реальном времени с серверов 2GIS. Конечные пользователи и приложения затем могут с помощью MapGL JS API отобразить пробки в виде цветных линий на отдельном слое карты.
Используя только сервис Tiles API.

В этой конфигурации Tiles API предоставляет растровые тайлы.

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

Каждая из этих конфигураций требует наличия сервиса Tiles API. Он предоставляет API для получения и отображения тайлов карты. Тайл - квадратное изображение, соответствующее участку карты (пример тайлированной карты). С помощью тайлов становится возможным рендерить только видимую часть карты, подгружая необходимые тайлы при перемещении по карте или при изменении масштаба карты. Таким образом, работая с картой, приложение потребляет меньше памяти.

Детали архитектуры решения On-Premise приведены в обзорном документе.

Требования

Если вы планируете развернуть конфигурацию с сервисами MapGL JS API и Tiles API:

Сервисы:
- MapGL JS API.
- Tiles API, предоставляющий векторные тайлы.
Общая инфраструктура:
- Прокси для пробок, настроенный на использование серверов обновлений, предоставляющих данные о пробках в векторном формате.
- Хранилище данных Apache Cassandra для тайлов.

Если вы планируете развернуть конфигурацию только с сервисом Tiles API:

Сервисы:
- Tiles API, предоставляющий растровые тайлы.
Общая инфраструктура:
- Хранилище данных Apache Cassandra для тайлов.

Детальные требования для каждого сервиса описаны в обзорном документе. Дополнительную информацию можно найти в разделе Что нужно учесть перед развертыванием этого документа.

Установка

Примечание:

Конфигурации Ingress в файлах ниже приведены для примера в ознакомительных целях. Адаптируйте приведенные конфигурации для соответствия используемому вами Ingress.

Выполните следующие шаги:

Выполните общие шаги по развертыванию.

Примечание:

Не забудьте записать путь к файлу с манифестом, эта информация необходима для развертывания сервисов.
Разверните сервис Tiles API.
Разверните прокси для пробок, если необходимо (см. раздел Требования).
Разверните сервис MapGL JS API, если необходимо (см. раздел Требования).

Tiles API

Выберите вариант Tiles API, который нужно развернуть: для векторных или растровых тайлов.
Создайте конфигурационный файл values-tiles.yaml:

values-tiles.yaml
```
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise

dgctlStorage:
    host: <Deployment Artifacts Storage endpoint>
    bucket: <Deployment Artifacts Storage bucket>
    accessKey: <The bucket access key>
    secretKey: <The bucket secret key>
    manifest: <Path to the manifest file>

serviceName: <name that depends on Tiles API flavor>
type: <Tiles API flavor>

cassandra:
    hosts:
        - <IP address of Apache Cassandra host>
        - ...
        - <IP address of Apache Cassandra host>

    replicaFactor: 3
    consistencyLevelRead: LOCAL_QUORUM
    consistencyLevelWrite: LOCAL_QUORUM
    credentials:
        user: "cassandra"
        password: "cassandra"
        jmxUser: "cassandra"
        jmxPassword: "cassandra"

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

api:
    pdb:
        enabled: false
    ingress:
        annotations:
            cert-manager.io/cluster-issuer: <Issuer name>
        enabled: true
        hosts:
            - host: <Domain name for Tiles API service>
                paths:
                    - path: /
                      pathType: Prefix
        tls:
            - hosts:
                - <Domain name for Tiles API service>
            secretName: tls-tiles-api

proxy:
    access:
        enabled: <true or false>
        host: <API Keys endpoint>
        token: <service API key>
```
Где:
1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.
2. dgctlStorage: настройки хранилища артефактов развертывания.
  1. Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
  2. manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы.
3. serviceName: имя сервиса.
  1. tiles-api-webgl: для Tiles API с поддержкой векторных тайлов.
  2. tiles-api-raster: для Tiles API с поддержкой растровых тайлов.
4. type: тип сервиса.
  1. Не указывайте значение этого параметра для Tiles API с поддержкой векторных тайлов.
  2. raster: для Tiles API с поддержкой растровых тайлов.
5. cassandra: настройки хранилища данных Apache Cassandra.
  1. hosts: массив из одного и более IP-адресов инсталляции Apache Cassandra.
  2. replicaFactor: фактор репликации. Задайте подходящее значение для этой настройки в соответствии с вашей инсталляцией Apache Cassandra.
  3. При необходимости задайте подходящее значение для настроек консистентности данных в соответствии с вашей инсталляцией Apache Cassandra. См. документацию Apache Cassandra для получения дополнительной информации.
  4. credentials: учётные данные для аутентификации. Значения user и password являются обязательными, а jmxUser и jmxPassword используются только для очистки снимков хранилища (см. Обновление сервиса Tiles API). Значение по умолчанию каждого из параметров - cassandra.
6. importer: настройки воркеров процесса импорта (Kubernetes Importer job).
  1. workerNum: число воркеров (параллельных процессов импорта).
  2. writerNum: число процессов-писателей на один воркер.
    
    Примечание:
    
    При развертывании Tiles API с поддержкой растровых тайлов, рекомендуется уменьшить значения настроек workerNum (по умолчанию: 20) и writerNum (по умолчанию: 8)
    
    Импорт данных для растровых тайлов может занять длительное время. Использование относительно высоких значений по умолчанию может привести к преждевременному завершению задания из-за истечения таймаута.
  3. workerResources: настройки вычислительных ресурсов для воркера. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
  4. cleaner и clearSnapshots: настройки автоматического удаления старых данных. Подробнее см. в разделе Обновление сервиса Tiles API.
  См. обзорный документ для получения дополнительной информации о работе процесса импорта.
7. api: Настройки бэкенд-сервиса API.
  1. pdb.enabled: флаг, определяющий, включена ли защита сервиса с использованием Pod Disruption Budget.
  2. ingress: пример конфигурации ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
8. proxy: настройки сервиса ключей. Используйте эти настройки, если вы хотите ограничить доступ к сервису Tiles API для конечных пользователей.
  1. access.enabled: флаг, определяющий, проверять ли действие ограничений для ключей доступа.
  2. url: URL API-эндпоинта сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  3. token: отдельный сервисный API-ключ сервиса Tiles API. Этот ключ можно получить с помощью утилиты keysctl.
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл values-tiles.yaml:

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

В процессе развертывания будет выполнена инициализация пространства ключей (keyspace) Apache Cassandra для инсталляции Apache Cassandra, которая указана в конфигурационном файле values-tiles.yaml.

Это означает, что существующие данные в этом пространстве ключей будут полностью заменены данными из хранилища артефактов развертывания.

Существующие данные сохраняются в течении короткого промежутка времени только если вы выполняете обновление сервиса, а не первоначальное развертывание.
```
helm upgrade --install --version=1.0.3 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
```
Процесс импорта (Kubernetes Importer job) получит все необходимые данные из хранилища артефактов развертывания и далее импортирует эти данные в Apache Casssandra. Затем Helm выполнит развертывание самого сервиса.

MapGL JS API

Создайте конфигурационный файл values-mapgl.yaml:

values-mapgl.yaml
```
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise

env:
    MAPGL_HOST: <Domain name for MapGL JS API service>
    MAPGL_TILES_API: <Domain name of the Tiles API service>
    MAPGL_KEYSERVER: <Domain name of the API Keys service>
    MAPGL_TRAFFICSERVER: <Domain name of the Traffic Proxy service>

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

ingress:
    annotations:
        cert-manager.io/cluster-issuer: <Issuer name>
    enabled: true
    hosts:
        - host: <Domain name for MapGL JS API service>
            paths:
                - path: /
                  pathType: Prefix
    tls:
        - hosts:
            - <Domain name for MapGL JS API service>
        secretName: mapgl-js-api
```
Где:
1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.
2. env: переменные среды окружения.
  1. MAPGL_HOST: FQDN сервиса. Ваши приложения должны использовать это доменное имя (или IP-адрес) для коммуникаций с сервисами карт.
  2. MAPGL_TILES_API: доменное имя развернутого прокси для пробок.
  3. MAPGL_KEYSERVER: доменное имя сервиса ключей.
  4. MAPGL_TRAFFICSERVER: Доменное имя публичного сервера 2GIS, предоставляющего данные о пробках. Сервер по умолчанию: traffic-jams.2gis.com.
3. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
4. ingress: пример конфигурации ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress.
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл values-mapgl.yaml:
```
helm upgrade --install --version=1.0.3 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
```

Обновление

Tiles API

Вы можете обновить сервис Tiles API как вместе с его данными (самими тайлами), так и без их обновления.

Чтобы обновить только сервис:

helm upgrade --version=1.0.3 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api --set importer.enabled=false

Чтобы обновить сервис и данные:
```
helm upgrade --version=1.0.3 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
```
Свежезагруженные файлы после каждого обновления хранятся в новом кейспейсе (keyspace) в Cassandra. Название кейспейса генерируется на основе типа данных (web или raster), названия кластера Cassandra и Unix-времени в момент генерации манифеста (при вызове 2GIS CLI). Например: dgis_tileserver_web_test_1653477379.

Все данные в прежнем кейспейсе после успешного переключения на новый кейспейс становятся ненужными. Для экономии места на диске рекомендуется удалять старые кейспейсы. Это можно делать автоматически следующим образом:
1. В настройке importer.cleaner.enabled укажите значение true.
2. В настройке importer.cleaner.limit укажите количество старых кейспейсов, которые нужно хранить. Например, 1 означает, что будет оставлен всего один ненужный кейспейс, а все более старые будут удалены. Обратите внимание, что этот лимит не может быть менее 1, так как это привело бы к удалению кейспейса, являющегося текущим на момент выполнения helm upgrade.
3. По умолчанию удалённые данные всё ещё будут занимать дисковое пространство в виде снимков (snapshots) Cassandra. Удалить устаревшие снимки можно вручную с помощью nodetool clearsnapshot, или можно настроить автоматическое удаление через JMX:
  1. Убедитесь, что в вашей конфигурации Cassandra включён удалённый доступ по JMX.
  2. Задайте настройки cassandra.credentials.jmxUser и cassandra.credentials.jmxPassword.
  3. В настройке importer.clearSnapshots укажите значение true.

MapGL JS API

Чтобы обновить сервис, выполните следующую команду:

helm upgrade --version=1.0.3 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api

Проверка работоспособности

Сервисы MapGL JS API и Tiles API

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

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

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

<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_HOST/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                style: '//MAPGL_HOST/style/',
                styleOptions: {
                    iconsPath: '//MAPGL_HOST/style/images/',
                    fontsPath: '//MAPGL_HOST/style/fonts/',
                },
                useRtlTextPlugin: 'always-on',
                zoom: 13,
            });
        </script>
    </body>
</html>

Примечание:

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

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

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

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

http://TILES_API_PUBLIC_HOST/tiles?x=2602&y=1736&z=12

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