Развёртывание коннекторов ко внешним источникам данных

Коннекторы - специальные микросервисы, предоставляющие YDB универсальную абстракцию доступа ко внешним источникам данных. Коннекторы выступают в качестве точек расширения системы обработки федеративных запросов YDB. В данном руководстве мы рассмотрим особенности развёртывания коннекторов в режиме on-premise.

fq-connector-go

Коннектор fq-connector-go реализован на языке Go; его исходный код размещён на GitHub. Он обеспечивает доступ к следующим источникам данных:

• ClickHouse
• PostgreSQL

Коннектор может быть установлен с помощью бинарного дистрибутива или с помощью Docker-образа.

Запуск из бинарного дистрибутива

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

1. На странице с релизами коннектора выберите последний релиз, скачайте архив для подходящей вам платформы и архитектуры. Так выглядит команда для скачивания коннектора версии v0.2.4 под платформу Linux и архитектуру процессора amd64:

   mkdir /tmp/connector && cd /tmp/connector
   wget https://github.com/ydb-platform/fq-connector-go/releases/download/v0.2.4/fq-connector-go-v0.2.4-linux-amd64.tar.gz
   tar -xzf fq-connector-go-v0.2.4-linux-amd64.tar.gz
   

2. Если на сервере ещё не были развёрнуты узлы YDB, создайте директории для хранения исполняемых и конфигурационных файлов:

   sudo mkdir -p /opt/ydb/bin /opt/ydb/cfg
   

3. Разместите разархивированные исполняемый и конфигурационный файлы коннектора в только что созданные директории:

   sudo cp fq-connector-go /opt/ydb/bin
   sudo cp fq-connector-go.yaml /opt/ydb/cfg
   

4. В рекомендуемом режиме использования коннектор развёртывается на тех же серверах, что и динамические узлы YDB, следовательно, шифрование сетевых соединений между ними не требуется. Однако если вам всё же необходимо включить шифрование, подготовьте пару TLS-ключей и пропишите пути до публичного и приватного ключа в поля connector_server.tls.cert и connector_server.tls.key конфигурационного файла fq-connector-go.yaml:

   connector_server:
     # ...
     tls:
       cert: "/opt/ydb/certs/fq-connector-go.crt"
       key: "/opt/ydb/certs/fq-connector-go.key"
   

5. В случае, если внешние источники данных используют TLS, для организации шифрованных соединений с ними коннектору потребуется корневой или промежуточный сертификат удостоверяющего центра (Certificate Authority, CA), которым были подписаны сертификаты источников. На Linux-серверах обычно предустанавливается некоторое количество корневых сертификатов CA. Для ОС Ubuntu список поддерживаемых CA можно вывести следующей командой:

   awk -v cmd='openssl x509 -noout -subject' '/BEGIN/{close(cmd)};{print | cmd}' < /etc/ssl/certs/ca-certificates.crt
   

   Если на сервере отсутствует сертификат нужного CA, скопируйте его в специальную системную директорию и обновите список сертификатов:

   sudo cp root_ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates
   

6. Вы можете запустить сервис вручную или с помощью systemd.

   Вручную

   С использованием systemd

   Запустите сервис из консоли следующей командой:

   /opt/ydb/bin/fq-connector-go server -c /opt/ydb/cfg/fq-connector-go.yaml
   

   Вместе с бинарным дистрибутивом fq-connector-go распространяется пример конфигурационного файла (юнита) для системы инициализации systemd. Скопируйте юнит в директорию /etc/systemd/system, активизируйте и запустите сервис:

   cd /tmp/connector
   sudo cp fq-connector-go.service /etc/systemd/system/
   sudo systemctl enable fq-connector-go.service
   sudo systemctl start fq-connector-go.service
   

   В случае успеха сервис должен перейти в состояние active (running). Проверьте его следующей командой:

   sudo systemctl status fq-connector-go 
   ● fq-connector-go.service - YDB FQ Connector Go
       Loaded: loaded (/etc/systemd/system/fq-connector-go.service; enabled; vendor preset: enabled)
       Active: active (running) since Thu 2024-02-29 17:51:42 MSK; 2s ago
   

   Логи сервиса можно прочитать с помощью команды:

   sudo journalctl -u fq-connector-go.service
   

Запуск в Docker

1. Для запуска коннектора используйте официальный Docker-образ. Он уже содержит конфигурационный файл сервиса. Запустить сервис с настройками по умолчанию можно следующей командой:

   docker run -d \
       --name=fq-connector-go \
       -p 2130:2130 \
       ghcr.io/ydb-platform/fq-connector-go:latest
   

   На порту 2130 публичного сетевого интерфейса вашего хоста запустится слушающий сокет GRPC-сервиса коннектора. В дальнейшем сервер YDB должен будет установить соединение именно с этим сетевым адресом.

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

   docker run -d \
       --name=fq-connector-go \
       -p 2130:2130 \
       -v /path/to/config.yaml:/opt/ydb/cfg/fq-connector-go.yaml
       ghcr.io/ydb-platform/fq-connector-go:latest
   

3. В рекомендуемом режиме использования коннектор развёртывается на тех же серверах, что и динамические узлы YDB, следовательно, шифрование сетевых соединений между ними не требуется. Но если вам всё же необходимо включить шифрование между YDB и коннектором, подготовьте пару TLS-ключей и пропишите пути до публичного и приватного ключа в секции конфигурационного файла connector_server.tls.cert и connector_server.tls.key соответственно:

   connector_server:
     # ...
     tls:
       cert: "/opt/ydb/certs/fq-connector-go.crt"
       key: "/opt/ydb/certs/fq-connector-go.key"
   

   При запуске контейнера примонтируйте внутрь него директорию с парой TLS-ключей так, чтобы они оказались доступны для процесса fq-connector-go по путям, указанным в конфигурационном файле:

   docker run -d \
       --name=fq-connector-go \
       -p 2130:2130 \
       -v /path/to/config.yaml:/opt/ydb/cfg/fq-connector-go.yaml
       -v /path/to/keys/:/opt/ydb/certs/
       ghcr.io/ydb-platform/fq-connector-go:latest
   

4. В случае, если внешние источники данных используют TLS, для организации шифрованных соединений с ними коннектору потребуется корневой или промежуточный сертификат удостоверяющего центра (Certificate Authority, CA), которым были подписаны сертификаты источников. Docker-образ для коннектора базируется на образе дистрибутива Alpine Linux, который уже содержит некоторое количество сертификатов от доверенных CA. Проверить наличие нужного CA в списке предустановленных можно следующей командой:

   docker run -it --rm ghcr.io/ydb-platform/fq-connector-go sh
   # далее в консоли внутри контейнера:
   apk add openssl
   awk -v cmd='openssl x509 -noout -subject' ' /BEGIN/{close(cmd)};{print | cmd}' < /etc/ssl/certs/ca-certificates.crt
   

   Если TLS-ключи для источников выпущены CA, не входящим в перечень доверенных, необходимо добавить сертификат этого CA в системные пути контейнера с коннектором. Сделать это можно, например, собрав собственный Docker-образ на основе имеющегося. Для этого подготовьте следующий Dockerfile:

   FROM ghcr.io/ydb-platform/fq-connector-go:latest
   
   USER root
   
   RUN apk --no-cache add ca-certificates openssl
   COPY root_ca.crt /usr/local/share/ca-certificates
   RUN update-ca-certificates
   

   Поместите Dockerfile и корневой сертификат CA в одной папке, зайдите в неё и соберите образ следующей командой:

   docker build -t fq-connector-go_custom_ca .
   

   Новый образ fq-connector-go_custom_ca можно использовать для развёртывания сервиса с помощью команд, приведённых выше.

Конфигурация

Актуальный пример конфигурационного файла сервиса fq-connector-go можно найти в репозитории.