Управление шардами

Введение

В этом документе рассказывается о работе шардинга в CouchDB, а также о том, как безопасно добавлять, перемещать и удалять шарды и создавать правила их размещения и размещения реплик.

Шард — это горизонтальный раздел базы данных. Разделение данных на шарды и распределение копий каждого шарда (называемых «репликами шардов» или просто «репликами») по разным узлам кластера повышает устойчивость данных к потере узлов. Кластеры CouchDB автоматически разбивают базы данных на шарды и распределяют подмножества документов, из которых состоит каждый шард, между узлами. Изменение состава кластера и поведения шардинга необходимо выполнять вручную.

[cluster]
q=2
n=3

$ curl -X PUT "$COUCH_URL:5984/database-name?q=4&n=2"

$ curl "$COUCH_URL:5984/{db}/{doc}?r=2"

$ curl -X PUT "$COUCH_URL:5984/{db}/{doc}?w=2" -d '{...}'

Просмотр шардов базы данных

Есть несколько эндпоинтов API, которые помогают понять, как база данных разделена на шарды. Для начала создадим базу данных в кластере и добавим в неё несколько документов:

$ curl -X PUT $COUCH_URL:5984/mydb
{"ok":true}
$ curl -X PUT $COUCH_URL:5984/mydb/joan -d '{"loves":"cats"}'
{"ok":true,"id":"joan","rev":"1-cc240d66a894a7ee7ad3160e69f9051f"}
$ curl -X PUT $COUCH_URL:5984/mydb/robert -d '{"loves":"dogs"}'
{"ok":true,"id":"robert","rev":"1-4032b428c7574a85bc04f1f271be446e"}

Сначала эндпоинт верхнего уровня /{db} сообщит параметры шардинга базы данных:

$ curl -s $COUCH_URL:5984/db | jq .
{
  "db_name": "mydb",
...
  "cluster": {
    "q": 8,
    "n": 3,
    "w": 2,
    "r": 2
  },
...
}

Итак, мы знаем, что эта база данных была создана с 8 шардами (q=8), и у каждого шарда есть 3 реплики (n=3), то есть всего 24 реплики шардов на узлах кластера.

Теперь посмотрим, как эти реплики шардов размещены в кластере, с помощью эндпоинта /{db}/_shards:

$ curl -s $COUCH_URL:5984/mydb/_shards | jq .
{
  "shards": {
    "00000000-1fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node4@127.0.0.1"
    ],
    "20000000-3fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ],
    "40000000-5fffffff": [
      "node2@127.0.0.1",
      "node3@127.0.0.1",
      "node4@127.0.0.1"
    ],
    "60000000-7fffffff": [
      "node1@127.0.0.1",
      "node3@127.0.0.1",
      "node4@127.0.0.1"
    ],
    "80000000-9fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node4@127.0.0.1"
    ],
    "a0000000-bfffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ],
    "c0000000-dfffffff": [
      "node2@127.0.0.1",
      "node3@127.0.0.1",
      "node4@127.0.0.1"
    ],
    "e0000000-ffffffff": [
      "node1@127.0.0.1",
      "node3@127.0.0.1",
      "node4@127.0.0.1"
    ]
  }
}

Теперь мы видим, что в кластере на самом деле 4 узла и CouchDB равномерно распределила между ними все 24 реплики шардов.

С помощью эндпоинта /{db}/_shards/{docid} также можно точно определить, в каком шарде находится заданный документ:

$ curl -s $COUCH_URL:5984/mydb/_shards/joan | jq .
{
  "range": "e0000000-ffffffff",
  "nodes": [
    "node1@127.0.0.1",
    "node3@127.0.0.1",
    "node4@127.0.0.1"
  ]
}
$ curl -s $COUCH_URL:5984/mydb/_shards/robert | jq .
{
  "range": "60000000-7fffffff",
  "nodes": [
    "node1@127.0.0.1",
    "node3@127.0.0.1",
    "node4@127.0.0.1"
  ]
}

CouchDB показывает конкретный шард, которому сопоставлен каждый из двух примеров документов.

Перемещение шарда

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

В этом разделе описано, как вручную размещать и заменять шарды. Это важные действия, если вы решили, что кластер слишком большой или слишком маленький и хотите успешно изменить его размер, либо заметили по метрикам сервера неоптимальную структуру баз данных/шардов и отдельные «горячие точки», которые необходимо устранить.

Рассмотрим кластер из трёх узлов с q=8 и n=3. В каждой базе данных 24 шарда, распределённых между тремя узлами. Если вы добавите в кластер четвёртый узел, CouchDB не перераспределит на него шарды существующих баз данных. Это приведёт к неравномерной нагрузке: новый узел будет хранить только шарды баз данных, созданных после его присоединения к кластеру. Чтобы сбалансировать распределение шардов существующих баз данных, их необходимо переместить вручную.

Перемещение шардов между узлами кластера состоит из следующих шагов:

0. Убедитесь, что целевой узел присоединился к кластеру.

1. Скопируйте шарды и все вторичные индексы шардов на целевой узел.

2. Переведите целевой узел в режим обслуживания.

3. Обновите метаданные кластера, указав новые целевые шарды.

4. Следите за внутренней репликацией, чтобы убедиться, что шарды актуальны.

5. Отключите режим обслуживания целевого узла.

6. Снова обновите метаданные кластера, удалив исходные шарды

7. Удалите файлы шардов и файлы вторичных индексов на исходном узле.

data/shards/00000000-1fffffff/abc.1529362187.couch
data/shards/20000000-3fffffff/abc.1529362187.couch
data/shards/40000000-5fffffff/abc.1529362187.couch
data/shards/60000000-7fffffff/abc.1529362187.couch
data/shards/80000000-9fffffff/abc.1529362187.couch
data/shards/a0000000-bfffffff/abc.1529362187.couch
data/shards/c0000000-dfffffff/abc.1529362187.couch
data/shards/e0000000-ffffffff/abc.1529362187.couch

data/.shards
data/.shards/e0000000-ffffffff/_replicator.1518451591_design
data/.shards/e0000000-ffffffff/_replicator.1518451591_design/mrview
data/.shards/e0000000-ffffffff/_replicator.1518451591_design/mrview/3e823c2a4383ac0c18d4e574135a5b08.view
data/.shards/c0000000-dfffffff
data/.shards/c0000000-dfffffff/_replicator.1518451591_design
data/.shards/c0000000-dfffffff/_replicator.1518451591_design/mrview
data/.shards/c0000000-dfffffff/_replicator.1518451591_design/mrview/3e823c2a4383ac0c18d4e574135a5b08.view
...

# one one machine
$ mkdir -p data/.shards/{range}
$ mkdir -p data/shards/{range}
# on the other
$ scp {couch-dir}/data/.shards/{range}/{database}.{datecode}* \
  {node}:{couch-dir}/data/.shards/{range}/
$ scp {couch-dir}/data/shards/{range}/{database}.{datecode}.couch \
  {node}:{couch-dir}/data/shards/{range}/

http-check disable-on-404
option httpchk GET /_up

$ curl -X PUT -H "Content-type: application/json" \
    $COUCH_URL:5984/_node/{node-name}/_config/couchdb/maintenance_mode \
    -d "\"true\""

$ curl -v $COUCH_URL/_up
…
< HTTP/1.1 404 Object Not Found
…
{"status":"maintenance_mode"}

$ curl http://adm:pass@localhost:5984/_node/_local/_dbs/{name}
{
  "_id": "{name}",
  "_rev": "1-e13fb7e79af3b3107ed62925058bfa3a",
  "shard_suffix": [46, 49, 53, 51, 48, 50, 51, 50, 53, 50, 54],
  "changelog": [
    ["add", "00000000-1fffffff", "node1@xxx.xxx.xxx.xxx"],
    ["add", "00000000-1fffffff", "node2@xxx.xxx.xxx.xxx"],
    ["add", "00000000-1fffffff", "node3@xxx.xxx.xxx.xxx"],
    …
  ],
  "by_node": {
    "node1@xxx.xxx.xxx.xxx": [
      "00000000-1fffffff",
      …
    ],
    …
  },
  "by_range": {
    "00000000-1fffffff": [
      "node1@xxx.xxx.xxx.xxx",
      "node2@xxx.xxx.xxx.xxx",
      "node3@xxx.xxx.xxx.xxx"
    ],
    …
  }
}

["add", "{range}", "{node-name}"]

{
  "_id": "{name}",
  "_rev": "1-e13fb7e79af3b3107ed62925058bfa3a",
  "shard_suffix": [46, 49, 53, 51, 48, 50, 51, 50, 53, 50, 54],
  "changelog": [
    ["add", "00000000-1fffffff", "node1@xxx.xxx.xxx.xxx"],
    ["add", "00000000-1fffffff", "node2@xxx.xxx.xxx.xxx"],
    ["add", "00000000-1fffffff", "node3@xxx.xxx.xxx.xxx"],
    ...
    ["add", "00000000-1fffffff", "node4@xxx.xxx.xxx.xxx"]
  ],
  "by_node": {
    "node1@xxx.xxx.xxx.xxx": [
      "00000000-1fffffff",
      ...
    ],
    ...
    "node4@xxx.xxx.xxx.xxx": [
      "00000000-1fffffff"
    ]
  },
  "by_range": {
    "00000000-1fffffff": [
      "node1@xxx.xxx.xxx.xxx",
      "node2@xxx.xxx.xxx.xxx",
      "node3@xxx.xxx.xxx.xxx",
      "node4@xxx.xxx.xxx.xxx"
    ],
    ...
  }
}

$ curl -X PUT http://adm:pass@localhost:5984/_node/_local/_dbs/{name} -d '{...}'

$ curl -X POST $COUCH_URL:5984/{db}/_sync_shards
{"ok":true}

$ rm {couch-dir}/data/shards/{range}/{db}.{datecode}.couch
$ rm -r {couch-dir}/data/.shards/{range}/{db}.{datecode}*

Настройка размещения базы данных

Можно настроить CouchDB так, чтобы при создании базы данных реплики шардов размещались на определённых узлах согласно правилам размещения.

Сначала каждому узлу необходимо присвоить атрибут зоны. Он определяет, к какой зоне относится узел. Для этого отредактируйте документ узла в специальной базе данных /_nodes, доступной через специальный локальный для узла эндпоинт API /_node/_local/_nodes/{node-name}. Добавьте пару «ключ-значение» следующего вида:

"zone": "{zone-name}"

Повторите эти действия для всех узлов кластера. Например:

$ curl -X PUT http://adm:pass@localhost:5984/_node/_local/_nodes/{node-name} \
    -d '{ \
        "_id": "{node-name}",
        "_rev": "{rev}",
        "zone": "{zone-name}"
        }'

В качестве альтернативы можно задать на каждом узле переменную среды COUCHDB_ZONE, и CouchDB настроит этот документ при запуске.

В локальном файле конфигурации (local.ini) каждого узла задайте согласованную настройку для всего кластера, например:

[cluster]
placement = {zone-name-1}:2,{zone-name-2}:1

В этом примере CouchDB разместит две реплики шарда на узлах с атрибутом зоны {zone-name-1}, а одну реплику — на новом узле с атрибутом зоны {zone-name-2}.

Этот подход гибок: можно также задавать зоны отдельно для каждой базы данных, указывая настройку размещения в качестве параметра запроса при создании базы данных и используя тот же синтаксис, что и в ini-файле:

curl -X PUT $COUCH_URL:5984/{db}?placement={zone}

Также можно указать аргумент placement. Обратите внимание: это переопределит логику, определяющую количество создаваемых реплик!

Эту систему также можно использовать, чтобы запретить размещение реплик новых баз данных на определённых узлах кластера: для этого задайте им атрибут зоны, отсутствующий в строке размещения [cluster].

Разделение шардов

Эндпоинт /_reshard — это HTTP API для работы с шардами. В настоящее время он поддерживает только разделение шардов. Инструкции по объединению шардов см. в описании ручного процесса в разделе Объединение шардов.

Основной способ работы с /_reshard — создание заданий перераспределения шардов, наблюдение за ними, ожидание их завершения, удаление, создание новых заданий и так далее. Ниже приведены несколько шагов, которые можно выполнить для разделения шардов с помощью этого API.

Для начала полезно вызвать GET /_reshard, чтобы получить сводку о перераспределении шардов в кластере.

$ curl -s $COUCH_URL:5984/_reshard | jq .
{
  "state": "running",
  "state_reason": null,
  "completed": 3,
  "failed": 0,
  "running": 0,
  "stopped": 0,
  "total": 3
}

Следует обратить внимание на два важных параметра: общее количество заданий и их состояние.

Поле state показывает состояние перераспределения шардов в кластере. Обычно оно равно running, однако другой пользователь мог временно отключить перераспределение. В этом случае состояние будет stopped, и, будем надеяться, в значении поля state_reason будет указана причина или комментарий. Подробнее см. в разделе Остановка заданий перераспределения шардов.

Важно следить за количеством заданий total, поскольку для каждого узла установлено максимальное количество заданий перераспределения шардов. Создание новых заданий после достижения этого ограничения приведёт к ошибке. Перед запуском новых заданий рекомендуется удалить уже завершённые. Значение параметра max_jobs по умолчанию и инструкции по его изменению при необходимости см. в разделе конфигурации reshard.

Например, чтобы удалить все завершённые задания, выполните:

$ for jobid in $(curl -s $COUCH_URL:5984/_reshard/jobs | jq -r '.jobs[] | select (.job_state=="completed") | .id'); do \
      curl -s -XDELETE $COUCH_URL:5984/_reshard/jobs/$jobid \
  done

Затем рекомендуется посмотреть на карту шардов базы данных.

$ curl -s $COUCH_URL:5984/db1/_shards | jq '.'
{
  "shards": {
    "00000000-7fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ],
    "80000000-ffffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ]
  }
}

В этом примере мы разделим все копии диапазона 00000000-7fffffff. API позволяет комбинировать параметры: например, разделить все диапазоны на всех узлах, все диапазоны только на одном узле или один конкретный диапазон на одном конкретном узле. Для этого используются параметры задания db, node и range.

Чтобы разделить все копии 00000000-7fffffff, отправьте запрос следующего вида:

$ curl -s -H "Content-type: application/json" -XPOST $COUCH_URL:5984/_reshard/jobs \
  -d '{"type": "split", "db":"db1", "range":"00000000-7fffffff"}' | jq '.'
[
  {
    "ok": true,
    "id": "001-ef512cfb502a1c6079fe17e9dfd5d6a2befcc694a146de468b1ba5339ba1d134",
    "node": "node1@127.0.0.1",
    "shard": "shards/00000000-7fffffff/db1.1554242778"
  },
  {
    "ok": true,
    "id": "001-cec63704a7b33c6da8263211db9a5c74a1cb585d1b1a24eb946483e2075739ca",
    "node": "node2@127.0.0.1",
    "shard": "shards/00000000-7fffffff/db1.1554242778"
  },
  {
    "ok": true,
    "id": "001-fc72090c006d9b059d4acd99e3be9bb73e986d60ca3edede3cb74cc01ccd1456",
    "node": "node3@127.0.0.1",
    "shard": "shards/00000000-7fffffff/db1.1554242778"
  }
]

В ответе на запрос возвращены три задания — по одному для каждой из трёх копий.

Чтобы проверить ход выполнения заданий, используйте GET /_reshard/jobs или GET /_reshard/jobs/{jobid}.

В конечном итоге задания должны завершиться, а карта шардов будет выглядеть так:

$ curl -s $COUCH_URL:5984/db1/_shards | jq '.'
{
  "shards": {
    "00000000-3fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ],
    "40000000-7fffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ],
    "80000000-ffffffff": [
      "node1@127.0.0.1",
      "node2@127.0.0.1",
      "node3@127.0.0.1"
    ]
  }
}

Остановка заданий перераспределения шардов

Перераспределение шардов на уровне кластера можно остановить, а затем возобновить. Это полезно, чтобы внешние инструменты, изменяющие карту шардов, не мешали заданиям перераспределения. Чтобы остановить все задания перераспределения шардов в кластере, отправьте запрос PUT к эндпоинту /_reshard/state с ключом и значением "state": "stopped". При остановке также можно указать необязательное примечание или причину.

Например:

$ curl -s -H "Content-type: application/json" \
  -XPUT $COUCH_URL:5984/_reshard/state \
  -d '{"state": "stopped", "reason":"Moving some shards"}'
{"ok": true}

Это состояние отобразится в глобальной сводке:

$ curl -s $COUCH_URL:5984/_reshard | jq .
{
  "state": "stopped",
  "state_reason": "Moving some shards",
  "completed": 74,
  "failed": 0,
  "running": 0,
  "stopped": 0,
  "total": 74
}

Чтобы возобновить работу, отправьте запрос PUT, как в примере выше, указав состояние running. Все задания разделения шардов должны продолжиться с последней контрольной точки.

Подробнее см. в справочнике API: /_reshard.

Объединение шардов

Значение q для базы данных можно задать при её создании или увеличить позднее, разделив некоторые шарды, как описано в разделе Разделение шардов. Чтобы уменьшить q и объединить несколько шардов, необходимо создать базу данных заново. Выполните следующие шаги:

1. Если в кластере выполняются задания разделения шардов, остановите их через HTTP API, как описано в разделе Остановка заданий перераспределения шардов.

2. Создайте временную базу данных с нужными настройками шардов, указав значение q в качестве параметра запроса при выполнении операции PUT.

3. Запретите клиентам доступ к базе данных.

4. Реплицируйте основную базу данных во временную. Если основная база данных активно используется, может потребоваться выполнить репликацию несколько раз.

5. Удалите основную базу данных. Убедитесь, что никто её не использует!

6. Создайте основную базу данных заново с нужными настройками шардов.

7. Теперь клиенты снова могут обращаться к базе данных.

8. Реплицируйте данные из временной базы обратно в основную.

9. Удалите временную базу данных.

После выполнения всех шагов базу данных снова можно использовать. Кластер автоматически создаст и распределит её шарды согласно правилам размещения.

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