Создание кластера Sharded PostgreSQL

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

export IAM_TOKEN="<IAM-токен>"

Создайте файл body.json и добавьте в него следующее содержимое:

{
  "folderId": "<идентификатор_каталога>",
  "name": "<имя_кластера>",
  "description": "<описание>",
  "environment": "<окружение>",
  "securityGroupIds": [
    "<идентификатор_группы_безопасности_1>",
    "<идентификатор_группы_безопасности_2>",
    ...
    "<идентификатор_группы_безопасности_N>"
  ],
  "networkId": "<идентификатор_сети>",
  "deletionProtection": <защитить_кластер_от_удаления>,
  "configSpec": {
    "spqrSpec": {
      "router": {
        "config": {
          "showNoticeMessages": <показывать_информационные_уведомления>,
          "timeQuantiles": [
            <список_квантилей_времени_для_отображения_статистики>
          ],
          "defaultRouteBehavior": "<разрешать_мультишардовые_запросы>",
          "preferSameAvailabilityZone": <приоритет_маршрутизации_в_зону_доступности_роутера>
        },
        "resources": {
          "resourcePresetId": "<класс_хостов_роутера>",
          "diskSize": "<размер_хранилища_в_байтах>",
          "diskTypeId": "<тип_диска>"
        }
      },
      "coordinator": {
        "resources": {
          "resourcePresetId": "<класс_хостов_координатора>",
          "diskSize": "<размер_хранилища_в_байтах>",
          "diskTypeId": "<тип_диска>"
        }
      },
      "infra": {
        "router": {
          "showNoticeMessages": <показывать_информационные_уведомления>,
          "time_quantiles": [
            <список_квантилей_времени_для_отображения_статистики>
          ],
          "defaultRouteBehavior": "<разрешать_мультишардовые_запросы>",
          "preferSameAvailabilityZone": <приоритет_маршрутизации_в_зону_доступности_роутера>
        },
        "resources": {
          "resourcePresetId": "<класс_хостов_INFRA>",
          "diskSize": "<размер_хранилища_в_байтах>",
          "diskTypeId": "<тип_диска>"
        }
      },
      "consolePassword": "<пароль_консоли_Sharded_PostgreSQL>",
      "logLevel": "<уровень_логирования>"
    },
    "backupWindowStart": {
      "hours": "<часы>",
      "minutes": "<минуты>",
      "seconds": "<секунды>",
      "nanos": "<наносекунды>"
    },
    "backupRetainPeriodDays": "<количество_дней>",
  },
  "databaseSpecs": [
    {
      "name": "<имя_БД>"
    },
    { <аналогичный_набор_настроек_для_БД_2> },
    { ... },
    { <аналогичный_набор_настроек_для_БД_N> }
  ],
  "userSpecs": [
    {
      "name": "<имя_пользователя>",
      "password": "<пароль_пользователя>",
      "permissions": [
        {
          "databaseName": "<имя_БД>"
        },
        { <имя_БД_2> },
        { ... },
        { <имя_БД_N> }
      ],
      "settings": {
        "connectionLimit": "<количество_пользовательских_соединений>",
        "connectionRetries": "<количество_повторов_при_подключении>"
      },
      "grants": [
        "привилегия_1",
        ...,
        "привилегия_N"
      ]
    },
    { <аналогичный_набор_настроек_для_пользователя_2> },
    { ... },
    { <аналогичный_набор_настроек_для_пользователя_N> }
  ],
  "hostSpecs": [
    {
      "zoneId": "<зона_доступности>",
      "subnetId": "<идентификатор_подсети>",
      "assignPublicIp": <разрешить_публичный_доступ_к_хосту>,
      "type": "<тип_хоста>"
    },
    { <аналогичный_набор_настроек_для_хоста_2> },
    { ... },
    { <аналогичный_набор_настроек_для_хоста_N> }
  ],
  "shardSpecs": [
    {
      "shardName": "<имя_шарда>",
      "mdbPostgresql": {
        "clusterId": "<идентификатор_кластера>"
      }
    },
    { <аналогичный_набор_настроек_для_шарда_2> },
    { ... },
    { <аналогичный_набор_настроек_для_шарда_N> }
  ],
  "maintenanceWindow": {
    "weeklyMaintenanceWindow": {
      "day": "<день_недели>",
      "hour": "<час_дня>"
    }
  }
}

Где:

• folderId — идентификатор каталога. Его можно запросить со списком каталогов в облаке.

• name — имя кластера.

• environment — окружение кластера: PRODUCTION или PRESTABLE.

• networkId — идентификатор сети, в которой будет размещен кластер.

  Важно

  Выбранную для размещения кластера облачную сеть нельзя будет изменить. Если в дальнейшем вам потребуется переместить кластер в другую облачную сеть, воспользуйтесь функцией восстановления из резервной копии и укажите необходимую сеть для копии кластера.

• securityGroupIds — идентификаторы групп безопасности.

  Важно

  Чтобы роутер мог подключаться к хостам шарда, кластер Managed Service for Sharded PostgreSQL и шарды должны находиться в одной группе безопасности, разрешающей входящие и исходящие TCP-подключения на порт 6432.

• deletionProtection — защита кластера от удаления: true или false.

  Включенная защита кластера от удаления не помешает подключиться к нему вручную и удалить данные.

• configSpec — настройки кластера:

  • spqrSpec — настройки сервиса Sharded PostgreSQL:

    • router — при расширенном шардировании задайте настройки роутера:

      • config — конфигурация роутера:

        • showNoticeMessages — показывать информационные уведомления: true или false.
        • timeQuantiles — массив строк временных квантилей для отображения статистики. По умолчанию используются значения "0.5", "0.75", "0.9", "0.95", "0.99", "0.999", "0.9999".
        • defaultRouteBehavior — политика выполнения мультишардовых запросов роутером. Возможные значения: BLOCK — блокировать, ALLOW — разрешать.
        • preferSameAvailabilityZone — включить приоритет маршрутизации запросов на чтение в зону доступности роутера: true или false.

      • resources — параметры ресурсов хостов ROUTER:

        • resourcePresetId — класс хостов;
        • diskSize — размер диска в байтах;
        • diskTypeId — тип диска.

    • coordinator – при расширенном шардировании задайте параметры ресурсов координатора:

      • resourcePresetId — класс хостов;
      • diskSize — размер диска в байтах;
      • diskTypeId — тип диска.

    • infra – при стандартном шардировании задайте настройки хостов INFRA:

      • resources — параметры ресурсов:

        • resourcePresetId — класс хостов;
        • diskSize — размер диска в байтах;
        • diskTypeId — тип диска.

      • router — конфигурация роутера:

        • showNoticeMessages — показывать информационные уведомления: true или false.
        • timeQuantiles — массив временных квантилей для отображения статистики. По умолчанию используются значения 0.5, 0.75, 0.9, 0.95, 0.99, 0.999, 0.9999.
        • defaultRouteBehavior — политика выполнения мультишардовых запросов роутером. Возможные значения: BLOCK — блокировать, ALLOW — разрешать.
        • preferSameAvailabilityZone — включить приоритет маршрутизации запросов на чтение в зону доступности роутера: true или false.

      • consolePassword — пароль консоли Sharded PostgreSQL.

      • logLevel — уровень логирования запросов: DEBUG, INFO, WARNING, ERROR, FATAL, PANIC.

  • backupWindowStart — настройки окна резервного копирования.

    В параметре укажите время, когда начинать резервное копирование. Возможные значения параметров:

    • hours — от 0 до 23 часов;
    • minutes — от 0 до 59 минут;
    • seconds — от 0 до 59 секунд;
    • nanos — от 0 до 999999999 наносекунд.

  • backupRetainPeriodDays — сколько дней хранить резервную копию кластера. Возможные значения: от 7 до 60 дней.

• databaseSpecs — настройки баз данных в виде массива элементов. Каждый элемент соответствует отдельной БД и имеет следующую структуру:

  • name — имя БД.

• userSpecs — настройки пользователей в виде массива элементов. Каждый элемент соответствует отдельному пользователю и имеет следующую структуру:

  • name — имя пользователя.

  • password — пароль пользователя. Длина пароля — от 8 до 128 символов.

  • permissions.databaseName — имя базы данных, к которой пользователь получает доступ.

  • settings — параметры пользовательских подключений к БД:

    • connectionLimit — лимит подключений.
    • connectionRetries — количество повторных попыток подключения.

  • grants – привилегии пользователя в виде массива строк. Возможные значения: reader, writer, admin, transfer.

• hostSpecs — настройки хостов кластера в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

  • zoneId — зона доступности;

  • subnetId — идентификатор подсети;

  • assignPublicIp — разрешение на подключение к хосту из интернета: true или false;

  • type — тип хоста. Возможные значения:

    • ROUTER — роутер в кластере с расширенным шардированием;
    • COORDINATOR — координатор в кластере с расширенным шардированием;
    • INFRA — хост INFRA в кластере со стандартным шардированием.

• shardSpecs — настройки шардов в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

  • shardName — имя шарда.
  • mdbPostgresql.clusterId — идентификатор кластера Managed Service for PostgreSQL в составе шарда.

• maintenanceWindow — настройки расписания окна технического обслуживания:

  • day — день недели в формате DDD, когда должно проходить обслуживание.
  • hour — час дня в формате HH, когда должно проходить обслуживание. Допустимые значения: от 1 до 24.

Воспользуйтесь методом Cluster.Create и выполните запрос, например с помощью cURL:

curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.yandexcloud.kz/managed-spqr/v1/clusters' \
  --data "@body.json"

Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:

export IAM_TOKEN="<IAM-токен>"

Клонируйте репозиторий cloudapi:

cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

Создайте файл body.json и добавьте в него следующее содержимое:

{
  "folder_id": "<идентификатор_каталога>",
  "name": "<имя_кластера>",
  "description": "<описание>",
  "environment": "<окружение>",
  "security_group_ids": [
    "<идентификатор_группы_безопасности_1>",
    "<идентификатор_группы_безопасности_2>",
    ...
    "<идентификатор_группы_безопасности_N>"
  ],
  "network_id": "<идентификатор_сети>",
  "deletion_protection": <защитить_кластер_от_удаления>,
  "config_spec": {
    "spqr_spec": {
      "router": {
        "config": {
          "show_notice_messages": {
            "value": <показывать_информационные_уведомления>
          },
          "time_quantiles": [
            <список_квантилей_времени_для_отображения_статистики>
          ],
          "default_route_behavior": "<разрешать_мультишардовые_запросы>",
          "prefer_same_availability_zone": {
            "value": <приоритет_маршрутизации_в_зону_доступности_роутера>
          }
        },
        "resources": {
          "resource_preset_id": "<класс_хостов_роутера>",
          "disk_size": "<размер_хранилища_в_байтах>",
          "disk_type_id": "<тип_диска>" }
      },
      "coordinator": {
        "resources": {
          "resource_preset_id": "<класс_хостов_координатора>",
          "disk_size": "<размер_хранилища_в_байтах>",
          "disk_type_id": "<тип_диска>"
        }
      },
      "infra": {
        "resources": {
          "resource_preset_id": "класс_хостов_INFRA",
          "disk_size": "<размер_хранилища_в_байтах>",
          "disk_type_id": "<тип_диска>"
        },
        "router": {
          "show_notice_messages": {
            "value": <показывать_информационные_уведомления>
          },
          "time_quantiles": [
            <список_квантилей_времени_для_отображения_статистики>
          ],
          "default_route_behavior": "<разрешать_мультишардовые_запросы>",
          "prefer_same_availability_zone": {
            "value": <приоритет_маршрутизации_в_зону_доступности_роутера>
          }
        },
      },
      "console_password": "<пароль_консоли_Sharded_PostgreSQL>",
      "log_level": "<уровень_логирования>"
    },
    "backup_window_start": {
      "hours": "<часы>",
      "minutes": "<минуты>",
      "seconds": "<секунды>",
      "nanos": "<наносекунды>"
    },
    "backup_retain_period_days": "<количество_дней>"
  },
  "database_specs": [
    {
      "name": "<имя_БД>"
    },
    { <аналогичный_набор_настроек_для_БД_2> },
    { ... },
    { <аналогичный_набор_настроек_для_БД_N> }
  ],
  "user_specs": [
    {
      "name": "<имя_пользователя>",
      "password": "<пароль_пользователя>",
      "permissions": [
        {
          "database_name": "<имя_БД>"
        },
        { <имя_БД_2> },
        { ... },
        { <имя_БД_N> }
      ],
      "settings": {
        "connection_limit": {
          "value": <количество_пользовательских_соединений>
        },
        "connection_retries": {
          "value": <количество_повторов_при_подключении>
        }
      },
      "grants": [
        "привилегия_1",
        ...,
        "привилегия_N"
      ]
    },
    { <аналогичный_набор_настроек_для_пользователя_2> },
    { ... },
    { <аналогичный_набор_настроек_для_пользователя_N> }
  ],
  "host_specs": [
    {
      "zone_id": "<зона_доступности>",
      "subnet_id": "<идентификатор_подсети>",
      "assign_public_ip": <разрешить_публичный_доступ_к_хосту>,
      "type": "<тип_хоста>"
    },
    { <аналогичный_набор_настроек_для_хоста_2> },
    { ... },
    { <аналогичный_набор_настроек_для_хоста_N> }
  ],
  "shard_specs": [
    {
      "shard_name": "<имя_шарда>",
      "mdb_postgresql": {
        "cluster_id": "<идентификатор_кластера>"
      }
    },
    { <аналогичный_набор_настроек_для_шарда_2> },
    { ... },
    { <аналогичный_набор_настроек_для_шарда_N> }
  ],
  "maintenance_window": {
    "weekly_maintenance_window": {
      "day": "<день_недели>",
      "hour": "<час_дня>"
    }
  }
}

Где:

• folder_id — идентификатор каталога. Его можно запросить со списком каталогов в облаке..

• name — имя кластера.

• environment — окружение кластера: PRODUCTION или PRESTABLE.

• network_id — идентификатор сети, в которой будет размещен кластер.

  Важно

  Выбранную для размещения кластера облачную сеть нельзя будет изменить. Если в дальнейшем вам потребуется переместить кластер в другую облачную сеть, воспользуйтесь функцией восстановления из резервной копии и укажите необходимую сеть для копии кластера.

• security_group_ids — идентификаторы групп безопасности.

  Важно

  Чтобы роутер мог подключаться к хостам шарда, кластер Managed Service for Sharded PostgreSQL и шарды должны находиться в одной группе безопасности, разрешающей входящие и исходящие TCP-подключения на порт 6432.

• deletion_protection — защита кластера от удаления: true или false.

  Включенная защита кластера от удаления не помешает подключиться к нему вручную и удалить данные.

• config_spec — настройки кластера:

  • spqr_spec — настройки сервиса Sharded PostgreSQL:

    • router — при расширенном шардировании задайте настройки роутера:

      • config — конфигурация роутера:

        • show_notice_messages — показывать информационные уведомления: true или false.
        • time_quantiles — массив временных квантилей для отображения статистики. По умолчанию используются значения 0.5, 0.75, 0.9, 0.95, 0.99, 0.999, 0.9999.
        • default_route_behavior — политика выполнения мультишардовых запросов роутером. Возможные значения: BLOCK — блокировать, ALLOW — разрешать.
        • prefer_same_availability_zone — включить приоритет маршрутизации запросов на чтение в зону доступности роутера: true или false.

      • resources — параметры ресурсов хостов ROUTER:

        • resource_preset_id — класс хостов;
        • disk_size — размер диска в байтах;
        • disk_type_id — тип диска.

    • coordinator – при расширенном шардировании задайте параметры ресурсов координатора:

      • resource_preset_id — класс хостов;
      • disk_size — размер диска в байтах;
      • disk_type_id — тип диска.

    • infra – при стандартном шардировании задайте настройки хостов INFRA:

      • resources — параметры ресурсов:

        • resource_preset_id — класс хостов;
        • disk_size — размер диска в байтах;
        • disk_type_id — тип диска.

      • router — конфигурация роутера:

        • default_route_behavior — поведение роутера по умолчанию. Возможные значения: BLOCK — блокировать запрос, ALLOW — разрешать.
        • prefer_same_availability_zone — включить приоритет маршрутизации в зону доступности роутера: true или false.

      • console_password — пароль консоли Sharded PostgreSQL.

      • log_level — уровень логирования запросов: DEBUG, INFO, WARNING, ERROR, FATAL, PANIC.

  • backup_window_start — настройки окна резервного копирования.

    В параметре укажите время, когда начинать резервное копирование. Возможные значения параметров:

    • hours — от 0 до 23 часов;
    • minutes — от 0 до 59 минут;
    • seconds — от 0 до 59 секунд;
    • nanos — от 0 до 999999999 наносекунд.

  • backup_retain_period_days — сколько дней хранить резервную копию кластера. Возможные значения: от 7 до 60 дней.

• database_specs — настройки баз данных в виде массива элементов. Каждый элемент соответствует отдельной БД и имеет следующую структуру:

  • name — имя БД.

• user_specs — настройки пользователей в виде массива элементов. Каждый элемент соответствует отдельному пользователю и имеет следующую структуру:

  • name — имя пользователя.

  • password — пароль пользователя. Длина пароля — от 8 до 128 символов.

  • permissions.database_name — имя базы данных, к которой пользователь получает доступ.

  • settings — параметры пользовательских подключений к БД:

    • connection_limit — лимит подключений.
    • connection_retries — количество повторных попыток подключения.

  • grants – привилегии пользователя в виде массива строк. Возможные значения: reader, writer, admin, transfer.

• host_specs — настройки хостов кластера в виде массива элементов. Каждый элемент соответствует отдельному хосту и имеет следующую структуру:

  • zone_id — зона доступности;

  • subnet_id — идентификатор подсети;

  • assign_public_ip — разрешение на подключение к хосту из интернета: true или false;

  • type — тип хоста. Возможные значения:

    • ROUTER — роутер в кластере с расширенным шардированием;
    • COORDINATOR — координатор в кластере с расширенным шардированием;
    • INFRA — хост INFRA в кластере со стандартным шардированием.

• shard_specs — настройки шардов в виде массива элементов. Каждый элемент соответствует отдельному шарду и имеет следующую структуру:

  • shard_name — имя шарда.
  • mdb_postgresql.cluster_id — идентификатор кластера Managed Service for PostgreSQL в составе шарда.

• maintenance_window — настройки расписания окна технического обслуживания:

  • day — день недели в формате DDD, когда должно проходить обслуживание.
  • hour — час дня в формате HH, когда должно проходить обслуживание. Допустимые значения: от 1 до 24.

Воспользуйтесь вызовом ClusterService.Create и выполните запрос, например с помощью gRPCurl:

grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d @ \
  mdb.api.yandexcloud.kz:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.Create \
  < body.json

Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.