О lookup-плагине hashi_vault

Особенности lookup-плагина hashi_vault

Из-за истории lookup-плагина hashi_vault он выполняет множество задач. Он универсален, но порой его поведение трудно предугадать.

Lookup-плагин hashi_vault выполняет три основные задачи:

• аутентификация: принимает параметры для различных типов входа в систему, выполняет вход и получает токен, с помощью которого может отправлять дополнительные запросы в Vault;
• универсальное чтение: позволяет читать данные из любого пути Vault, не требуя специальной реализации для конкретного типа пути;
• преобразование ответов, похожих на ответы kv2, в более простые ответы, напоминающие ответы kv1.

Чаще всего этот плагин используют для чтения секретов. Самое распространённое хранилище секретов — встроенное в Vault хранилище kv (ключ-значение). В большинстве реализаций используется версия 2 хранилища kv. Чтобы упростить чтение секретов kv версии 2, lookup-плагин предполагает, что вы, вероятно, пытаетесь прочитать секрет kv, и пытается определить, получен ли ответ от kv2, поскольку ответы версии 2 содержат метаданные, а значение секрета дополнительно заключено в другую структуру. Lookup-плагин преобразует ответы kv2 так, чтобы они были похожи на ответы версии 1.

Поскольку хранилище kv содержит одну или несколько пар ключ-значение в каждом секрете, lookup-плагин также поддерживает нестандартный суффикс в пути, позволяющий получить значение, относящееся к одному конкретному ключу, с помощью синтаксиса :keyname. Это удобно для компактного обращения к одному значению секрета (что, стоит признать, является очень распространённым сценарием), но усложняет реализацию и приводит к формированию нежелательных привычек.

Например, стало обычным делом использовать множество вызовов lookup-плагина с одним и тем же путём, но разными значениями :keyname, чтобы получить несколько значений из одного секрета. Однако это весьма неэффективно: для каждого вызова отдельно выполняются вход в систему и чтение секрета, хотя возвращается одно и то же значение, а разыменование ключа выполняется на стороне клиента. Кроме того, разыменование можно выполнить непосредственно в Jinja, где происходящее будет понятнее, используя синтаксис .key или ['key'].

Ещё одна особенность плагина — возможность указывать все его параметры в строке термина. Это выглядит компактно, но значительно усложняет обработку параметров плагина. Когда этот lookup-плагин был создан, многие другие lookup-плагины позволяли указывать параметры в строке термина, однако с тех пор такой подход стали считать антипаттерном, и его использование в основных плагинах было объявлено устаревшим или прекращено.

Ещё один недостаток такого подхода — невозможность эффективно повторно использовать токен аутентификации, когда передано несколько строк термина напрямую или через with_community.hashi_vault.hashi_vault. В результате при таком использовании выполняется новый вход в систему для каждого термина. В новых lookup-плагинах можно выполнить несколько операций после одного входа в систему.

Все эти особенности объяснимы в контексте, но несколько затуманивают назначение lookup-плагина:

• Если ответ от совершенно другой конечной точки окажется похожим на ответ kv2, результат будет неожиданным.
• Если попытаться напрямую указать путь к секрету kv2, это не сработает, пока в путь не будет добавлен компонент /data/, чтобы он соответствовал пути API, а не привычному пользователям пути.
• Если нужно получить метаданные вместе с ответом kv2, сделать это невозможно.
• Другие возможности kv2, например управление версиями секретов, нельзя использовать напрямую, если не изменить URL, что чревато ошибками и неочевидно.
• Получить токен, созданный при внутреннем входе в систему, чтобы использовать его повторно, невозможно.

Как мы учитываем эти особенности

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

Кроме того, теперь можно напрямую выполнить вход в систему и вернуть токен для последующего повторного использования с помощью community.hashi_vault.vault_login модуля и lookup-плагина.

Универсальное чтение (не только для kv) по-прежнему важно, поэтому для этого мы предлагаем community.hashi_vault.vault_read модуль и lookup-плагин, которые не пытаются определить, получен ли ответ от конкретного бэкенда.

Поскольку чтение из хранилища kv — наиболее распространённый сценарий использования, для него есть специализированный контент:

• community.hashi_vault.vault_kv1_get модуль
• community.hashi_vault.vault_kv2_get модуль
• community.hashi_vault.vault_kv1_get lookup-плагин
• community.hashi_vault.vault_kv2_get lookup-плагин

Разыменование словаря с помощью синтаксиса :keyname не будет поддерживаться в других элементах контента. В Jinja для этого можно использовать:

• синтаксис с точкой .keyname
• синтаксис lookup-плагина ['keyname']
• специализированные фильтры в некоторых случаях, например vault_login_token фильтр.

Другие lookup-плагины не будут поддерживать параметры в строке термина. Разработчики основного проекта не рекомендуют такой подход и уже предприняли шаги по удалению этой функциональности из основного проекта там, где она ещё сохраняется. Однако в плагине hashi_vault она останется для обратной совместимости, поскольку, вероятно, всё ещё широко используется.

Будущее lookup-плагина hashi_vault

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

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

Маловероятно, что в lookup-плагин hashi_vault будут добавляться или приниматься новые функции и возможности, за исключением тех, которые появляются «бесплатно», например новых методов аутентификации (для них не нужно менять код самого плагина).