Группы общих переменных окружения

Группа переменных окружения содержит значения, которые нужны нескольким проектам Orbit, например общий ключ API или учетные данные базы данных, в одном месте. Свяжите группу с проектами, которым она нужна, и каждая их сборка получит эти переменные, так что ротация ключа это одно редактирование вместо шести.

Где находятся группы переменных окружения

Откройте Orbit и выберите Env groups из навигации верхнего уровня. Страница называется Shared env var groups и описывает их как группы уровня аккаунта, общие для нескольких проектов Orbit.

Группы находятся выше проектов. Собственные переменные проекта находятся на его вкладке Env vars: см. Переменные окружения в Orbit.

Когда использовать группу

Тест прост: одно и то же значение вставляется в несколько проектов?

Хорошие кандидаты:

• Общий ключ аналитики или отслеживания ошибок, используемый каждым интерфейсом.
• Строка подключения для чтения реплики, используемая несколькими внутренними инструментами.
• Ключ API третьей стороны для сервиса, с которым взаимодействует весь аккаунт.
• Общий токен клиента флага функции.

Плохие кандидаты:

• Что-либо специфичное для одного проекта. Оно принадлежит этому проекту.
• Что-либо, что отличается между production и preview. Группы не работают по окружению, поэтому значение, которое меняется в зависимости от окружения, должно находиться в собственных переменных окружения проекта.

Создание группы

1. Нажмите New group.
2. Дайте ей Group name, до 64 символов. Назовите её в зависимости от того, что она содержит, например, сервис, к которому принадлежат учетные данные.
3. Добавьте опциональное Description.
4. Нажмите Create group.

Аккаунт может содержать до 20 групп. Когда вы находитесь на лимите, кнопка показывает (limit reached) и создание ещё одной отклоняется.

Добавление переменных

Откройте группу и используйте раздел Variables:

1. Нажмите Add variable.
2. Введите ключ и значение.
3. Установите флажок Mark as secret для чего-либо конфиденциального.
4. Нажмите Save group.

Переменная, отмеченная как секретная, хранится в зашифрованном виде, и её значение не возвращается в панель впоследствии. Список показывает ключ и индикатор Marked as secret (hidden) вместо значения. Несекретные значения остаются видимыми, чтобы вы могли проверить их с первого взгляда.

Чтобы изменить значение секрета, введите новое и сохраните. Чтобы удалить переменную, нажмите Remove на её строке и сохраните.

Связывание проектов

Раздел Linked projects перечисляет каждый проект в аккаунте. Нажмите на проект, чтобы связать или отвязать его; связанные проекты выделены. Сохраните группу, чтобы применить изменения.

Группа без связанных проектов ничего не делает, и в разделе говорится No projects yet, пока вы не свяжете один.

Переменные группы вставляются во время сборки, поэтому связывание проекта влияет на его следующую сборку, а не на развертывание, которое в данный момент находится в production. Если вам нужно изменение прямо сейчас, переразвертайте: см. Развертывание вашего проекта.

Приоритет

Правило указано на странице: переменные группы вставляются во время сборки, и переменные уровня проекта и уровня окружения имеют приоритет над переменными группы.

Другими словами, побеждает наиболее конкретное:

1. Переменные уровня окружения, наивысший приоритет.
2. Переменные уровня проекта.
3. Переменные группы, наименьший приоритет.

Этот порядок полезен, а не просто технический момент. Установите общее значение по умолчанию в группе и переопределите его на одном проекте, который нуждается в чём-то другом, без удаления этого проекта из группы. См. Переменные окружения по окружению для уровня окружения.

Это также объясняет наиболее частую путаницу с группами: вы редактируете группу, переразворачиваете, и ничего не меняется, потому что проект имеет собственную переменную с тем же ключом, которая тихо побеждает. Сначала проверьте вкладку Env vars самого проекта, когда значение группы кажется игнорируемым.

Ротация общих учетных данных

Это рабочий процесс, для которого существуют группы:

1. Создайте новые учетные данные у поставщика, оставив старые активными.
2. Отредактируйте значение в группе и сохраните.
3. Переразвертайте каждый связанный проект или дождитесь его следующего развертывания.
4. Убедитесь, что каждый проект работает с новыми учетными данными.
5. Отозовите старые учетные данные у поставщика.

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

Удаление группы

Нажмите delete на группе. Подтверждение конкретно указывает на последствие: будущие сборки потеряют эти переменные, а уже завершенные сборки не будут затронуты.

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

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

Практические советы

Держите группы небольшими и целеустремленными. Одна группа на внешний сервис лучше, чем одна гигантская "общая" группа, потому что это позволяет вам связать ровно те проекты, которым нужна каждая вещь.

Называйте ключи одинаково везде. Если один проект читает SENTRY_DSN и другой читает SENTRY_KEY, общая группа не может вам помочь. Сначала стандартизируйте имена.

Не помещайте учетные данные production в группу, связанную с проектами с открытыми предпросмотрами. Переменные группы достигают каждой сборки связанного проекта, включая предпросмотры.

Устранение неполадок

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

Значение неправильно во время выполнения. Переменная уровня проекта или уровня окружения с тем же ключом переопределяет её. Проверьте вкладку Env vars проекта.

Создание группы недоступно. Вы находитесь на лимите 20 групп, или ваша роль на аккаунте это не владелец или администратор.

Значение секрета показывается как пусто. Это правильно. Значения секретов не возвращаются в панель после сохранения.

Проект сломался после редактирования группы. Откатите значение назад в группе и переразвертайте, затем выясните, какой проект не согласился. Откат развертывания приводит работающий сайт в порядок, пока вы это делаете.

Что дальше

• Переменные окружения в Orbit для переменных уровня проекта.
• Переменные окружения по окружению для уровня переопределения.
• Параметры проекта Orbit для остальной части конфигурации проекта.