Перейти к основному содержимому

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

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

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

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

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

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

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

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

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

    ОбъектПример значенияКак получить значение
    Endpoint зеркала реестра Dockerdocker.storage.example.local:5000См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Dockeronpremise-registry-credsСм. Получение артефактов установки
    Домен S3-хранилища с артефактами установкиartifacts.example.comСм. Получение артефактов установки
    Название бакета с артефактами установкиonpremise-artifactsСм. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установкиAKIAIOSFODNN7EXAMPLEСм. Получение артефактов установки
    Секрет ключа для доступа к артефактам установкиwJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYСм. Получение артефактов установки
    Путь к файлу манифестаmanifests/1640661259.jsonСм. Получение артефактов установки
    Endpoint сервиса лицензийhttps://licenseСм. Установка сервиса лицензий
    Endpoint сервиса API-ключейhttp://keys-apiСм. Установка сервиса API-ключей
    Endpoint прокси для API пробокhttp://traffic-proxyСм. Установка прокси для API пробок
    Сервисные токеныTILES_VECTOR_TOKEN, TILES_RASTER_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
    • Доменное имя для Tilegen API: tilegen-api.example.com
    • Доменное имя для Styles API: styles.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

Настройте Redis для Tilegen API​

  1. Разместите Redis в приватной сети.

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

    Пример:

    • Имя пользователя: redisuser
    • Пароль: REDISPASSWORD-KFY87TSM0JD10LD

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

Настройте S3-совместимое хранилище, если вы планируете установить Tilegen API или Styles API. Если вам необходимо установить оба сервиса, вы можете настроить разные серверы S3 или использовать один, но с разными бакетами.

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

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

    • Access key: ``

    • Secret key: ``

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

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

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

Настройте 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;

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
        region: ''
        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_ONE
        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
            vector:
                token: 'TILES_VECTOR_TOKEN'
            raster:
                token: 'TILES_RASTER_TOKEN'

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

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

    # Если вы планируете использовать Tilegen API
    tilegen:
        enabled: true
        tileset:
            name: userdata
            keyspace: dgis_userdata

    Где:

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

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

      • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • region: регион S3-хранилища.
      • 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-endpoint сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • access.vector.token: отдельный сервисный токен для доступа к векторным данным Tiles API. Этот ключ можно получить с помощью утилиты keysctl.
      • access.raster.token: отдельный сервисный токен для доступа к растровым данным Tiles Raster API. Этот ключ можно получить с помощью утилиты keysctl.

    • license: настройки сервиса лицензий.

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

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

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

    • tilegen: настройки для взаимодействия с сервисом Tilegen API.

      • enabled: использовать ли Tilegen API.

      • tileset: параметры набора тайлов.

        • name: имя набора тайлов.
        • keyspace: название пространства ключей в БД.

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

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

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

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

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

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

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

    imagePullSecrets: [onpremise-registry-creds]

    s3:
        host: 's3.storage.example.local'
        accessKey: ''
        secretKey: ''
        vectorTilesBucket: 'tiles'

    redis:
        host: 'redis.example.local'
        port: 6379

    tilesImporter:
        hosts: 'tiles1.importer.host,tiles2.importer.host'

    Где:

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

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

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

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

    • redis: настройки взаимодействия с Redis.

      • host: имя или IP-адрес хоста Redis.
      • port: порт Redis.

    • tilesImporter: настройки импорта тайлов.

      • hosts: список имен хостов для импорта тайлов через запятую.

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

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

Установите сервис 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: 's3.storage.example.local:80'
        accessKey: ''
        secretKey: ''
        bucket: 'styles'
        publicDomain: ''
        region: ''
        secure: false
        verifySsl: false

    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: endpoint вашего реестра 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.
      • region: регион S3-хранилища.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • verifySsl: включить ли проверку SSL-сертификатов. Значение по умолчанию: false.

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

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

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

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

    imagePullSecrets: [onpremise-registry-creds]

    env:
        MAPGL_DEMO_KEY: ''
        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_STYLESERVER: https://styles.ingress.host
        MAPGL_ICONS_URL: https://s3.ingress.host/styles/assets/icons
        MAPGL_MODELS_URL: https://s3.ingress.host/styles/assets/models
        MAPGL_KEYSERVER: https://keys-api.example.com/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: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

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

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

      • MAPGL_DEMO_KEY: API-ключ для доступа к сервису. Должен быть сгенерирован с помощью сервиса API-ключей.
      • MAPGL_HOST: URL сервиса, который ваши приложения должны использовать для коммуникаций с сервисами карт.
      • MAPGL_TILES_API: URL сервиса Tiles API.
      • MAPGL_TILESET: подложка сервиса Tiles API с векторными тайлами.
      • MAPGL_IMMERSIVE_TILESET: подложка сервиса Tiles API с тайлами для отображения 3D-моделей.
      • MAPGL_TRAFFICSERVER: URL сервиса прокси для API пробок.
      • MAPGL_STYLESERVER: URL сервиса Styles API.
      • MAPGL_ICONS_URL: URL директории с иконками для стилей. URL должен быть публично доступен.
      • MAPGL_MODELS_URL: URL директории с моделями для стилей. 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.32.0 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api

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

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

Tilegen API​

Отправьте GET-запрос на endpoint Tilegen API:

curl -X 'GET' \
  'https://tilegen-api.example.com/version' \
  -H 'accept: */*'

В ответе вы должны получить номер версии сервиса.

Styles API​

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

Что дальше?​