Установка сервиса API-ключей
Важное примечание:
Все пароли и ключи в этом разделе приведены в иллюстративных целях.
При реальной установке рекомендуется использовать более сложные и надёжные пароли.
1. Перед установкой
-
По возможности познакомьтесь с:
-
Убедитесь, что выполнены необходимые предварительные шаги:
-
Соберите необходимые данные, заданные или полученные на предыдущих шагах:
Объект Значение Как получить значение Эндпоинт зеркала реестра Docker в приватной сети docker.storage.example.local:5000
См. Получение артефактов установки Секрет Kubernetes для доступа к эндпоинту зеркала реестра Docker onpremise-registry-creds
См. Получение артефактов установки Домен S3-хранилища с артефактами установки artifacts.example.com
См. Получение артефактов установки Название бакета с артефактами установки onpremise-artifacts
См. Получение артефактов установки Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE
См. Получение артефактов установки Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
См. Получение артефактов установки Путь к файлу манифеста manifests/1640661259.json
См. Получение артефактов установки -
Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чарте. Подробнее о том, как это сделать, смотрите в документе Системные требования.
* Эти требования к хранилищу могут меняться в зависимости от настроенного временного периода для хранения статистики. Чем больше этот период, тем больший объем хранилища потребуется.
Примечание
Содержание Helm-чарта, описанное в данном разделе, актуально для последней версии On-Premise (см. Релизы). Чтобы изучить параметры для более ранних версий, откройте values.yaml в GitHub и введите номер нужной версии комплекса (например, 1.18.0) в переключателе тегов слева.
-
Определите доменные имена для сервиса API-ключей.
Пример:
keys.example.com
2. Подготовьте инфраструктуру, необходимую для работы сервисов
Настройка PostgreSQL
Разместите кластер PostgreSQL с доменным именем keys-postgresql.storage.example.local
в приватной сети. В этом руководстве предполагается, что кластер работает на стандартном порту 5432
.
Настройте кластер PostgreSQL для использования в качестве хранилища:
-
Подключитесь к кластеру от имени суперпользователя (обычно это
postgres
). -
Создайте двух пользователей базы данных, которые будут использоваться для сервиса. Установите пароли для пользователей.
create user keys_superuser_rw password 'KEYS_Db_Owner_Password_1234'; create user keys_user_ro password 'KEYS_Db_RO_User_Password_5678';
-
Создайте базу данных, принадлежащую одному из пользователей.
create database onpremise_keys owner keys_superuser_rw;
-
Добавьте ограниченные права к этой базе данных другому пользователю.
\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;
Настройка LDAP
Чтобы сервисы могли выполнять аутентификацию администраторов сервиса API-ключей, рекомендуется использовать LDAP-сервер (например, Microsoft Active Directory). Этот шаг можно пропустить, если у вас нет возможности развернуть LDAP-сервер и вы собираетесь использовать аутентификацию по plaintext-паролям в конфигурационном файле.
Разместите LDAP-сервер с доменным именем keys-ldap.storage.example.local
в приватной сети. В этом руководстве предполагается, что сервер работает на стандартном порту 3268
.
-
Получите значения необходимых настроек LDAP.
Настройка Пример значения Пользователь для подключения к службе LDAP keys_ldap_user
Пароль пользователя для подключения к службе LDAP KEYS_LDAP_PaSSw0rd_8901
Основное уникальное имя (base relative distinguished name), относительно которого выполняется поиск в каталоге LDAP dc=2gis
Фильтр LDAP, используемый для идентификации записей в поисковых запросах (&(objectClass=user)(sAMAccountName=%s))
-
Добавьте в LDAP пользователя
admin
, которому будет назначена роль администратора в сервисе API-ключей.
3. Установите сервис API-ключей
-
Создайте конфигурационный файл для 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
: директория для монтирования сертификата внутри контейнера.
-
-
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл
values-keys.yaml
:helm upgrade --install --version=1.29.0 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
-
Добавьте пользователей в сервис с помощью утилиты
keysctl
. Этим пользователям будет назначена роль администратора сервиса API-ключей.Важное примечание:
При использовании LDAP достаточно добавить одного пользователя. При использовании списка реквизитов (настройка
api.adminUsers
) необходимо добавить всех пользователей из этого списка.Чтобы добавить одного пользователя, выполните эту команду из любого пода
keys-api
:keysctl users add admin 'Keys Service Admin'
4. Получите сервисные токены
Каждый сервис, который интегрируется с сервисом API-ключей, обязан отправлять информацию об использовании ключей конечными пользователями на бэкенд сервиса API-ключей. Чтобы сервис мог взаимодействовать с этим бэкендом, нужно во время конфигурации сервиса задать сервисный токен.
Выполните следующую команду из любого пода keys-api
, чтобы получить список доступных сервисных ключей.
keysctl services
5. Проверьте работоспособность установленных сервисов
Чтобы проверить работоспособность сервиса API-ключей:
-
Откройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки
admin.host
из конфигурационного файлаvalues-keys.yaml
):https://keys.example.com/
-
Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора (это пользователь, которому была назначена роль администратора с помощью утилиты
keysctl
). Вы должны увидеть веб-интерфейс для управления API-ключами.
Что дальше?
-
Узнайте, как обновить сервис:
-
Установите продукты программного комплекса 2ГИС:
-
Узнайте, как создавать API-ключи: