API карт | On-Premise | 2GIS Documentation
On-Premise

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

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

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

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

  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 пробок http://traffic-proxy См. Установка прокси для API пробок
    Сервисные токены TILES_TOKEN См. Установка сервиса ключей
  4. Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чартах:

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

    Примечание

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

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

    Пример:

    • Доменное имя для Tiles API: tiles-api.example.com
    • Доменное имя для MapGL JS API: mapgl-js-api.example.com
    • Доменное имя для Floors API: floors.example.com

Разместите один или несколько инстансов хранилища 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
  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.24.0 --atomic --wait --timeout 7200s --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
    

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

  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_KEYSERVER: https://keys-api.ingress.host/public/v1/keys/{keyID}/services/mapgl-js-api
        MAPGL_TRAFFICSERVER: traffic-jams.2gis.com
        MAPGL_FLOORSSERVER: https://floors-api.ingress.host
    
    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 сервиса. Ваши приложения должны использовать этот URL (или IP-адрес) для коммуникаций с сервисами карт.
      • MAPGL_TILES_API: URL сервиса Tiles API.
      • MAPGL_KEYSERVER: URL сервиса ключей.
      • MAPGL_TRAFFICSERVER: доменное имя публичного сервера 2ГИС, предоставляющего данные о пробках, или прокси для API пробок. Сервер по умолчанию: traffic-jams.2gis.com.
      • MAPGL_FLOORSSERVER: URL сервиса Floors API.
    • resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

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

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

    helm upgrade --install --version=1.24.0 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-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.24.0 --atomic --values ./values-floors-api.yaml floors-api 2gis-on-premise/floors-api
    

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

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

  • Перейдите в браузере по доменному имени или 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, который работает с растровыми тайлами, перейдите в браузере по адресу (приведён пример для Москвы):

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

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

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

Что дальше?