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

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

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

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

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

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

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

    1. Подготовка к установке
    2. Получение артефактов установки
    3. Установка сервиса ключей
    4. Установка прокси для API пробок
  3. Ознакомьтесь с важными значениями, заданными или полученными на предыдущих шагах:

    Объект Пример значения Как получить значение
    Эндпоинт зеркала реестра Docker docker.storage.example.local:5000 См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Docker onpremise-registry-creds См. Получение артефактов установки
    Домен S3-хранилища с артефактами установки artifacts.example.com См. Получение артефактов установки
    Название бакета с артефактами установки onpremise-artifacts См. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE См. Получение артефактов установки
    Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY См. Получение артефактов установки
    Путь к файлу манифеста manifests/1640661259.json См. Получение артефактов установки
    Эндпоинт API сервиса ключей keys.example.local См. Установка сервиса ключей
    Эндпоинт прокси для API пробок traffic-proxy.example.local См. Установка прокси для API пробок
    Сервисные API-ключи MAPGL_JS_KEY_AAAAAA-111111
    TILES_KEY_BBBBBB-222222
    См. Установка сервиса ключей
  4. Убедитесь, что удовлетворены следующие требования к ресурсам (требования приведены с учётом минимального числа реплик):

    • Для testing-окружения:

      Сервис vCPU RAM Хранилище
      MapGL JS API 2 4 ГБ
      Tiles API Backend 2 1 ГБ Apache Cassandra
      Apache Cassandra 3 48 ГБ 500 ГБ
      Задание импорта Kubernetes 1 4 ГБ
      Итоговое количество: 8 57 ГБ 500 ГБ
    • Для production-окружения:

      Сервис vCPU RAM Хранилище
      MapGL JS API 4 4 ГБ
      Tiles API Backend 8 1 ГБ Apache Cassandra
      Apache Cassandra 12 48 ГБ 500 ГБ
      Задание импорта Kubernetes 4 4 ГБ
      Итоговое количество: 28 57 ГБ 500 ГБ

    Примечание:

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

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

    Пример:

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

Разместите один или несколько инстансов хранилища Apache Cassandra в приватной сети.

Рекомендуется включить доступ к Apache Cassandra по протоколу JMX, чтобы разрешить очистку снимков хранилища (см. Обновление сервиса Tiles API).

Пример:

  • Хосты:
    • tiles-cassandra-1.storage.example.local
    • tiles-cassandra-2.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/2gis-on-premise
    
    dgctlStorage:
        host: artifacts.example.com
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
    
    serviceName: tiles-api-raster
    type: raster
    
    cassandra:
        hosts:
            - tiles-cassandra-1.storage.example.local
            - tiles-cassandra-2.storage.example.local
        replicaFactor: 3
        consistencyLevelRead: LOCAL_QUORUM
        consistencyLevelWrite: LOCAL_QUORUM
        credentials:
            user: cassandrauser
            password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN
            jmxUser: jmxuser
            jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8
    
    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.example.com
    
    proxy:
        access:
            enabled: true
            host: http://tiles-api.example.local
            token: TILES_KEY_BBBBBB-222222
    

    Где:

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

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

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

      • для Tiles API с поддержкой векторных тайлов — tiles-api-webgl.
      • для Tiles API с поддержкой растровых тайлов — tiles-api-raster.
    • type: тип сервиса.

      • для Tiles API с поддержкой векторных тайлов — не указывайте значение этого параметра.
      • для Tiles API с поддержкой растровых тайлов — raster.
    • cassandra: настройки хранилища данных Apache Cassandra.

      • hosts: массив из одного и более IP-адресов инсталляции Apache Cassandra.
      • replicaFactor: фактор репликации. Задайте подходящее значение для этой настройки в соответствии с вашей инсталляцией Apache Cassandra.
      • При необходимости задайте подходящее значение для настроек консистентности данных в соответствии с вашей инсталляцией Apache Cassandra. См. документацию Apache Cassandra для получения дополнительной информации.
      • credentials: учётные данные для аутентификации. Значения user и password являются обязательными, а jmxUser и jmxPassword используются только для очистки снимков хранилища (см. Обновление сервиса Tiles API). Значение по умолчанию каждого из параметров - 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.host: URL API-эндпоинта сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • access.token: отдельный сервисный API-ключ сервиса Tiles API. Этот ключ можно получить с помощью утилиты keysctl.
  3. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-tiles.yaml.

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

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

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

    Существующие данные сохраняются в течении короткого промежутка времени только если вы выполняете обновление сервиса, а не первоначальную установку.

    helm upgrade --install --version=1.4.5 --atomic --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/2gis-on-premise
    
    env:
        MAPGL_HOST: mapgl.example.com
        MAPGL_TILES_API: tiles.example.com
        MAPGL_KEYSERVER: keys.example.com
        MAPGL_TRAFFICSERVER: traffic-proxy.example.com
    
    resources:
        requests:
            cpu: 30m
            memory: 32M
        limits:
            cpu: 100m
            memory: 64M
    
    ingress:
        hosts:
            - host: mapgl.example.com
        tls:
            - hosts:
                  - mapgl.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.
    • resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

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

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

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

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

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

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

Примечание:

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

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

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

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

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

Что дальше?