Установка API для работы с картами
Важное примечание:
Все пароли и ключи в этом разделе приведены в иллюстративных целях.
При реальной установке рекомендуется использовать более сложные и надёжные пароли.
1. Перед установкой
-
По возможности познакомьтесь с:
-
Убедитесь, что выполнены необходимые предварительные шаги:
-
Ознакомьтесь с важными значениями, заданными или полученными на предыдущих шагах:
Объект Пример значения Как получить значение Эндпоинт зеркала реестра 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
См. Установка сервиса ключей -
Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чартах:
Подробнее о том, как это сделать, смотрите в документе Системные требования.
-
Определите доменные имена для сервисов карт.
Пример:
- Доменное имя для Tiles API:
tiles-api.example.com
- Доменное имя для MapGL JS API:
mapgl-js-api.example.com
- Доменное имя для Floors API:
floors-api.example.com
- Доменное имя для Tiles API:
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
-
Выберите вариант Tiles API, который нужно установить: для векторных или растровых тайлов.
-
Создайте конфигурационный файл для 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 должен пытаться обновить статус лицензии, если ему не удается его получить.
-
-
Установите сервис с помощью 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
-
Создайте конфигурационный файл для 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 необходимо создать секрет, содержащий сертификат и приватный ключ.
-
-
Установите сервис с помощью 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 (опционально)
-
Создайте конфигурационный файл для 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.
-
-
Установите сервис с помощью 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 необходимо, чтобы здание, связанное с комплексом этажей, попало во видимую область на карте. См. пример работы с этажными планами.
Что дальше?
-
Узнайте, как обновить сервисы карт:
-
Установите другие продукты программного комплекса 2ГИС: