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

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

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

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

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

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

   • Документацией сервисов поиска
   • Архитектурой программного комплекса 2ГИС

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

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

3. Соберите необходимые данные, заданные или полученные на предыдущих шагах:

   Объект	Пример значения	Как получить значение
   Endpoint зеркала реестра Docker	docker.storage.example.local:5000	См. Получение артефактов установки
   Секрет Kubernetes для доступа к зеркалу реестра Docker	onpremise-registry-creds	См. Получение артефактов установки
   Домен S3-хранилища с артефактами установки	artifacts.example.com	См. Получение артефактов установки
   Название бакета с артефактами установки	onpremise-artifacts	См. Получение артефактов установки
   Идентификатор ключа для доступа к артефактам установки	AKIAIOSFODNN7EXAMPLE	См. Получение артефактов установки
   Секрет ключа для доступа к артефактам установки	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	См. Получение артефактов установки
   Путь к файлу манифеста	manifests/api-platform/1640661259.json	См. Получение артефактов установки
   Endpoint сервиса лицензий	https://license	См. Установка сервиса лицензий
   Endpoint сервиса API-ключей	http://keys-api	См. Установка сервиса API-ключей
   Endpoint сервиса сбора статистики	http://stat-receiver	См. Установка сервиса сбора статистики
   Сервисный токен	CATALOG_APIS_TOKEN	См. Установка сервиса API-ключей

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

   • Search API,
   • Catalog APIs.

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

   Примечание

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

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

   Пример:

   • Доменное имя для Search API: search-api.example.com
   • Доменное имя для Catalog APIs: catalog-api.example.com

2. Подготовьте инфраструктуру

Настройте PostgreSQL

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

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

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

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

   create user dbuser_catalog password '650D7AmZjSR1dkNa';

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

   create database onpremise_catalog owner dbuser_catalog;

4. Установите необходимые внешние расширения JsQuery и PostGIS для PostgreSQL.

   Вы можете получить расширения из репозиториев, в которых они доступны в виде готовых пакетов. Например, для дистрибутивов на базе Debian/Ubuntu установка выполняется командами:

   sudo apt install postgresql-15-jsquery

   sudo apt install postgresql-15-postgis-3
   sudo apt install postgis

5. Включите требуемые расширения для базы данных:

   \c onpremise_catalog
   
   create schema extensions;
   grant usage on schema extensions to public;
   grant execute on all functions in schema extensions to public;
   alter default privileges in schema extensions grant execute on functions to public;
   alter default privileges in schema extensions grant usage on types to public;
   create extension if not exists plpgsql with schema pg_catalog;
   create extension if not exists jsquery with schema extensions;
   create extension if not exists postgis with schema extensions;

Для установки Catalog APIs

Если вы планируете устанавливать Catalog APIs, добавьте первого партнёра и создайте для него API-ключ. См. инструкцию Управление доступом к API.

Наличие ключа проверяется перед установкой Catalog APIs. В список доступных сервисов для ключа должны быть включены API поиска.

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

Установите сервис Search API

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

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

   values-search.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   dgctlStorage:
       host: artifacts.storage.example.local:443
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/api-platform/1640661259.json
       secure: false
       region: ''
   
   api:
       resources:
           limits:
               cpu: 1
               memory: 3G
           requests:
               cpu: 100m
               memory: 1G
   nginx:
       resources:
           limits:
               cpu: 1
               memory: 1G
           requests:
               cpu: 100m
               memory: 200Mi
   
   ingress:
       enabled: true
       className: nginx
       hosts:
           - host: search-api.example.com
             paths:
                 - path: /
                   pathType: Prefix
       tls: []
       #- hosts:
       #  - search-api.example.com
       #  secretName: secret.tls
   
   customCAs:
       bundle: ''
       # bundle: |
       #   -----BEGIN CERTIFICATE-----
       #   ...
       #   -----END CERTIFICATE-----
       certsPath: ''

   Где:

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

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

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

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

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

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

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

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

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

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

   В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

Установите сервис Catalog APIs

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

   Примечание:

   Вы можете настроить процесс импорта новых данных для Catalog APIs. За это отвечают настройки группы importer конфигурационного файла (см. ниже).

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

   values-catalog.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   dgctlStorage:
       host: artifacts.storage.example.local:443
       bucket: onpremise-artifacts
       accessKey: AKIAIOSFODNN7EXAMPLE
       secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
       manifest: manifests/api-platform/1640661259.json
       secure: false
       region: ''
       verifySsl: true
   
   api:
       postgres:
           host: catalog-postgresql.storage.example.local
           port: 5432
           name: onpremise_catalog
           username: dbuser_catalog
           password: 650D7AmZjSR1dkNa
       ingress:
           enabled: true
           className: nginx
           hosts:
               - host: catalog-api.example.com
                 paths:
                     - path: /
                       pathType: Prefix
           tls: []
           #- hosts:
           #  - catalog-api.example.com
           #  secretName: secret.tls
   
   search:
       url: http://search-api
   
   keys:
       url: http://keys-api
       token: CATALOG_APIS_TOKEN
   
   stat:
       url: 'http://stat-receiver'
       enabled: false
       request:
         enabled: false
       search:
         enabled: false
   
   importer:
       postgres:
           host: catalog-postgresql.storage.example.local
           port: 5432
           name: onpremise_catalog
           username: dbuser_catalog
           password: 650D7AmZjSR1dkNa
           schemaSwitchEnabled: true
       cleaner:
           enabled: true
           versionLimit: 2
   
   license:
       url: 'https://license'
       requestTimeout: 1s
   
   customCAs:
       bundle: ''
       # bundle: |
       #   -----BEGIN CERTIFICATE-----
       #   ...
       #   -----END CERTIFICATE-----
       certsPath: ''

   Где:

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

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

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

     • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
     • manifest: укажите путь до файла с манифестом в формате manifests/api-platform/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • region: регион S3-хранилища.
     • verifySsl: включить ли проверку SSL-сертификатов при подключении к dgctlStorage.host по HTTP. Значение по умолчанию: true.

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

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

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

   • search: настройки доступа к сервису Search API.

     • url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.

   • keys: настройки сервиса ключей.

     • url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
     • token: сервисный токен для сохранения статистики использования (см. Установка сервиса API-ключей).

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

     • url: URL сервиса сбора статистики.
     • enabled: включите, чтобы отправлять статистику использования ключей.
     • request.enabled: включите, чтобы отправлять статистику по запросам к API.
     • search.enabled: включите, чтобы отправлять данные по поисковым запросам.

   • importer: настройки процесса импорта (Kubernetes Importer job). Импорт новых наборов данных происходит, только если для указанного манифеста не происходил импорт ранее.

     • postgres: настройки доступа к серверу PostgreSQL для импорта новых данных об объектах.

       • host: имя хоста или IP-адрес сервера.
       • port: порт, на котором слушает сервер.
       • name: имя базы данных.
       • username: имя пользователя.
       • password: пароль пользователя.
       • schemaSwitchEnabled: разрешить ли работу со схемами.
         • true: каждый импорт данных происходит в новую схему, возможно переключение на старые схемы и их очистка.
         • false: создание новых схем и очистка базы производятся администратором вручную.

       Подробнее см. в разделе Обновление сервиса Catalog APIs.

     • cleaner: настройки автоматического удаления старых наборов данных.

       • enabled: включено ли автоматическое удаление старых наборов данных. Подробнее см. в разделе Обновление сервиса Catalog APIs.
       • versionLimit: количество старых наборов данных, которые нужно хранить.

       См. Жизненный цикл артефактов установки для получения дополнительной информации о работе процесса импорта.

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

     • url: URL-адрес сервиса лицензий. Пример: https://license.
     • requestTimeout: период времени для запроса сервиса лицензий.

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

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

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

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

   В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

   Если в конфигурационном файле были указаны настройки importer, то при установке сервиса проверяется наличие данных в базе и при необходимости происходит импорт этих данных в PostgreSQL. Затем Helm выполняет установку самого сервиса.

4. Проверьте работоспособность установленных сервисов

Проверьте сервис Search API

Чтобы проверить работоспособность сервиса Search API, выполните GET-запрос к endpoint status:

curl search-api.example.com/v2/status?f=common

Проверьте сервис Catalog APIs

Чтобы проверить работоспособность сервиса Catalog APIs, с хоста в приватной сети example.com:

1. С помощью веб-интерфейса управления API-ключами создайте API-ключ, который предоставляет доступ к Places API и Regions API.

2. Выполните следующий GET-запрос, заменив:

   • API_KEY на значение созданного ключа.
   • City на имя любого города, о котором вы хотите найти информацию.

   curl catalog-api.example.com/3.0/items/geocode?key=API_KEY&q=City

   Если запрос выполнен успешно, то сервисы, необходимые для работы поиска, работают корректно.

Что дальше?

• Ознакомьтесь с документацией API для работы с поиском:

  • Places API,
  • Geocoder API,
  • Suggest API,
  • Categories API,
  • Regions API.

• Узнайте, как обновить API для работы с поиском.

• Установите другие продукты программного комплекса 2ГИС:

  • API для работы с картами,
  • API для работы с навигацией,
  • 2ГИС Про,
  • 2ГИС Ситискан,
  • мобильный SDK,
  • GIS-платформа,
  • прокси для API пробок,
  • Менеджер Платформы.

• Изучите рекомендации по обслуживанию системы.