Соединение CLI с базой данных и аутентификация

Большинство команд YDB CLI относится к операциям над базой данных YDB и требует соединения с ней для исполнения.

YDB CLI определяет, с какой БД необходимо соединиться и какой режим аутентификации использовать из следующих источников (в порядке убывания приоритета):

Командной строки
Профиля, выбранного опцией командной строки --profile
Переменных окружения
Активированного профиля

Для того чтобы YDB CLI попробовал соединиться с БД, в результате исполнения данных шагов должен быть определен эндпоинт и путь базы данных.

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

О возможных ситуациях, когда YDB CLI не будет пытаться соединиться с БД, читайте ниже в секции Сообщения об ошибках.

Параметры командной строки

Опции соединения c БД в командной строке указываются перед определением команды и её параметров:

ydb <опции_соединения> <команда> <опции_команды>

-e, --endpoint <endpoint> — эндпоинт - основной параметр соединения, позволяющий найти сервер YDB в сети. Если порт не указан, применяется 2135. Если протокол не указан, то в публичных сборках YDB CLI применяется gRPCs (с шифрованием).
-d, --database <database> — путь базы данных.

Режим и параметры аутентификации выбираются заданием одной из перечисленных ниже опций:

--token-file <filepath> : используется режим аутентификации Access Token, в качестве которого используется содержимое файла, указанное в значении данной опции
--yc-token-file <filepath> : используется режим аутентификации Refresh Token, в качестве которого используется содержимое файла, указанное в значении данной опции
--use-metadata-credentials : используется режим аутентификации Metadata
--sa-key-file <filepath> : используется режим аутентификации Service Account Key, а ключ и другие параметры загружаются из JSON-файла, указанного в значении данной опции

--user <username> : используется режим аутентификации по логину и паролю, в качестве логина используется значение данной опции. Дополнительно могут быть указаны:
- --password-file <filename> : пароль читается из контента указанного файла
- --no-password : определяет пустой пароль
  Пароль будет запрошен в интерактивном режиме в случае, если в параметрах командной строки не указана ни одна из опций определения пароля из перечисленных выше.

--oauth2-key-file <filepath> : используется режим аутентификации OAuth 2.0 token exchange, а ключ и другие параметры загружаются из JSON файла, указанного в значении данной опции. Опция --iam-endpoint используется для задания endpoint для обмена токена в формате <schema>://<host>:<port>/<path> (через параметр YDB CLI, профиль либо переменную окружения).

Если в командной строке задано одновременно несколько из перечисленных выше опций, то CLI выдаст ошибку с просьбой указать ровно одну:

$ ydb --use-metadata-credentials --iam-token-file ~/.ydb/token scheme ls
More than one auth method were provided via options. Choose exactly one of them
Try "--help" option for more info.

При использовании режимов аутентификации, предусматривающих ротацию токена с его периодическим перезапросом в IAM (Refresh Token, Service Account Key, OAuth 2.0 token exchange), может быть установлен специальный параметр, указывающий где размещен сервис IAM:

--iam-endpoint <URL> : Задает URL сервиса IAM для обращения за новыми токенами в режимах аутентификации, подразумевающих ротацию токенов. Значение по умолчанию — "iam.api.cloud.yandex.net".

Параметры из профиля, выбранного опцией командной строки

Если в командной строке при вызове YDB CLI не указан какой-либо параметр соединения, то CLI производит попытку его определения по профилю, выбранному опцией командной строки --profile.

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

Параметры из переменных окружения

Если в командной строке не был явно указан профиль или в нём не заданы отвечающие за аутентификацию параметры, то YDB CLI пытается определить режим и параметры аутентификации по окружению YDB CLI по следующему алгоритму:

Eсли задано значение переменной окружения IAM_TOKEN, то используется режим аутентификации Access Token, в который передается значение данной переменной
Иначе, если задано значение переменной окружения YC_TOKEN, то используется режим аутентификации Refresh Token, а токен для передачи на IAM endpoint при перезапросе берется из значения этой переменной
Иначе, если задано значение переменной окружения USE_METADATA_CREDENTIALS, равное 1, то используется режим аутентификации Metadata
Иначе, если задано значение переменной окружения SA_KEY_FILE, то используется режим аутентификации Service Account Key, а ключ загружается из файла, имя которого указано в данной переменной

Если задано значение переменной окружения YDB_USER или YDB_PASSWORD, то используется режим аутентификации по логину и паролю. Логин считывается из переменной YDB_USER; если он не задан, то выдается ошибка User password was provided without user name. Пароль считывается из переменной YDB_PASSWORD; если она не задана, то в зависимости от наличия опции командной строки --no-password применяется либо пустой пароль, либо пароль будет запрошен интерактивно.

Иначе, если задано значение переменной окружения YDB_OAUTH2_KEY_FILE, то используется режим аутентификации OAuth 2.0 token exchange, а параметры для обмена токена загружаются из JSON файла, имя которого указано в данной переменной. Опция --iam-endpoint используется для задания endpoint для обмена токена в формате <schema>://<host>:<port>/<path> (через параметр YDB CLI, профиль либо переменную окружения).

Параметры из активированного профиля

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

Сообщения об ошибках

Ошибки до попытки установки соединения с БД

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить эндпоинт, то выполнение команды будет прервано с выдачей сообщения Missing required option 'endpoint'.

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить путь базы данных, то выполнение команды будет прервано с выдачей сообщения Missing required option 'database'.

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

(No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028) -- не удалось открыть на чтение файл <filepath>, указанный в одном из параметров, где передается имя файла с путем

Дополнительные параметры

При использовании протокола gRPCs (с шифрованием) может потребоваться выбор корневого сертификата:

--ca-file <filepath> : Файл корневого PEM-сертификата для TLS-соединения

Проверка аутентификации

Сервисная команда YDB CLI discovery whoami позволяет проверить, под какой учетной записью вы фактически аутентифицировались на сервере.