Защищённые окружения

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

Защита настраивается в проекте для имени окружения и в группе для уровня развёртывания. Правило группы действует на все проекты этой группы и её подгрупп.

Принцип работы защищённых окружений

Список «Разрешено развёртывать» в правиле задаёт, кто может запускать задачу развёртывания в это окружение. Он же определяет, кто может изменять, останавливать и удалять само окружение. Список «Правила одобрения» задаёт, чьё одобрение требуется для развёртывания и сколько одобрений должен дать каждый субъект.

Значение имени правила зависит от того, кому правило принадлежит:

Уровень развёртывания окружения задаётся параметром deployment_tier в конфигурационном файле CI/CD. Если параметр не указан, Deckhouse Code определяет уровень по наличию в имени окружения следующих подстрок без учёта регистра:

Строки проверяются в этом порядке, и уровень определяет первое совпадение. Окружение dev-live получает уровень development. Имя, в котором нет ни одной из этих подстрок, получает уровень other.

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

Администраторы экземпляра Deckhouse Code могут развёртывать по любому правилу и одобрять по любому правилу одобрения. Эти права, как и остальные исключения для администратора на этой странице, действуют независимо от режима администратора.

Администратор, который не состоит в проекте, получает доступ к проекту и его задачам после переключения в режим администратора, если он включён в экземпляре Deckhouse Code. Исключение — развёртывание, созданное собственной задачей администратора. Оно подчиняется разделу «Одобрение собственного развёртывания» наравне с остальными.

Предварительные требования

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

• в проекте включён механизм CI/CD;
• в конфигурационном файле CI/CD есть задача с параметром environment;
• для настройки правил проекта у пользователя есть роль Мейнтейнер или Владелец, а для настройки правил группы — роль Владелец в группе.

Правило проекта можно настроить до создания окружения. После создания окружение сразу будет защищено, если его имя совпадает с именем правила.

Защита окружения в проекте

Защитить окружение проекта можно через веб-интерфейс или API.

curl --request POST --header "PRIVATE-TOKEN: <TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "production",
    "deploy_access_levels": [{ "access_level": 40 }],
    "approval_rules": [{ "access_level": 40, "required_approvals": 2 }]
  }' \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments"

# Все правила проекта, отсортированные по имени.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments"

# Правила, унаследованные от групп проекта, вместе с группой-владельцем.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/inherited"

# Одно правило.
curl --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

# Изменение списков существующего правила.
curl --request PUT --header "PRIVATE-TOKEN: <TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{ "approval_rules": [{ "access_level": 40, "required_approvals": 1 }] }' \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

# Снятие защиты.
curl --request DELETE --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/protected_environments/<ENVIRONMENT_NAME>"

Защита окружений в группе

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

Чтобы создать правило группы:

1. Откройте группу.
2. Перейдите в «Настройки» → «CI/CD».
3. Разверните раздел «Защищённые окружения».
4. Нажмите «Добавить защищённое окружение».
5. В поле «Имя окружения» выберите уровень развёртывания:
   • «Рабочая среда»;
   • «Предпродакшен»;
   • «Тестирование»;
   • «Разработка»;
   • «Другое».
6. В списках «Разрешено развёртывать» и «Правила одобрения» выберите субъектов.
7. Нажмите «Создать защищённое окружение».

Субъекты правила группы ограничены её иерархией:

В настройках проекта правила групп отображаются в таблице «Унаследованные защищённые окружения» со ссылкой на группу-владельца в столбце «Унаследовано от» и с отметкой «Уровень деплоя» рядом с именем. Такое правило нельзя изменить или удалить в проекте. Чтобы изменить его, откройте настройки группы-владельца.

Чтобы создать правило группы через API, используйте /groups/:id/protected_environments с теми же параметрами, что и для правила проекта. При этом параметр name должен содержать только уровень развёртывания; для любого другого значения API возвращает 400.

Разрешения на развёртывание

Список «Разрешено развёртывать» определяет, кто может запускать задачу развёртывания в окружение. В списке можно комбинировать роли, отдельных пользователей и группы. Доступ получает каждый, кто подходит хотя бы под один из пунктов.

Доступные варианты:

Селектор «Членство в группе» принимает следующие значения:

Если список «Разрешено развёртывать» пуст, в таблице отображается «Никто». При этом:

• участники проекта не могут запускать задачу развёртывания в это окружение независимо от роли;
• развёртывание остаётся доступно администраторам экземпляра Deckhouse Code;
• пустой список любого действующего правила запрещает развёртывание в окружение, даже если другое действующее правило его разрешает;
• пустой список правила группы отменяет разрешения правила проекта.

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

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

• запускать;
• отменять;
• перезапускать;
• очищать.

Изменения роли или членства в группе учитываются сразу при проверке прав.

Правила одобрения

В правиле одобрения задаются субъект и необходимое количество одобрений. Поле «Требуемые одобрения» принимает значения от 1 до 5. Для субъекта-пользователя оно всегда равно 1, поскольку один пользователь принимает по правилу одно решение.

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

Решение относится к одному правилу, а одобрения всех правил учитываются вместе.

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

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

Управление защищённым окружением

Изменение любых настроек защищённого окружения, а также его остановка и удаление доступны пользователям из списка «Разрешено развёртывать». Одной роли Мейнтейнер для этого недостаточно. На администраторов экземпляра Deckhouse Code ограничение не распространяется.

Действие «Очистить окружения» останавливает устаревшие окружения, кроме защищённых. Запущенными остаются окружения, имя которых указано в правиле проекта, а также окружения с уровнем, указанным в унаследованном правиле группы.

Одобрение развёртывания

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

Чтобы открыть страницу развёртывания, перейдите в «Деплои» → «Окружения», откройте окружение и выберите нужное развёртывание в истории. Если развёртывание ожидает одобрений, в истории отображаются статус «Ожидание» и кнопка «Посмотреть одобрения развёртывания», а в списке «Окружения» и в шапке страницы — отметка «Требуется одобрение».

curl --request POST --header "PRIVATE-TOKEN: <TOKEN>" \
  "https://<HOST>/api/v4/projects/<PROJECT_ID>/deployments/<DEPLOYMENT_ID>/approval?status=approved"

Одобрение собственного развёртывания

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

Чтобы разрешить такому пользователю одобрять развёртывание, перейдите в «Настройки» → «CI/CD» → «Защищённые окружения». В разделе «Параметры одобрения» установите флажок «Разрешить инициатору pipeline одобрять развёртывания» и нажмите «Сохранить изменения». Настройка действует для всего проекта и по умолчанию выключена.

Автором развёртывания считается пользователь его задачи, а для задачи без пользователя — пользователь развёртывания.

Поведение задачи развёртывания

Перед назначением раннера для задачи развёртывания в защищённое окружение проверяются права пользователя задачи, а если у задачи нет пользователя — права пользователя пайплайна.

Результат проверки определяет, что происходит с задачей.

• Если действующие правила содержат правила одобрения, Deckhouse Code создаёт развёртывание и переводит задачу в ручной режим независимо от прав автора пайплайна. Задачу нельзя запустить, пока одобрения не собраны или развёртывание отклонено.
• После того как каждое правило собрало свои одобрения, задача не запускается автоматически. Пользователь запускает её вручную. Право на запуск задачи и списки «Разрешено развёртывать» проверяются для того, кто её запускает.
• Если действующие правила не содержат правил одобрения, а пользователю развёртывание не разрешено, задача завершается с причиной «ошибка доступа к защищённому окружению» до создания развёртывания и назначения раннера.
• Задача, которая выполняет развёртывание в незащищённое окружение, выполняется как обычно.

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

Отклонённое развёртывание

Первое принятое решение об отклонении завершает задачу развёртывания с причиной «развёртывание отклонено», а развёртывание переходит в состояние ошибки. Состояние развёртывания обновляет фоновая задача, поэтому оно меняется с задержкой.

Параметр retry не перезапускает отклонённую задачу развёртывания; её может перезапустить только пользователь. Отклонённое развёртывание сохраняет этот статус до перезапуска задачи. При перезапуске создаются новая задача и новое развёртывание, которое собирает одобрения заново без переноса решений по предыдущему развёртыванию.

Доступ к защищённым окружениям

Доступные действия зависят от роли пользователя и правил окружения:

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

Экспорт и импорт защищённых окружений

Экспорт проекта содержит защищённые окружения проекта вместе с записями списка «Разрешено развёртывать» и правилами одобрения. Принятые решения не экспортируются, поскольку относятся к конкретному развёртыванию, а экспорт переносит только конфигурацию проекта.

Для поиска субъектов на целевом экземпляре Deckhouse Code экспорт сохраняет:

• полный путь группы-субъекта;
• полный путь группы, которой принадлежит проект;
• имя пользователя-субъекта.

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

Если субъекта сопоставить нельзя или устаревшее поле required_approval_count в экспорте содержит любое значение, кроме 0, импорт проекта отклоняется целиком. Импорт с потерянным субъектом дал бы более слабую защиту, чем исходная конфигурация.

События аудита

Deckhouse Code записывает следующие события аудита для защищённых окружений:

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

При изменении принятого решения создаётся новое событие, а при повторе того же решения — нет.

Исключение участника из проекта и отзыв доступа группы к проекту удаляют записи доступа к развёртыванию и правила одобрения этого субъекта без отдельного события. Само исключение уже записано.

Устранение проблем

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

Задача завершилась с ошибкой доступа к защищённому окружению

Пользователь задачи не указан в списке «Разрешено развёртывать» одного из действующих правил либо его учётная запись удалена. Проверьте следующее:

• пользователь должен соответствовать хотя бы одной записи каждого списка «Разрешено развёртывать» правила проекта для этого имени окружения и правил групп для его уровня;
• списки «Разрешено развёртывать» не пусты, поскольку пустой список запрещает развёртывание всем;
• роль пользователя в проекте не ниже роли, выбранной в списке.

Задача развёртывания не запускается

Если у окружения есть правила одобрения, задача остаётся ручной, пока каждое правило не соберёт свои одобрения. Откройте страницу развёртывания и проверьте состояние правил в разделе «Одобрения развёртывания».

Задача также недоступна пользователю, который не указан в списке «Разрешено развёртывать», в том числе после одобрения развёртывания.

Окружение нельзя изменить, остановить или удалить

Изменение любых настроек защищённого окружения, а также его остановка и удаление доступны пользователям из списка «Разрешено развёртывать». Добавьте пользователя в этот список в правиле для данного имени окружения и в правилах групп для его уровня.

Форма одобрения не отображается

Проверьте следующее:

• развёртывание ожидает одобрений, при этом его задача находится в ручном режиме, а сводное состояние отличается от «Все необходимые одобрения получены» и от отклонения;
• ваша учётная запись подходит под правило одобрения этого окружения либо вы уже приняли решение по одному из его правил;
• развёртывание создано не вашей задачей либо в проекте включена настройка «Разрешить инициатору pipeline одобрять развёртывания». Отклонить собственное развёртывание автор может и без этой настройки.

Субъекта нельзя добавить в правило

Сообщение «У субъекта уже есть правило для этого защищённого окружения» означает, что роль, пользователь или группа уже указаны в списке, который вы изменяете. Субъекту отводится одна запись в списке «Разрешено развёртывать» и одна запись в списке «Правила одобрения». Измените существующую запись вместо добавления второй.

Влияние изменений правил на принятые решения

Состояние развёртывания вычисляется по текущим правилам.

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

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

Отклонение продолжает действовать в обоих случаях.

Правило группы не применяется к окружению

Проверьте, что уровень развёртывания окружения совпадает с именем правила группы и что проект входит в группу, которой принадлежит правило, или в одну из её подгрупп. Уровень задаётся параметром deployment_tier в конфигурационном файле CI/CD, а иначе определяется по имени окружения.

Правило проекта не применяется к окружению с похожим именем

Имя окружения должно точно совпадать с именем правила проекта с учётом регистра. Поэтому правило Production не защищает окружение production, а правило production — окружение production/eu. Чтобы защитить несколько окружений сразу, используйте правило группы для соответствующего уровня развёртывания.

Унаследованное правило нельзя изменить в проекте

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

Дополнительные ресурсы

• Непрерывная сборка и поставка ПО (CI/CD)
• Защищённые ветки