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

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

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

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

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

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

  1. По возможности познакомьтесь с:

  2. Убедитесь, что выполнены необходимые предварительные шаги:

    1. Подготовка к установке
    2. Получение артефактов установки
    3. Установка сервиса лицензий
    4. Установка сервиса ключей
    5. Установка прокси для API пробок

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

    Объект Пример значения Как получить значение
    Эндпоинт зеркала реестра 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 См. Установка сервиса ключей

  4. Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чартах:

    Подробнее о том, как это сделать, смотрите в документе Системные требования.

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

    Пример:

    • Доменное имя для Tiles API: tiles-api.example.com
    • Доменное имя для MapGL JS API: mapgl-js-api.example.com
    • Доменное имя для Floors API: floors-api.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

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

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

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

    values-tiles.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise

dgctlStorage:
    host: artifacts.example.com
    secure: false
    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
    - kind: web
      subtype: immersive

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
    ssl:
        enabled: false
        caCrt: ''

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-api.example.com

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

license:
    url: ''
    retryPeriod: 30s

    Где:

    • dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • dgctlStorage: настройки хранилища артефактов установки.

      • Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • manifest: путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.

    • warningText: предупреждающее сообщение о скорой блокировке при работе с растровыми тайлами. Должно содержать: %d — плейсхолдер для количества дней до полной блокировки, %s — плейсхолдер для контакта менеджера аккаунта.

    • errorText: сообщение о полной блокировке при работе с растровыми тайлами. Должно содержать %s — плейсхолдер для контакта менеджера аккаунта.

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

    • types: массив из одного и более типов тайлов которые будет предоставлять сервис.

      • types[0].kind: задаёт тип возвращаемых тайлов. Возможные значения:
        • web — векторные тайлы для MapGL JS API.
          • subtype: immersive — подтип векторных тайлов для отображения 3D-моделей.
        • raster — растровые тайлы.
        • native — векторные тайлы для Mobile SDK.

    • cassandra: настройки хранилища данных Apache Cassandra.

      • hosts: массив из одного и более IP-адресов инсталляции Apache Cassandra.
      • replicaFactor: фактор репликации. Задайте подходящее значение для этой настройки в соответствии с вашей инсталляцией Apache Cassandra.
      • При необходимости задайте подходящее значение для настроек консистентности данных в соответствии с вашей инсталляцией Apache Cassandra.
      • credentials: учётные данные для аутентификации. Значения user и password являются обязательными, а jmxUser и jmxPassword используются только для очистки снимков хранилища (см. Обновление сервиса Tiles API). Значение по умолчанию каждого из параметров - cassandra.
      • ssl: конфигурация SSL для доступа к Apache Cassandra.
        • enabled: включите, если Apache Cassandra использует SSL для клиентских подключений. По умолчанию false (выключено).
        • caCrt: сертификат центра сертификации Apache 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 должен пытаться обновить статус лицензии, если ему не удается его получить.

  3. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-tiles.yaml.

    helm upgrade --install --version=1.10.0 --atomic --wait --timeout 7200 --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api

    Процесс импорта (Kubernetes Importer job) получит все необходимые данные из хранилища артефактов установки и далее импортирует эти данные в Apache Casssandra. Затем Helm выполнит установку самого сервиса.

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

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

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

    values-mapgl.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise

env:
    MAPGL_HOST: mapgl-js-api.example.com
    MAPGL_TILES_API: tiles-api.example.com
    MAPGL_KEYSERVER: keys.example.com
    MAPGL_TRAFFICSERVER: traffic-proxy.example.com
    MAPGL_FLOORSSERVER: floors-api.example.com

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

ingress:
    hosts:
        - host: mapgl-js-api.example.com
    tls:
        - hosts:
              - mapgl-js-api.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.
      • MAPGL_FLOORSSERVER: доменное имя сервиса Floors API.

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

    • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. Обратите внимание, что для использования TLS необходимо создать секрет, содержащий сертификат и приватный ключ.

  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-mapgl.yaml:

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

Установка сервиса Floors API (опционально)

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

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

    values-floors-api.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

ingress:
    hosts:
        - host: floors-api.example.com

    Где:

    • dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • dgctlStorage: настройки хранилища артефактов установки.

      • Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
      • manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.

    • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress.

  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-floors-api.yaml:

    helm upgrade --install --version=1.10.0 --atomic --values ./values-floors-api.yaml floors-api 2gis-on-premise/floors-api

    После установки сервиса Floors API запустится процесс импорта данных этажных планов из хранилища артефактов установки на сервер, на котором развернуты docker-образы сервиса.

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

MapGL JS API

Выполните одно из следующих действий:

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

    http://mapgl-js-api.example.com

  • Если вы хотите поменять настройки иницализации карты, создайте файл test.html со следующим содержимым и запустите его в браузере:

    <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-js-api.example.com/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                useRtlTextPlugin: 'always-on', // отображение справа налево текстов на арабском языке
            });
        </script>
    </body>
</html>

    В этом случае опции style и styleOptions не указываются, и их значения будут разрешены по умолчанию относительно 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="//example.com/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                style: '//example.com/style/', //путь к папке со стилями
                styleOptions: {
                    iconsPath: '//example.com/style/icons/', // путь к папке с иконками
                    fontsPath: '//example.com/style/fonts/', // путь к папке со шрифтами
                    modelsPath: '//example.com/style/models/', // путь к папке с моделями
                },
                useRtlTextPlugin: 'always-on', // отображение справа налево текстов на арабском языке
            });
        </script>
    </body>
</html>

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

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

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

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

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

Floors API

Для проверки работоспособности сервиса Floors API необходимо, чтобы здание, связанное с комплексом этажей, попало во видимую область на карте. См. пример работы с этажными планами.

Что дальше?