Руководство для начинающих¶

Установка и конфигурация¶

minikube start --driver=docker --cpus 4 --memory=10240 --disk-size 50GB

$ minikube status
minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

cat > init.sql << 'EOF'
-- Create Person table
CREATE TYPE gender AS ENUM ('male', 'female');
CREATE TABLE "Person" (
    "uid" BIGINT PRIMARY KEY,
    "firstname" VARCHAR(256) NOT NULL,
    "lastname" VARCHAR(256) NOT NULL,
    "gender" gender NOT NULL,
    "birthdate" TIMESTAMPTZ NOT NULL,
    "age" INT,
    "metadata" JSONB,
    "description" TEXT,
    "enabled" BOOLEAN DEFAULT false
);

-- Insert 10,000 random tuples into the Person table
INSERT INTO "Person" (uid, firstname, lastname, gender, birthdate, age, metadata, description, enabled)
SELECT
    gs AS uid,
    md5(random()::text || clock_timestamp()::text)::varchar(8) AS firstname,
    md5(random()::text || clock_timestamp()::text)::varchar(10) AS lastname,
    (ARRAY['male', 'female'])[floor(random() * 2 + 1)]::gender AS gender,
    timestamp '1950-01-01' + random() * (timestamp '2000-01-01' - timestamp '1950-01-01') AS birthdate,
    (random() * (70 - 18) + 18)::INT AS age,
    jsonb_build_object('key1', md5(random()::text)::varchar(5),
                       'key2', (random() * 100)::INT,
                       'key3', (random() > 0.5)) AS metadata,
    md5(random()::text || clock_timestamp()::text)::varchar(50) AS description,
    (random() > 0.5) AS enabled
FROM generate_series(1, 10000) AS gs;
EOF

make stop
make clean

Настройка мониторинга в Grafana¶

1. Добавьте репозиторий с kube-prometheus-stack в minikube:

   helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
   

2. Оставьте только нужные компоненты kube-prometheus-stack. Для этого в рабочей директории создайте файл kube-prometheus-stack-values.yaml:

   # Disable components that are not needed
   defaultRules:
     create: false
   
   alertmanager:
     enabled: false
   
   kubeApiServer:
     enabled: false
   
   kubelet:
     enabled: false
     cAdvisorMetricRelabelings: []
   
   kubeControllerManager:
     enabled: false
   
   coreDns:
     enabled: false
   
   kubeDns:
     enabled: false
   
   kubeEtcd:
     enabled: false
   
   kubeScheduler:
     enabled: false
   
   kubeProxy:
     enabled: false
   
   nodeExporter:
     enabled: false
   
   kubernetesServiceMonitors:
     enabled: false
   
   prometheusOperator:
     enabled: true
   
   # Enable Prometheus
   prometheus:
     enabled: true
     prometheusSpec:
       podMonitorSelectorNilUsesHelmValues: false
       serviceMonitorSelectorNilUsesHelmValues: false
       scrapeInterval: "5s"  # Set the scrape interval to 5 seconds
   
   # Enable Grafana
   grafana:
     enabled: true
   
   # Disable additional exporters and services
   kubeStateMetrics:
     enabled: false
   
   # Disable additional monitoring
   additionalPrometheusRulesMap: {}
   additionalScrapeConfigs: []
   

3. Установите kube-prometheus-stack в minikube или используйте уже установленный:

   helm upgrade kube-prometheus-stack --install --namespace monitoring --create-namespace \
   prometheus-community/kube-prometheus-stack -f kube-prometheus-stack-values.yaml
   

   Запуск подов может занять 1-2 минуты. Убедитесь, что они находятся в статусе Running:

   $ kubectl -n monitoring get pod
   NAME                                             READY   STATUS    RESTARTS         AGE
   kube-prometheus-stack-grafana-6bbf7df694-lc8rv   3/3     Running   12 (2m45s ago)   13d
   kube-prometheus-stack-operator-df7db7df9-n6zt4   1/1     Running   25 (118s ago)    13d
   prometheus-kube-prometheus-stack-prometheus-0    2/2     Running   14 (2m45s ago)   13d
   

4. Узнайте и сохраните пароль от учетной записи admin для доступа в графану:

   kubectl --namespace monitoring get secrets kube-prometheus-stack-grafana -o jsonpath="{.data.admin-password}" | base64 -d ; echo
   

   Примечание

   Обратите внимание, что команда возвращает пароль в незашифрованном виде. Команда может отличаться в зависимости от версии чарта kube-prometheus-stack. При написания этого Руководства использовалась версия 80.0.0.

5. В рабочей директории создайте файл tarantool-cdc-monitors.yaml:

   ---
   kind: PodMonitor
   apiVersion: monitoring.coreos.com/v1
   metadata:
     name: tqe-grpc-monitor
     namespace: monitoring
   spec:
     namespaceSelector:
       matchNames:
       - tarantool-cdc-demo
     selector:
       matchExpressions:
       - key: app
         operator: In
         values:
           - cdc-tqe-api-consumer-0
           - cdc-tqe-api-publisher
           - cdc-tqe-api-pubsub
     podMetricsEndpoints:
       - path: /metrics
         port: monitoring
   ...
   ---
   kind: PodMonitor
   apiVersion: monitoring.coreos.com/v1
   metadata:
     name: tqe-tarantool-monitor
     namespace: monitoring
   spec:
     namespaceSelector:
       matchNames:
       - tarantool-cdc-demo
     selector:
       matchExpressions:
       - key: app
         operator: In
         values:
           - tarantool
     podMetricsEndpoints:
       - path: /metrics
         port: http
   ...
   ---
   kind: PodMonitor
   apiVersion: monitoring.coreos.com/v1
   metadata:
     name: cdc-monitor
     namespace: monitoring
   spec:
     namespaceSelector:
       matchNames:
       - tarantool-cdc-demo
     selector:
       matchLabels:
         cdc.tarantool.io/component: worker
     podMetricsEndpoints:
       - path: /actuator/prometheus
         port: http
   ...
   

6. Подключите PodMonitor к мониторингу:

   kubectl apply -f tarantool-cdc-monitors.yaml
   

7. Пробросьте порт от Grafana с помощью kubectl:

   kubectl -n monitoring get svc
   kubectl -n monitoring port-forward svc/kube-prometheus-stack-grafana 3000:80 &
   

   или воспользуйтесь функцией port-forward в K9s (SHIFT-F на под с grafana).

8. При помощи браузера зайдите в Grafana (localhost:3000), используя логин и пароль, которые вы узнали в шаге 4 выше.

9. Импортируйте панель мониторинга tarantool-cdc-dashboard_rev3.json:

a. Нажмите Dashboards в меню слева.

b. Нажмите New. В выпадающем меню выберите пункт Import.

c. Загрузите JSON-файл с панелью мониторинга.

d. Нажмите Import.

В результате отобразится панель мониторинга Tarantool CDC, но данные в ней появятся только после запуска CDC.

Запуск CDC¶

1. Откройте новое окно терминала.

2. Перейдите в директорию с распакованным главным архивом:

   cd tarantool-cdc-bundle-0.9.0
   

3. Распакуйте архив с helm-чартом в новую директорию helm-chart-cdc:

   mkdir helm-chart-cdc
   tar -xzf helm-chart-cdc-0.8.2.tar.gz -C helm-chart-cdc --strip-components=1
   

4. Скачайте архив с примером helm-чарта по ссылке, переместите его в директорию tarantool-cdc-bundle-0.9 и распакуйте.

5. Скачайте YAML-файл cdc-pg-tdb-example.yaml с примером конфигурации для helm-чарта. Сохраните файл вместо имеющегося в директории распакованного выше архива k8s/samples/quickstart/.

   Примечание

   • Для запуска на Windows и macOS, в этом файле нужно поменять все вхождения подстроки minikube.host.internal на host.docker.internal.

   • При прохождении примера на macOS рекомендуется перейти в рабочую директорию и выполнить команду find . -name ".DS_Store" -type f -delete. Эта команда удалит скрытые файлы .DS_Store, которые могут создаваться операционной системой автоматически в рабочей директории и в ее дочерних директориях. Эти файлы помешают процессу миграции данных в базу данных Tarantool.

6. Запустите кластер Tarantool CDC.

   Удалите PVC от предыдущих запусков:

   kubectl -n tarantool-cdc-demo delete pvc --all
   

   Установите кластер:

   helm install -n tarantool-cdc-demo -f k8s/samples/quickstart/cdc-pg-tdb-example.yaml cdc helm-chart-cdc/
   

   Запуск всех подов может занять 1-2 минуты.

7. Проверьте, что кластер Tarantool CDC успешно запустился:

   a. В K9s откройте список всех подов в пространстве имен tarantool-cdc-demo:

   k9s -n tarantool-cdc-demo
   

   b. Убедитесь, что все поды находятся в статусе Running или Completed (колонка STATUS).

   Если под находится в статусе Init, то нужно подождать еще немного, чтобы он загрузился.

c. Убедитесь, что в журналах обработчиков (worker) отсутствуют ошибки подключения к БД (в списке выберите по очереди каждый из подов, у которого в имени есть worker, и нажмите клавишу L).

6. Проверьте, что данные о кластере Tarantool CDC появились на панели мониторинга в Grafana (обновите страницу мониторинга в браузере).

Запуск постоянной нагрузки¶

Теперь проверим работу стенда, запустив нагрузочное тестирование с помощью утилиты K6.

1. Создайте скрипт load_test_tarantool_const_rps.js для нагрузочного тестирования:

   import { check, sleep } from 'k6';
   import exec from 'k6/execution';
   import faker from "k6/x/faker";
   import sql from "k6/x/sql";
   import driver from "k6/x/sql/driver/postgres";
   
   // Database connection configuration
   const db = sql.open(driver, 'postgres://demouser:demopasswd@localhost:5432/demo?sslmode=disable');
   
   // k6 options
   export const options = {
       scenarios: {
           constant_rps: {
               executor: 'constant-arrival-rate',
               rate: 150, // 150 iterations per second
               timeUnit: '1s', // Time unit for the rate
               duration: '10m', // Total duration of the test
               preAllocatedVUs: 50, // Pre-allocate VUs for the test
               maxVUs: 200, // Maximum VUs to allow for the test
           },
       },
       thresholds: {
           http_req_duration: ['p(95)<500'], // 95% of requests should complete below 500ms
       },
   };
   
   // Define the range of UIDs to use
   const UID_START = 1;
   const UID_END = 100;
   
   // Function to get a random UID within the specified range
   function getRandomUid() {
       return Math.floor(Math.random() * (UID_END - UID_START + 1)) + UID_START;
   }
   
   export default function () {
       // Randomly select a UID for each operation
       const uid = getRandomUid();
   
       // Generate fake data
       const firstname = faker.person.firstName();
       const lastname = faker.person.lastName();
       const gender = faker.person.gender();
       const birthDate = faker.time.date("RFC3339");
       const age = faker.numbers.int16();
       const metadata = JSON.stringify({
           key1: faker.word.word(),
           key2: faker.numbers.int8(),
           key3: faker.numbers.boolean(),
       });
       const description = faker.word.sentence(5);
       const enabled = faker.numbers.boolean();
   
       // Insert operation (using a unique value to avoid conflicts)
       let insertResult = db.exec(
           'INSERT INTO "Person" (uid, firstname, lastname, gender, birthdate, age, metadata, description, enabled) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) ON CONFLICT (uid) DO NOTHING',
           uid + 1000, firstname, lastname, gender, birthDate, age, metadata, description, enabled
       );
       // console.log('[INSERT] res: ', insertResult);
       check(insertResult, {
           'insert successful': (r) => r.err == '',
       });
   
       // Update operation
       let updateResult = db.exec(
           'UPDATE "Person" SET firstname = $1, lastname = $2, age = $3 WHERE uid = $4',
           firstname, lastname, age, uid + 1000
       );
       // console.log('[UPDATE] res: ', updateResult);
       check(updateResult, {
           'update successful': (r) => r.err == '',
       });
   
       // Delete operation
       let deleteResult = db.exec('DELETE FROM "Person" WHERE uid = $1', uid + 1000);
       // console.log('[DELETE] res: ', updateResult);
       check(deleteResult, {
           'delete successful': (r) => r.err == '',
       });
   }
   
   export function teardown() {
       db.close();
   }
   

2. Запустите Docker-контейнер с K6 SQL:

   Для Linux

   docker run --rm -it -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" \
      grafana/xk6 build v0.57.0 \
      --with github.com/grafana/xk6-sql@v1.0.4 \
      --with github.com/grafana/xk6-sql-driver-postgres \
      --with github.com/grafana/xk6-faker@v0.4.2
   

   Для macOS

   docker run --rm -it -e GOOS=darwin -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" \
      grafana/xk6 build v0.57.0 \
      --with github.com/grafana/xk6-sql@v1.0.4 \
      --with github.com/grafana/xk6-sql-driver-postgres \
      --with github.com/grafana/xk6-faker@v0.4.2
   

   Для Windows (PowerShell)

   docker run --rm -it -e GOOS=windows -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" `
      grafana/xk6 build v0.57.0 --output k6.exe `
      --with github.com/grafana/xk6-sql@v1.0.4 `
      --with github.com/grafana/xk6-sql-driver-postgres `
      --with github.com/grafana/xk6-faker@v0.4.2
   

   В результате будет создан исполняемый файл k6 или k6.exe. Поместите его в ту же директорию, что и скрипт для нагрузочного тестирования.

3. Запустите скрипт с циклической нагрузкой:

   Для Linux/macOS

   ./k6 run load_test_tarantool_const_rps.js
   

   Для Windows (PowerShell)

   k6.exe run load_test_tarantool_const_rps.js
   

4. Проконтролируйте работу CDC с помощью Grafana.

   В панели мониторинга Tarantool CDC отображаются основные параметры работы системы:

   • количество обработанных событий CDC в секунду;

   • объем трафика, проходящего через систему;

   • ошибки.

Остановка стенда¶

Чтобы корректно остановить Tarantool CDC и обе СУБД, выполните следующие команды:

# Остановите кластер Tarantool CDC:
helm uninstall cdc -n tarantool-cdc-demo
minikube stop

# Остановите кластер TarantoolDB (из директории up_with_docker_compose):
make stop

# Остановите PostgreSQL:
docker stop postgresql-sourcedb

Установка и конфигурация. Пример прямой передачи данных¶

Настройка мониторинга в Grafana. Пример прямой передачи данных¶

1. Добавьте репозиторий с kube-prometheus-stack в minikube:

   helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
   

2. Оставьте только нужные компоненты kube-prometheus-stack. Для этого в рабочей директории создайте файл kube-prometheus-stack-values.yaml:

   # Disable components that are not needed
   defaultRules:
     create: false
   
   alertmanager:
     enabled: false
   
   kubeApiServer:
     enabled: false
   
   kubelet:
     enabled: false
     cAdvisorMetricRelabelings: []
   
   kubeControllerManager:
     enabled: false
   
   coreDns:
     enabled: false
   
   kubeDns:
     enabled: false
   
   kubeEtcd:
     enabled: false
   
   kubeScheduler:
     enabled: false
   
   kubeProxy:
     enabled: false
   
   nodeExporter:
     enabled: false
   
   kubernetesServiceMonitors:
     enabled: false
   
   prometheusOperator:
     enabled: true
   
   # Enable Prometheus
   prometheus:
     enabled: true
     prometheusSpec:
       podMonitorSelectorNilUsesHelmValues: false
       serviceMonitorSelectorNilUsesHelmValues: false
       scrapeInterval: "5s"  # Set the scrape interval to 5 seconds
   
   # Enable Grafana
   grafana:
     enabled: true
   
   # Disable additional exporters and services
   kubeStateMetrics:
     enabled: false
   
   # Disable additional monitoring
   additionalPrometheusRulesMap: {}
   additionalScrapeConfigs: []
   

3. Установите kube-prometheus-stack в minikube или используйте уже установленный:

   helm upgrade kube-prometheus-stack --install --namespace monitoring --create-namespace \
   prometheus-community/kube-prometheus-stack -f kube-prometheus-stack-values.yaml
   

   Запуск подов может занять 1-2 минуты. Убедитесь, что они находятся в статусе Running:

   $ kubectl -n monitoring get pod
   NAME                                             READY   STATUS    RESTARTS         AGE
   kube-prometheus-stack-grafana-6bbf7df694-lc8rv   3/3     Running   12 (2m45s ago)   13d
   kube-prometheus-stack-operator-df7db7df9-n6zt4   1/1     Running   25 (118s ago)    13d
   prometheus-kube-prometheus-stack-prometheus-0    2/2     Running   14 (2m45s ago)   13d
   

4. Узнайте и сохраните пароль от учетной записи admin для доступа в графану:

   kubectl --namespace monitoring get secrets kube-prometheus-stack-grafana -o jsonpath="{.data.admin-password}" | base64 -d ; echo
   

   Примечание

   Обратите внимание, что команда возвращает пароль в незашифрованном виде. Команда может отличаться в зависимости от версии чарта kube-prometheus-stack. При написания этого Руководства использовалась версия 80.0.0.

5. В рабочей директории создайте файл tarantool-cdc-monitors.yaml:

   ---
   kind: PodMonitor
   apiVersion: monitoring.coreos.com/v1
   metadata:
     name: cdc-monitor
     namespace: monitoring
   spec:
     namespaceSelector:
       any: true
     selector:
       matchLabels:
         cdc.tarantool.io/component: worker
     podMetricsEndpoints:
       - path: /actuator/prometheus
         port: http
   ...
   

6. Подключите PodMonitor к мониторингу:

   kubectl apply -f tarantool-cdc-monitors.yaml
   

7. Пробросьте порт от Grafana с помощью kubectl:

   kubectl -n monitoring get svc
   kubectl -n monitoring port-forward svc/kube-prometheus-stack-grafana 3000:80 &
   

   или воспользуйтесь функцией port-forward в K9s (SHIFT-F на под с grafana).

8. При помощи браузера зайдите в Grafana (localhost:3000), используя логин и пароль, которые вы узнали в шаге 4 выше.

9. Импортируйте панель мониторинга universal-workers-dashboard_rev3.json:

   a. Нажмите Dashboards в меню слева.

   b. Нажмите New. В выпадающем меню выберите пункт Import.

   c. Загрузите JSON-файл с панелью мониторинга.

   d. Нажмите Import.

   В результате отобразится панель мониторинга Tarantool CDC, но данные в ней появятся только после запуска CDC.

Запуск CDC. Пример прямой передачи данных¶

1. Откройте новое окно терминала.

2. Перейдите в директорию с распакованным главным архивом:

   cd tarantool-cdc-bundle-0.10.0
   

3. В архив входит helm-чарт. Распакуйте этот архив в новую директорию helm-chart-cdc:

   mkdir helm-chart-cdc
   tar -xzf helm-chart-cdc-0.10.0.tar.gz -C helm-chart-cdc --strip-components=1
   

4. Скачайте архив с примером helm-чарта по ссылке, переместите его в директорию tarantool-cdc-bundle-0.10.0 и распакуйте.

5. Скачайте YAML-файл cdc-pg-tdb-universal-worker-example.yaml с примером конфигурации для helm-чарта. Сохраните файл вместо имеющегося в директории распакованного выше архива k8s/samples/quickstart/.

   Примечание

   • Для запуска на Windows и macOS, в этом файле нужно поменять все вхождения подстроки minikube.host.internal на host.docker.internal.

   • При прохождении примера на macOS рекомендуется перейти в рабочую директорию и выполнить команду find . -name ".DS_Store" -type f -delete. Эта команда удалит скрытые файлы .DS_Store, которые могут создаваться операционной системой автоматически в рабочей директории и в ее дочерних директориях. Эти файлы помешают процессу миграции данных в базу данных Tarantool.

6. Запустите кластер Tarantool CDC.

   Удалите PVC от предыдущих запусков:

   kubectl -n tarantool-cdc-demo delete pvc --all
   

   Установите кластер:

   helm install -n tarantool-cdc-demo -f k8s/samples/quickstart/cdc-pg-tdb-example.yaml cdc helm-chart-cdc/
   

   Запуск всех подов может занять 1-2 минуты.

7. Проверьте, что кластер Tarantool CDC успешно запустился:

   a. В K9s откройте список всех подов в пространстве имен tarantool-cdc-demo:

   k9s -n tarantool-cdc-demo
   

   b. Убедитесь, что все поды находятся в статусе Running или Completed (колонка STATUS).

   Если под находится в статусе Init, то нужно подождать еще немного, чтобы он загрузился.

c. Убедитесь, что в журнале универсального обработчика отсутствуют ошибки подключения к БД (в списке выберите под с именем cdc-pg-1-0-tdb2-1-0, и нажмите клавишу L).

8. Проверьте, что данные о кластере Tarantool CDC появились на панели мониторинга в Grafana (обновите страницу мониторинга в браузере).

Для выхода из интерфейса K9s используйте комбинацию клавиш CTRL+C.

Запуск постоянной нагрузки. Пример прямой передачи данных¶

Процесс запуска постоянной нагрузки в текущем примере полностью соответствует процедуре запуска из примера с передачей данных при помощи TQE.

Убедитесь, что панель мониторинга в Grafana отображает статистику передачи данных (обновите страницу мониторинга в браузере).

Остановка стенда. Пример прямой передачи данных¶

Процесс остановки стенда в текущем примере полностью соответствует процедуре остановки из примера с передачей данных при помощи TQE.