Настроить в SourceCraft сервисное подключение к Yandex Cloud

Сервисные подключения — это безопасный способ интеграции ваших проектов SourceCraft с ресурсами Yandex Cloud.

Сервисные подключения позволяют изнутри процессов СI/CD вашего репозитория SourceCraft получить доступ к API Yandex Cloud. Например, вы можете запросить секрет из Yandex Lockbox, загрузить файлы в бакет Yandex Object Storage, развернуть виртуальную машину в Yandex Compute Cloud и прочее.

При этом вам не требуется хранить в секретах репозитория и тем более в коде каких-либо долгоживущих токенов или ключей доступа. Аутентификация в Yandex Cloud осуществляется с помощью короткоживущего IAM-токена Yandex Identity and Access Management, который запрашивается внутри каждого конкретного задания CI/CD.

Cм. подробнее про сервисные подключения.

В инструкции в качестве примера будет показан процесс получения списка функций Yandex Cloud Functions.

Чтобы настроить сервисное подключение:

  1. Создайте сервисный аккаунт Yandex Cloud.
  2. Назначьте роль сервисному аккаунту.
  3. Создайте сервисное подключение.
  4. Подготовьте конфигурацию CI/CD.
  5. Проверьте работу сервисного подключения.

Создайте сервисный аккаунт Yandex Cloud

Сервисный аккаунт — аккаунт, от имени которого программы могут управлять ресурсами в Yandex Cloud.

Чтобы создать сервисный аккаунт:

  1. Войдите в консоль управления Yandex Cloud.

  2. В левой части экрана нажмите на строку с именем каталога, к ресурсам которого вы хотите настроить доступ из SourceCraft.

  3. В списке сервисов выберите Identity and Access Management.

  4. Нажмите кнопку Создать сервисный аккаунт.

  5. Введите имя сервисного аккаунта.

    Требования к формату имени:

    • длина — от 2 до 63 символов;
    • может содержать строчные буквы латинского алфавита, цифры и дефисы;
    • первый символ — буква, последний — не дефис.

    Имя сервисного аккаунта должно быть уникальным в рамках облака.

  6. Нажмите кнопку Создать.

См. подробнее про создание сервисного аккаунта.

Назначьте роль сервисному аккаунту

Роль — это набор разрешений, который определяет допустимые операции с ресурсами в Yandex Cloud.

Чтобы назначить сервисному аккаунту роль на каталог:

  1. В консоли управления Yandex Cloud выберите каталог с сервисным аккаунтом, созданным ранее.

  2. Перейдите на вкладку Права доступа.

  3. Нажмите кнопку Настроить доступ.

  4. В открывшемся окне выберите раздел Сервисные аккаунты.

  5. Выберите нужный сервисный аккаунт из списка или воспользуйтесь поиском.

  6. Нажмите кнопку Добавить роль и выберите роль из списка или воспользуйтесь поиском.

    Например, назначьте сервисному аккаунту роль functions.viewer для доступа к просмотру функций в Cloud Functions.

  7. Нажмите кнопку Сохранить.

Создайте сервисное подключение

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

  2. Перейдите на вкладку Организации.

  3. Выберите организацию.

  4. На странице организации в разделе Настройки перейдите в секцию Сервисные Подключения.

  5. Нажмите Новое Сервисное Подключение.

  6. В открывшемся окне:

    • В блоке Базовая информация укажите имя сервисного подключения, например default-service-connection, опционально добавьте описание.

    • В блоке Область применения выберите, для каких репозиториев и веток будет доступно сервисное подключение.

    • В блоке Настройки Yandex Cloud выберите:

      • Каталог, к ресурсам которого вы хотите настроить доступ из SourceCraft.
      • Сервисный аккаунт, созданный ранее.

      Совет

      Чтобы повторно запросить список облаков, каталогов и сервисных аккаунтов из Yandex Cloud, нажмите Синхронизировать. Это может быть полезно, если параллельно с созданием сервисного подключения вы создали каталог или сервисный аккаунт.

  7. Нажмите Создать Сервисное Подключение.

    Дождитесь окончания операции. На открывшейся странице будут представлены детали сервисного подключения, а также содержание блоков tokens и env для дальнейшей интеграции в CI/CD.

    В Yandex Cloud будет автоматически создана федерация сервисных аккаунтов Yandex Identity and Access Management.

    Чтобы посмотреть параметры созданного OIDC-провайдера, в блоке Федерация cервисных аккаунтов нажмите на имя федерации.

Подготовьте конфигурацию CI/CD

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

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

  3. На вкладке Домой в секции Ваша мастерская перейдите в раздел Репозитории и выберите репозиторий.

  4. На странице репозитория в разделе Код перейдите в секцию Ветки.

  5. Выберите ветку для внесения изменений.

  6. Откройте файл .sourcecraft/ci.yaml.

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

  8. Добавьте в конфигурацию CI/CD полученные ранее блоки tokens и env.

    Вы можете получить IAM-токен с помощью готового кубика от команды SourceCraft. Ниже приведен пример конфигурации CI/CD, в которой IAM-токен используется при аутентификации в Yandex Cloud CLI для получения списка функций Cloud Functions.

    tokens:
  # Произвольное имя токена.
  <имя_токена>:
    # Имя сервисного подключения, созданного ранее.
    service_connection: <имя_сервисного_подключения>
    # Область запроса доступа:
    # org — все репозитории.
    # repo — конкретный репозиторий.
    # ref — ветка или тег.
    scope: repo

workflows:
  test-workflow:
    tasks:
      - name: sample-task
        cubes:
          # Кубик обменивает токен SourceCraft на IAM-токен Yandex Cloud
          # и сохраняет его в переменную IAM_TOKEN в блоке outputs.
          - name: get-iam-token
            env:
              ID_TOKEN: ${{ tokens.<имя_токена>.id_token }}
              YC_SA_ID: ${{ tokens.<имя_токена>.service_account_id }}
              # Также вы можете получить идентификаторы каталога и облака
              # YC_FOLDER_ID: ${{ tokens.<имя_токена>.folder_id }}
              # YC_CLOUD_ID: ${{ tokens.<имя_токена>.cloud_id }}
            image: cr.yandex/sourcecraft/yc-iam:latest

          # Кубик с предустановленным Yandex Cloud CLI забирает из outputs 
          # переменную IAM_TOKEN и использует ее для получения списка функций Cloud Functions.
          - name: get-functions
            env:
              # Подставьте в блок для получения значений outputs имя кубика с
              # IAM-токеном, например get-iam-token.
              YC_IAM_TOKEN: ${{ cubes.<имя_кубика_с_IAM-токеном>.outputs.IAM_TOKEN }}
              YC_FOLDER_ID: ${{ tokens.<имя_токена>.folder_id }}
            image: 
              name: cr.yandex/sourcecraft/yc-cli:latest
              entrypoint: ""
            script:
              - |
                yc config set folder-id $YC_FOLDER_ID
                yc serverless function list

on:
  push: test-workflow

    Совет

    Вы можете взаимодействовать с Yandex Cloud напрямую через API или воспользоваться следующими инструментами:

    • Yandex Cloud CLI — для аутентификации передайте IAM-токен в переменную окружения YC_IAM_TOKEN, а в командах используйте параметры --cloud-id и --folder-id с указанием идентификаторов облака и каталога.
    • Terraform — для аутентификации передайте IAM-токен в переменную окружения YC_TOKEN, в переменные окружения YC_CLOUD_ID и YC_FOLDER_ID передайте идентификаторы облака и каталога.
    • SDK — аутентификация аналогична API.

  9. В правом верхнем углу нажмите Сохранить изменения.

  10. В открывшемся окне настройте параметры внесения изменений:

    • В поле Сообщение об изменениях укажите комментарий, который опишет внесенные изменения.
    • В блоке Ветка изменений выберите, в какую ветку внести изменения. При необходимости создайте новую ветку.
    • В блоке Действие после сохранения изменений выберите, как внести изменения: с помощью коммита или предложения изменений.

  11. Подтвердите внесение изменений.

    Если вы решили внести изменения через предложение изменений, завершите его создание.

Проверьте работу сервисного подключения

  1. На странице репозитория в разделе Код перейдите в секцию Автоматизации.

  2. Выберите запущенный рабочий процесс.

  3. На открывшейся странице будут отображены задания рабочего процесса, шаги задания — кубики, а также статусы и результаты выполнения.

  4. В правом нижнем углу кубика get-functions нажмите .

    Пример логов выполнения кубика get-functions:

    +----------------------+--------+----------------------+--------+
|          ID          |  NAME  |      FOLDER ID       | STATUS |
+----------------------+--------+----------------------+--------+
| d4e5l4qjepst******** | test-1 | b1gveg9vude9******** | ACTIVE |
+----------------------+--------+----------------------+--------+

Совет

Срок жизни IAM-токена составляет 12 часов. Однако в целях безопасности рекомендуется досрочно прекращать его действие после использования. Подробнее см. на странице Отзыв IAM-токена.

См. также

Предыдущая
Настроить пользовательский воркер
Следующая
Добавить файл или папку