API карт | On-Premise | 2GIS Documentation
On-Premise
Карты
Поиск
Навигация
On-Premise
2ГИС Про
CityLens
ру
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 См. Получение артефактов установки
    Эндпоинт сервиса лицензий https://license См. Установка сервиса лицензий
    Эндпоинт сервиса API-ключей http://keys-api См. Установка сервиса API-ключей
    Эндпоинт прокси для API пробок http://traffic-proxy См. Установка прокси для API пробок
    Сервисные токены TILES_TOKEN См. Установка сервиса API-ключей

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

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

    Примечание

    Содержание Helm-чартов, описанное в данном разделе, актуально для последней версии On-Premise (см. Релизы). Чтобы изучить параметры для более ранних версий, откройте нужный values.yaml в GitHub и введите номер нужной версии комплекса (например, 1.18.0) в переключателе тегов слева.

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

    Пример:

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

Настройка PostgreSQL для Styles API

Разместите кластер PostgreSQL с доменным именем styles-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.

Настройте кластер PostgreSQL для использования в качестве хранилища:

  1. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

  2. Создайте пользователя базы данных и установите пароль для него:

    create user dbuser_styles password '';

  3. Создайте базу данных, принадлежащую этому пользователю:

    create database onpremise_styles owner dbuser_styles;

Настройка S3-хранилища для Styles API

Разместите S3-совместимое хранилище (например, Ceph) с доменным именем styles-s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.

Настройте S3-совместимое хранилище:

  1. Создайте пользователя, который будет использоваться для сервиса:

    • Access key: ``
    • Secret key: ``

    Запомните ключи доступа для этого пользователя.

  2. Определите название бакета (bucket), который будет использоваться для сервиса (например, styles).

    Бакет должен быть публичным и иметь правильно настроенный CORS, чтобы файлы из него были доступны для загрузки из браузера с произвольного хоста.

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

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

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

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

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

    values-tiles.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

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:
    environment: ''
    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

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:
        enabled: true
        className: nginx
        hosts:
            - host: tiles-api.example.com
              paths:
                  - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - tiles-api.example.com
        #  secretName: secret.tls

proxy:
    access:
        enabled: true
        url: http://keys-api
        token: TILES_TOKEN

license:
    url: 'https://license'
    retryPeriod: 30s

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''

    Где:

    • 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.

      • environment: имя окружения, не более 7 символов.
      • 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 (выключено).

    • 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-адрес сервиса лицензий. Пример: https://license.
      • retryPeriod: как часто Tiles API должен пытаться обновить статус лицензии, если ему не удается его получить.

    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.

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

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

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

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

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

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

    values-styles.yaml 
    
dgctlDockerRegistry: docker.storage.example.local:5000

log:
    level: info

postgres:
    host: 'styles-postgresql.storage.example.local'
    name: 'onpremise_styles'
    username: ''
    password: ''

s3:
    host: 'styles-s3.storage.example.local:80'
    accessKey: ''
    secretKey: ''
    bucket: 'styles'
    publicDomain: ''

api:
    resources:
        requests:
            cpu: 50m
            memory: 128Mi
        limits:
            cpu: 1
            memory: 256Mi

    ingress:
        enabled: true
        className: nginx
        hosts:
            - host: styles.example.com
            paths:
                - path: /
                    pathType: Prefix
        tls: []
        #- hosts:
        #  - styles-api.example.com
        #  secretName: secret.tls

    Где:

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

    • log.level: уровень логирования.

    • postgres: настройки доступа к серверу PostgreSQL.

      • host: имя или IP-адрес хоста PostgreSQL.
      • name: имя базы данных.
      • username: имя пользователя базы данных PostgreSQL.
      • password: пароль для подключения к базе данных PostgreSQL.

    • s3: настройки S3-совместимого хранилища.

      • host: endpoint S3-совместимого хранилища.
      • accessKey: идентификатор ключа (S3 access key).
      • secretKey: секретный ключ (S3 secret key).
      • bucket: имя бакета.
      • publicDomain: домен для публичного доступа к хранилищу по протоколу HTTPS.

    • api.resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

    • api.ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

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

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

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

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

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

    values-mapgl.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

env:
    MAPGL_HOST: https://mapgl-api.ingress.host
    MAPGL_TILES_API: https://tiles-api.ingress.host
    MAPGL_TILESET: web
    MAPGL_IMMERSIVE_TILESET: web_immersive
    MAPGL_TRAFFICSERVER: https://traffic-proxy.ingress.host
    MAPGL_FLOORSSERVER: https://floors-api.ingress.host
    MAPGL_STYLESERVER: https://styles.ingress.host
    MAPGL_ICONSPATH: https://styles.ingress.host/styles/assets/icons
    MAPGL_MODELSPATH: https://styles.ingress.host/styles/assets/models
    MAPGL_KEYSERVER: https://keys-api.ingress.host/public/v1/keys/{keyID}/services/mapgl-js-api
    MAPGL_RTLPLUGIN: https://mapgl-api.ingress.host/api/js/plugins/rtl-v1.0.0.js
    MAPGL_RTLPLUGINHASH:
    MAPGL_INVALID_KEY_MESSAGE: Your MapGL key is invalid.

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

ingress:
    enabled: true
    className: nginx
    hosts:
        - host: mapgl-js-api.example.com
          paths:
              - path: /
                pathType: Prefix
    tls: []
    #- hosts:
    #  - mapgl-js-api.example.com
    #  secretName: secret.tls

    Где:

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

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

    • env: переменные окружения.

      • MAPGL_HOST: URL сервиса, который ваши приложения должны использовать для коммуникаций с сервисами карт.
      • MAPGL_TILES_API: URL сервиса Tiles API.
      • MAPGL_TILESET: подложка сервиса Tiles API с векторными тайлами.
      • MAPGL_IMMERSIVE_TILESET: подложка сервиса Tiles API с тайлами для отображения 3D-моделей.
      • MAPGL_TRAFFICSERVER: URL сервиса прокси для API пробок.
      • MAPGL_FLOORSSERVER: URL сервиса Floors API.
      • MAPGL_STYLESERVER: URL сервиса Styles API.
      • MAPGL_ICONSPATH: URL директории с иконками для стилей.
      • MAPGL_MODELSPATH: URL директории с моделями для стилей.
      • MAPGL_KEYSERVER: URL сервиса API-ключей.
      • MAPGL_RTLPLUGIN: URL плагина для поддержки языков с направлением письма справа налево (RTL).
      • MAPGL_RTLPLUGINHASH: SHA512-хеш плагина для поддержки RTL-языков.
      • MAPGL_INVALID_KEY_MESSAGE: текст сообщения об ошибке при использовании невалидного ключа для MapGL JS API.

    • resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

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

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

    helm upgrade --install --version=1.28.2 --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

dgctlStorage:
    host: artifacts.example.com
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json
    secure: false
    region: ''
    usePathStyle: true

ingress:
    enabled: true
    className: nginx
    hosts:
        - host: floors.example.com
          paths:
              - path: /
                pathType: Prefix
    tls: []
    #- hosts:
    #  - floors.example.com
    #  secretName: secret.tls

    Где:

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

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

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

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

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

    helm upgrade --install --version=1.28.2 --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>

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

    В этом случае опции style и styleOptions не указываются, и их значения будут разрешены по умолчанию относительно MAPGL_HOST. Если вы планируете использовать собственные стили, см. проверку Styles API.

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

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

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

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

Styles API

Чтобы подключить пользовательский стиль карты, установите Platform Manager и выполните шаги по загрузке и применению стиля.

Floors API

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

Что дальше?