---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ydb.tech/docs/en/devops/deployment-options/manual/bridge-management.md?version=main
  - https://ydb.tech/docs/ru/devops/deployment-options/manual/bridge-management.md?version=main
sourcePath: ru/core/devops/deployment-options/manual/bridge-management.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

## Управление кластером в режиме bridge

<!-- source: ru/_includes/feature_enterprise.md -->
{% note info "Функциональность Корпоративной СУБД Яндекса" %}

Данная функциональность доступна только в [Корпоративной СУБД Яндекса](https://ydb.tech/docs/ru/downloads/yandex-enterprise-database.md?version=main). В open-source версии YDB она отсутствует.

{% endnote %}
<!-- endsource: ru/_includes/feature_enterprise.md -->

Ниже приведены типовые операции для кластера в [режиме bridge](https://ydb.tech/docs/ru/concepts/bridge.md?version=main) с использованием [соответствующих команд YDB CLI](https://ydb.tech/docs/ru/reference/ydb-cli/commands/bridge/index.md?version=main).

### Посмотреть текущее состояние {#list}

Показывает текущее состояние каждого pile, настроенного на кластере YDB.

```bash
ydb admin cluster bridge list
```

Пример вывода:

```bash
pile-a: PRIMARY
pile-b: SYNCHRONIZED
```

### Плановая смена `PRIMARY` (switchover) {#switchover}

Если известно, что в обозримом будущем запланированы плановые работы в датацентре или на оборудовании, на котором работает текущий `PRIMARY` pile, то рекомендуется заранее переключить кластер на использование другого pile в роли `PRIMARY`. Выберите другой pile в состоянии `SYNCHRONIZED`, чтобы переключить его в состояние `PRIMARY` следующей командой:

```bash
ydb admin cluster bridge switchover --new-primary <pile>
```

Переключение выполняется плавно: роли проходят через `PRIMARY/PROMOTED` и завершаются в состоянии `SYNCHRONIZED/PRIMARY`.

### Плановое отключение pile (takedown) {#takedown}

Если плановые работы приведут к недоступности одного из pile, его необходимо вывести из кластера перед их началом с помощью следующей команды:

```bash
ydb admin cluster bridge takedown --pile <pile>
# если отключаете текущий PRIMARY:
ydb admin cluster bridge takedown --pile <current-primary> --new-primary <synchronized-pile>
```

При выполнении операции pile переводится в `SUSPENDED`, затем — в `DISCONNECTED`; дальнейшие операции с кластером выполняются без участия отключённого pile.

Если отключается текущий `PRIMARY` и не было возможности [сменить его заранее](#switchover), то эти операции можно совместить, указав новый `PRIMARY` в аргументе `--new-primary`, который должен быть в состоянии `SYNCHRONIZED`.

```bash
ydb admin cluster bridge takedown --pile <pile>
# если отключаете текущий PRIMARY:
ydb admin cluster bridge takedown --pile <current-primary> --new-primary <synchronized-pile>
```

{% note warning %}

Перед началом плановых работ обязательно убедитесь через команду [list](#list), что операция вывода pile из кластера завершилась успешно и все pile находятся в ожидаемом состоянии.

{% endnote %}

### Аварийное отключение недоступного pile (failover) {#failover}

Так как между pile работает синхронная репликация, то при неожиданном выходе одного из них из строя работа кластера по умолчанию останавливается, и необходимо принять решение, продолжать ли работу кластера без этого pile. Это решение может принимать как человек (например, дежурный DevOps-инженер), так и внешняя по отношению к кластеру YDB автоматизация.

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

```bash
ydb admin cluster bridge failover --pile <unavailable-pile>
```

Если недоступен текущий `PRIMARY`, необходимо добавить параметр `--new-primary` с указанием имени pile в состоянии `SYNCHRONIZED`. Если параметр не указан или указан некорректно, команда завершится с ошибкой без изменений в кластере.

```bash
ydb admin cluster bridge failover --pile <unavailable-pile>
# если недоступен текущий PRIMARY:
ydb admin cluster bridge failover --pile <unavailable-primary> --new-primary <synchronized-pile>
```

Недоступный pile будет переведён в состояние `DISCONNECTED`, а при указании нового `PRIMARY` произойдёт переключение этой роли. Если остальные pile находятся в состояниях, отличных от `SYNCHRONIZED`, аварийное отключение также может быть выполнено. Допустимые переходы зависят от текущей пары состояний и приведены на [диаграмме состояний](https://ydb.tech/docs/ru/concepts/bridge.md?version=main#pile-states) и в [таблице переходов](https://ydb.tech/docs/ru/concepts/bridge.md?version=main#transitions-between-states).

{% note warning %}

Если включена обязательная аутентификация, то в аварийном состоянии кластера аутентификация по логину и паролю не может быть использована — используйте аутентификацию по клиентским сертификатам. Подробнее см. [Особенности аутентификации в аварийном состоянии кластера](#emergency-auth).

{% endnote %}

### Вернуть pile в кластер (rejoin) {#rejoin}

После завершения плановых работ или устранения причин отказа ранее отключённые pile необходимо явным образом вводить обратно в эксплуатацию следующей командой:

```bash
ydb admin cluster bridge rejoin --pile <pile>
```

Сразу после запуска операции pile переходит в состояние `NOT_SYNCHRONIZED` и запускается фоновый процесс синхронизации данных; по её завершении pile автоматически становится `SYNCHRONIZED`. Дождавшись этого состояния, при необходимости можно [переключить роль `PRIMARY` на данный pile](#switchover).

### Особенности аутентификации в аварийном состоянии кластера {#emergency-auth}

Команды управления кластером в режиме bridge требуют прав администратора кластера. Если включена обязательная аутентификация ([`enforce_user_token_requirement: true`](https://ydb.tech/docs/ru/reference/configuration/security_config.md?version=main)), то в штатном режиме работы кластера доступны все способы аутентификации, включая [аутентификацию по логину и паролю](https://ydb.tech/docs/ru/security/authentication.md?version=main#static-credentials).

Однако при отказе pile кластер приостанавливает обслуживание запросов до выполнения [failover](#failover). В этом состоянии аутентификация по логину и паролю не может быть использована: для проверки учётных данных нужен доступ к [SchemeShard](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#scheme-shard), который недоступен на кластере в аварийном состоянии. Попытка входа завершается ошибкой:

```text
SchemeShard is unreachable
```

Единственный способ аутентификации, доступный в аварийном состоянии кластера, — [аутентификация по клиентским сертификатам](https://ydb.tech/docs/ru/reference/configuration/client_certificate_authorization.md?version=main). Клиентский сертификат проверяется локально узлом, принявшим запрос, поэтому такая проверка не зависит от доступности кластера в целом.

Аутентификация по клиентским сертификатам должна быть настроена на кластере заранее:

1. Секция [`client_certificate_authorization`](https://ydb.tech/docs/ru/reference/configuration/client_certificate_authorization.md?version=main) конфигурации кластера должна присваивать подключениям с доверенным клиентским сертификатом [SID](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#access-sid) административной группы:

    ```yaml
    client_certificate_authorization:
      request_client_certificate: true
      client_certificate_definitions:
        - member_groups: ["ADMINS"]
          subject_terms:
          - short_name: "O"
            values: ["YDB"]
    ```

2. Этот SID должен входить в список `administration_allowed_sids` секции [`security_config`](https://ydb.tech/docs/ru/reference/configuration/security_config.md?version=main):

    ```yaml
    security_config:
      enforce_user_token_requirement: true
      administration_allowed_sids:
      - "root"
      - "ADMINS"
    ```

Если кластер развёрнут по [инструкции по развёртыванию](https://ydb.tech/docs/ru/devops/deployment-options/manual/initial-deployment/deployment-configuration-v2.md?version=main), эти настройки уже включены в конфигурацию, а в качестве клиентского сертификата подойдут файлы `node.crt` и `node.key` из каталога `~/CA/certs/` на любом узле кластера.

Для аутентификации по клиентскому сертификату укажите его в глобальных опциях YDB CLI `--client-cert-file` и `--client-cert-key-file`. Подключаться необходимо к узлу работоспособного pile. Пример выполнения failover:

```bash
ydb -e grpcs://<node.ydb.tech>:2135 \
    --ca-file ca.crt \
    --client-cert-file node.crt \
    --client-cert-key-file node.key \
    admin cluster bridge failover --pile <unavailable-pile> --new-primary <synchronized-pile>
```

где:

- `<node.ydb.tech>` — FQDN узла в работоспособном pile;
- `ca.crt` — сертификат доверенного центра сертификации кластера;
- `node.crt`, `node.key` — клиентский сертификат и приватный ключ к нему, удовлетворяющие требованиям секции `client_certificate_authorization`.

{% note warning %}

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

{% endnote %}