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

Карты

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

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

Архитектура

Архитектура сервисов карт (On-Premise)

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

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

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

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

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

  2. Используя только сервис 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.

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

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

    Примечание:

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

  2. Разверните сервис Tiles API.

  3. Разверните прокси для пробок, если необходимо (см. раздел Требования).

  4. Разверните сервис MapGL JS API, если необходимо (см. раздел Требования).

Tiles API

  1. Выберите вариант Tiles API, который нужно развернуть: для векторных или растровых тайлов.

  2. Создайте конфигурационный файл 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:
        password: "cassandra"
        user: "cassandra"

importer:
    workerNum: 20
    writerNum: 8
    workerResources:
        requests:
            cpu: 256m
            memory: 512Mi
        limits:
            cpu: 2
            memory: 2048Mi

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: учётные данные для аутентификации в Apache Cassandra. Значения по умолчанию: cassandra/cassandra.

    6. importer: настройки воркеров процесса импорта (Kubernetes Importer job).

      1. workerNum: число воркеров (параллельных процессов импорта).

      2. writerNum: число процессов-писателей на один воркер.

        Примечание:

        При развертывании Tiles API с поддержкой растровых тайлов, рекомендуется уменьшить значения настроек workerNum (по умолчанию: 20) и writerNum (по умолчанию: 8)

        Импорт данных для растровых тайлов может занять длительное время. Использование относительно высоких значений по умолчанию может привести к преждевременному завершению задания из-за истечения таймаута.

      3. workerResources: настройки вычислительных ресурсов для воркера. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

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

    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.

  3. Разверните сервис с помощью 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

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

  2. Разверните сервис с помощью 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

Особенности обновления для сервиса:

  • Вы можете обновить либо сервис вместе с данными, либо только сервис.
  • При обновлении данных текущий набор данных будет заменен на новый только после серии проверок.

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

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

  • Обновить сервис вместе с данными:

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

  • Обновить только сервис:

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

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, выполните одно из следующих действий:

  1. Перейдите в браузере по доменному имени или IP-адресу сервиса:

    http://MAPGL_HOST

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

    <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

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