Сервис API-ключей | On-Premise | 2GIS Documentation
On-Premise

Установка сервиса API-ключей

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

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

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

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

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

    1. Подготовка к установке
    2. Получение артефактов установки
  3. Соберите необходимые данные, заданные или полученные на предыдущих шагах:

    Объект Значение Как получить значение
    Эндпоинт зеркала реестра Docker в приватной сети docker.storage.example.local:5000 См. Получение артефактов установки
    Секрет Kubernetes для доступа к эндпоинту зеркала реестра Docker onpremise-registry-creds См. Получение артефактов установки
  4. Убедитесь, что удовлетворены следующие требования к ресурсам (требования приведены с учётом минимального числа реплик):

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

      Сервис vCPU RAM Хранилище
      Frontend 2 2 ГБ
      Backend 2 2 ГБ Apache Kafka
      PostgreSQL
      Redis
      Apache Kafka + ZooKeeper 12 12 ГБ 500 ГБ*
      PostgreSQL 6 12 ГБ 200 ГБ
      Итоговое количество: 22 28 ГБ 700 ГБ
    • Для production-окружения:

      Сервис vCPU RAM Хранилище
      Frontend 2 2 ГБ
      Backend 2 2 ГБ Apache Kafka
      PostgreSQL
      Redis
      Apache Kafka + ZooKeeper 24 36 ГБ 500 ГБ*
      PostgreSQL 6 12 ГБ 200 ГБ
      Итоговое количество: 34 28 ГБ 700 ГБ

    * Эти требования к хранилищу могут меняться в зависимости от настроенного временного периода для хранения статистики. Чем больше этот период, тем больший объем хранилища потребуется.

    Примечание:

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

  5. Определите доменные имена для сервиса API-ключей.

    Пример:

    • Веб-интерфейс администратора: keys-api.example.com
    • API-бэкенд: keys.example.local

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

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

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

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

    create user keys_superuser_rw password 'KEYS_Db_Owner_Password_1234';
    create user keys_user_ro password 'KEYS_Db_RO_User_Password_5678';
    
  3. Создайте базу данных, принадлежащую одному из пользователей.

    create database onpremise_keys owner keys_superuser_rw;
    
  4. Добавьте ограниченные права к этой базе данных другому пользователю.

    \c onpremise_keys
    
    ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON TABLES TO keys_user_ro;
    ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON SEQUENCES TO keys_user_ro;
    

Чтобы сервисы могли выполнять аутентификацию администраторов сервиса API-ключей, рекомендуется использовать LDAP-сервер (например, Microsoft Active Directory). Этот шаг можно пропустить, если у вас нет возможности развернуть LDAP-сервер и вы собираетесь использовать аутентификацию по plaintext-паролям в конфигурационном файле.

Разместите LDAP-сервер с доменным именем keys-ldap.storage.example.local в приватной сети. В этом руководстве предполагается, что сервер работает на стандартном порту 3268.

  1. Получите значения необходимых настроек LDAP.

    Настройка Пример значения
    Пользователь для подключения к службе LDAP keys_ldap_user
    Пароль пользователя для подключения к службе LDAP KEYS_LDAP_PaSSw0rd_8901
    Основное уникальное имя (base relative distinguished name), относительно которого выполняется поиск в каталоге LDAP dc=2gis
    Фильтр LDAP, используемый для идентификации записей в поисковых запросах (&(objectClass=user)(sAMAccountName=%s))
  2. Добавьте в LDAP пользователя admin, которому будет назначена роль администратора в сервисе API-ключей.

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

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

    values-keys.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    
    postgres:
        ro:
            host: keys-postgresql.storage.example.local
            port: 5432
            name: onpremise_keys
            username: keys_superuser_ro
            password: KEYS_Db_RO_User_Password_5678
        rw:
            host: keys-postgresql.storage.example.local
            port: 5432
            name: onpremise_keys
            username: keys_superuser_rw
            password: KEYS_Db_Owner_Password_1234
    
    ldap:
        host: ldap.keys.example.local
        port: 3268
    
        useStartTLS: false
        useLDAPS: false
        skipServerCertificateVerify: false
        serverName: ldap.keys.example.local
        clientCertificatePath: /home/user/certificates/cert.crt
        clientKeyPath: /home/user/certificates/cert.key
        rootCertificateAuthoritiesPath: /home/user/certificates/root.cer
    
        bind:
            dn: keys_ldap_user
            password: KEYS_LDAP_PaSSw0rd_8901
    
        search:
            baseDN: dc=2gis
            filter: (&(objectClass=user)(sAMAccountName=%s))
    
    tasker:
        resources:
            requests:
                cpu: 10m
                memory: 32Mi
            limits:
                cpu: 100m
                memory: 64Mi
    
        delay: 30s
    
    admin:
        api: http://keys-api.example.local
        host: https://keys.example.com
    
    api:
        adminUsers: 'admin:8k7RVCP8m3AABDzD'
    

    Где:

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

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

      Сервис API-ключей работает с данными в двух режимах: только чтение (ro) и чтение-запись (rw). В обоих режимах сервис работает с одной базой, но от имени пользователей с разными правами (см. подробности в шаге 1).

      Задайте:

      • Настройки, общие для обоих режимов:

        • host: имя хоста или IP-адрес сервера.
        • port: порт, на котором слушает сервер.
        • name: имя базы данных.
      • Реквизиты для доступа к базе пользователя с правами только на чтение (секция ro).

      • Реквизиты для доступа к базе пользователя с правами на чтение и запись (секция rw).

      Для хранения настроек password в группах ro и rw Helm-чарт использует Kubernetes Secrets.

    • ldap: настройки доступа к серверу LDAP.

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

      • port: порт, на котором слушает сервер.

      • Группа настроек для обеспечения защищенного соединения с сервером LDAP:

        • useStartTLS: использовать StartTLS.
        • useLDAPS: использовать Secure LDAP.
        • skipServerCertificateVerify: не проверять сертификат сервера.
        • serverName: строка с именем сервера. Используется при проверке сертификата сервера.
        • clientCertificatePath: путь к сертификату клиента.
        • clientKeyPath: путь к ключу клиента.
        • rootCertificateAuthoritiesPath: путь к файлу с корневыми сертификатами от центров сертификации (root certificate authorities).
      • bind: реквизиты для доступа к серверу LDAP:

        • dn: уникальное имя пользователя (distinguished name).
        • password: пароль пользователя.
      • search: настройки поиска LDAP:

        • baseDN: основное относительное уникальное имя (base relative distinguished name).
        • filter: фильтр LDAP, используемый для идентификации записей в поисковых запросах.
    • tasker: настройки сервиса Tasker, который выполняет административные задачи, связанные с API-ключами.

      • resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
      • delay: период (в секундах). Эта настройка определяет, с каким периодом проверять задачи, которые связаны с настроенными отложенными действиями (например, блокировкой API-ключа).
    • admin: настройки веб-сервиса администратора (предоставляет доступ к веб-интерфейсу для администрирования сервиса).

      • api: URL бэкенда сервиса API-ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • host: URL фронтенда сервиса API-ключей. Этот URL должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
    • api.adminUsers: список реквизитов пользователей с административными правами в формате username1:password1,username2:password2,....

      Для хранения этой настройки Helm-чарт использует Kubernetes Secrets.

      Примечание:

      Если у вас есть сервер LDAP, то рекомендуется использовать его для аутентификации, а настройку api.adminUsers пропустить.

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

    helm upgrade --install --version=1.4.5 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
    
  3. Добавьте пользователей в сервис с помощью утилиты keysctl. Этим пользователям будет назначена роль администратора сервиса API-ключей.

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

    При использовании LDAP достаточно добавить одного пользователя. При использовании списка реквизитов (настройка api.adminUsers) необходимо добавить всех пользователей из этого списка.

    Чтобы добавить одного пользователя, выполните эту команду из любого пода keys-api:

    keysctl users add admin 'Keys Service Admin'
    

Каждый сервис, который интегрируется с сервисом API-ключей, обязан отправлять информацию об использовании ключей конечными пользователями на бэкенд сервиса API-ключей. Чтобы сервис мог взаимодействовать с этим бэкендом, нужно во время конфигурации сервиса задать сервисный токен.

Выполните следующую команду из любого пода keys-api, чтобы получить список доступных сервисных ключей.

keysctl services

Чтобы проверить работоспособность сервиса API-ключей:

  1. Откройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки admin.host из конфигурационного файла values-keys.yaml):

    https://keys.example.com/
    
  2. Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора (это пользователь, которому была назначена роль администратора с помощью утилиты keysctl). Вы должны увидеть веб-интерфейс для управления API-ключами.

Что дальше?