Сервис API-ключей | On‑Premise | 2GIS Documentation
On‑Premise
Личный кабинет

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

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

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

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

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

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

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

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

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

    Примечание

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

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

    Пример: keys.example.com

Разместите кластер PostgreSQL с доменным именем 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
    
    dgctlStorage:
        host: artifacts.storage.example.local:443
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
        verifySsl: true
    
    postgres:
        ro:
            host: keys-postgresql.storage.example.local
            port: 5432
            name: onpremise_keys
            username: keys_user_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.com
        port: 3268
    
        useStartTLS: false
        useLDAPS: false
        skipServerCertificateVerify: false
        serverName: ldap.keys.example.com
        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:
        host: https://keys.example.com
    
        ingress:
            enabled: true
            className: nginx
            hosts:
                - host: keys.example.com
                  paths:
                      - path: /
                        pathType: Prefix
            tls: []
            #- hosts:
            #  - keys.example.com
            #  secretName: secret.tls
    
    api:
        adminUsers: 'admin:8k7RVCP8m3AABDzD'
    
    customCAs:
        bundle: ''
        # bundle: |
        #   -----BEGIN CERTIFICATE-----
        #   ...
        #   -----END CERTIFICATE-----
        certsPath: ''
    

    Где:

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

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

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

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

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

    • api.adminUsers: список реквизитов пользователей с административными правами в формате username1:password1,username2:password2,....

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

      Примечание:

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

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

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

    helm upgrade --install --version=1.32.0 --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-ключами.

Что дальше?