Работа с окружениями в SourceCraft

Окружение — набор секретов и настроек доступа для определенной среды работы приложения. Например, окружения staging и production позволяют использовать одинаковую конфигурацию рабочего процесса CI/CD для развертывания на разных стендах, подставляя разные наборы секретов.

В SourceCraft можно определить, кто получает доступ к секретам окружения и управляет ими. Секреты используются в заданиях CI/CD, а ссылки между окружениями позволяют подключать общие секреты организации, проекта или репозитория.

Подробнее на странице Окружения в SourceCraft.

На этой странице описано, как:

• Подготовиться к работе.
• Создать окружение.
• Добавить секреты.
• Подключить другое окружение и настроить приоритеты.
• Настроить доступ.
• Использовать окружение в CI/CD.
• Изменить окружение.
• Удалить окружение.

Перед началом работы

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

• На организацию — роль Администратор организации или выше.
• На проект — роль Ответственный за проект или выше.
• На репозиторий — роль Ответственный за репозиторий или выше.

Секретами и ссылками управляет пользователь с ролью Ответственный за окружение или выше. Для изменения прав доступа нужна роль Администратор окружения, а для чтения секретов — Разработчик окружения или выше.

В примерах используются окружения репозитория staging и production. Для общих настроек можно создать окружение shared в организации или проекте и подключить его к окружениям репозитория.

Создать окружение

1. Откройте главную страницу SourceCraft.

2. Выберите организацию, проект или репозиторий, которому будет принадлежать окружение.

3. В настройках выбранного ресурса откройте раздел Окружения. В репозитории он находится в секции Настройки репозитория.

4. Нажмите Новое окружение.

5. В поле Название укажите имя, например staging.

   Имя должно быть уникально в пределах выбранного ресурса и содержать от 3 до 63 символов: строчные латинские буквы, цифры и дефис. Первый символ — буква, последний — буква или цифра.

6. В поле Описание опишите назначение окружения, например Проверка веб-приложения перед выпуском.

7. Нажмите Создать.

Вы автоматически получите в созданном окружении роль Администратор окружения.

Для примера из раздела Использовать окружение в CI/CD повторите шаги и создайте в том же репозитории окружение production с описанием Продуктовая среда веб-приложения.

Добавить секреты

Откройте окружение и перейдите на вкладку Секреты.

Добавить внутренний секрет

1. В блоке Секреты окружения нажмите Создать секрет.
2. Выберите тип Внутренний.
3. В поле Название укажите название секрета, например API_TOKEN. Используйте прописные латинские буквы, цифры и символ подчеркивания.
4. В поле Значение введите значение, например токен доступа к API приложения для выбранной среды.
5. Нажмите Добавить секрет.

В окружениях staging и production создайте секреты с одинаковым названием API_TOKEN, но разными токенами. В конфигурации CI/CD используйте одно выражение ${{ secrets.API_TOKEN }}, а нужное окружение выбирайте параметром environment рабочего процесса.

Подключить секрет из Yandex Lockbox

1. Подготовьте секрет и сервисное подключение с правом чтения содержимого секрета Yandex Lockbox.

2. В блоке Секреты окружения нажмите Создать секрет.

3. В открывшемся диалоге настройте секрет:

   1. Выберите тип Yandex Lockbox.
   2. В поле Название задайте название, по которому будете обращаться к секрету из CI/CD.
   3. В поле Сервисное подключение выберите сервисное подключение, подготовленное ранее.
   4. В поле Секрет Lockbox выберите секрет Yandex Lockbox.
   5. (Опционально) Чтобы подключить только часть ключей, нажмите Выбрать ключи. В блоке Ключи payload нажмите названия нужных ключей, например DB_USER и DB_PASSWORD. Нужно выбрать хотя бы один ключ. Если не настраивать выбор, будут добавлены все ключи секрета.
   6. Нажмите Добавить секрет.

Например, если вы задали название DB_CREDENTIALS, для обращения к ключу DB_PASSWORD подключенного секрета используйте в CI/CD выражение ${{ secrets.DB_CREDENTIALS#DB_PASSWORD }}.

Изменить или удалить внутренний секрет

1. Чтобы изменить значение, в строке внутреннего секрета нажмите Редактировать.
2. В открывшемся диалоге нажмите Показать значение, чтобы разблокировать поле Значение.
3. Введите новое значение и нажмите Сохранить изменения.

Для удаления нажмите Удалить секрет в строке внутреннего секрета и подтвердите удаление.

Секреты из подключенных окружений изменяются в окружении-источнике при наличии соответствующих прав. Чтобы переопределить значение только для текущего окружения, создайте в нем собственный секрет с тем же ключом. Для изменения секретов нужна роль Ответственный за окружение или выше в соответствующем окружении.

Подключить другое окружение

1. Создайте окружение с общими секретами, например shared в организации, и добавьте в него нужные секреты.
2. Откройте окружение репозитория, например production, и перейдите на вкладку Ссылки на секреты.
3. В блоке Секреты из других окружений нажмите Добавить ссылку на окружение.
4. В открывшемся диалоге выберите окружение, например shared. У каждого окружения указаны его владелец и описание.
5. Нажмите Добавить ссылку.
6. Если подключено несколько окружений, расставьте их в нужном порядке, перетаскивая строки за ручку слева. При одной ссылке ручка не отображается.
7. На вкладке Обзор включите Унаследованные секреты и проверьте итоговый список секретов и их источники. Без этой настройки отображаются только собственные секреты окружения.

Секрет ищется по ключу в следующем порядке:

1. В собственных секретах текущего окружения.
2. В подключенных окружениях по порядку ссылок, начиная с первого приоритета. Для каждой ссылки сначала проверяется подключенное окружение, затем его ссылки.
3. В секретах, созданных непосредственно в организации, проекте или репозитории, которому принадлежит текущее окружение.

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

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

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

Отключить окружение

1. На вкладке Ссылки на секреты в блоке Секреты из других окружений найдите подключенное окружение и нажмите Удалить в его строке.
2. В открывшемся диалоге нажмите Удалить ссылку на окружение.

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

Настроить доступ

1. Откройте окружение и перейдите на вкладку Доступы.
2. Нажмите Добавить участника.
3. В поле Пользователи или команды выберите пользователя или команду.
4. В поле Роль назначьте нужную роль окружения.
5. Нажмите Добавить.

Например, в staging назначьте команде разработки роль Разработчик окружения. В production назначьте эту роль участникам, которые будут запускать рабочие процессы с секретами продуктовой среды. Для просмотра информации об окружении без доступа к значениям секретов достаточно роли Просмотр окружения.

Чтобы изменить роль участника, в столбце Роль рядом с ролью нажмите , выберите новую и нажмите Обновить.

Для удаления участника в его строке нажмите и подтвердите удаление.

Использовать окружение в CI/CD

1. Настройте CI/CD в репозитории.

2. Создайте в репозитории окружения staging и production, добавьте в каждое секрет API_TOKEN с токеном доступа к API соответствующей среды.

3. Назначьте права участникам, которые будут запускать рабочие процессы с этими секретами.

4. В файл .sourcecraft/ci.yaml добавьте рабочие процессы:

   workflows:
     check-staging:
       environment: staging
       tasks:
         - name: check-api
           env:
             API_TOKEN: ${{ secrets.API_TOKEN }}
             API_URL: https://staging.example.com/api/status
           cubes:
             - name: request-status
               script:
                 - sh ./check-api.sh
   
     check-production:
       environment: production
       tasks:
         - name: check-api
           env:
             API_TOKEN: ${{ secrets.API_TOKEN }}
             API_URL: https://example.com/api/status
           cubes:
             - name: request-status
               script:
                 - sh ./check-api.sh
   

   Замените адреса в API_URL на адреса API вашего приложения. В этом примере открытые адреса заданы непосредственно в конфигурации CI/CD, а токены хранятся в окружениях. Задания используют одинаковое обращение к секрету и один скрипт; набор секретов выбирается параметром environment рабочего процесса, на одном уровне с tasks.

   Примечание

   Окружение выбирается параметром environment рабочего процесса и используется для всех его заданий. В выражении secrets имя окружения не указывается. Например, при environment: production выражение ${{ secrets.API_TOKEN }} получает секрет через окружение production с учетом порядка поиска. Если параметр environment не задан, используются секреты самого репозитория.

5. Добавьте в корень репозитория файл check-api.sh. Например, если API принимает запрос GET с токеном в заголовке Authorization, скрипт проверки может выглядеть так:

   #!/bin/sh
   set -eu
   
   curl --fail --silent --show-error \
     --header "Authorization: Bearer ${API_TOKEN}" \
     "${API_URL}"
   

   Для этого примера на воркере должен быть доступен curl. Адаптируйте запрос под API вашего приложения. При ответе с кодом ошибки HTTP скрипт завершится с ошибкой.

6. Сохраните оба файла в репозитории.

7. Запустите вручную рабочий процесс check-staging для нужной ветки или тега и проверьте результат запуска CI/CD.

8. Чтобы проверить продуктовую среду, запустите check-production от имени участника с доступом к секретам production.

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

Изменить окружение

1. Откройте страницу окружения.

2. В правом верхнем углу нажмите Редактировать.

3. Измените название или описание.

4. Нажмите Обновить окружение.

5. Если изменили название, обновите параметр environment в рабочих процессах CI/CD.

   Например, при переименовании staging в preprod замените environment: staging на environment: preprod. Выражение ${{ secrets.API_TOKEN }} останется прежним.

Удалить окружение

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

Например, перед удалением временного окружения preprod обновите параметр environment в рабочих процессах .sourcecraft/ci.yaml: укажите другое существующее окружение с необходимыми секретами. Иначе новые запуски с environment: preprod завершатся с ошибкой.

Полезные ссылки

• Окружения в SourceCraft
• Задания (tasks)
• Управлять секретами в репозитории SourceCraft
• Настроить интеграцию с Yandex Lockbox в SourceCraft
• Работа с переменными окружения в SourceCraft
• Настроить ручное подтверждение заданий CI/CD в SourceCraft