Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@vitaly4n
vitaly4n authored Sep 27, 2024
1 parent e0aab72 commit 8fc9c5b
Showing 1 changed file with 94 additions and 100 deletions.
194 changes: 94 additions & 100 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,85 +4,76 @@

Взаимодействие с Yandex Load Testing (запуск тестов, создание и удаление агентов нагрузочного тестирования) будет осуществляться с помощью экшенов, опубликованных в официальном аккаунте Yandex Cloud на GitHub: https://github.com/yandex-cloud/yc-github-loadtesting-ci.

> Публично доступные примеры настроенных workflow:
> - [YC Load Testing example actions CI](https://github.com/yandex-cloud/yc-github-loadtesting-ci/actions/workflows/example.yml) в репозитории yandex-cloud/yc-github-loadtesting-ci;
> - [Performance tests](https://github.com/yandex/pandora/actions/workflows/perftest.yml) для генератора нагрузки Pandora в репозитории yandex/pandora;
> [!TIP]
> Примеры workflow:
> - [yandex-cloud/yc-github-loadtesting-ci: YC Load Testing example actions CI](https://github.com/yandex-cloud/yc-github-loadtesting-ci/actions/workflows/example.yml) - пример из репозитория с экшенами
> - [yandex/pandora: Performance tests](https://github.com/yandex/pandora/actions/workflows/perftest.yml) - перф-тесты генератора нагрузки Pandora
## 0. Подготовка

Используя интерфейс консоли управления Yandex Cloud:
Ознакомьтесь с сервисом Yandex Load Testing; используя веб интерфейс консоли управления Yandex Cloud, проведите тесты, которые планируете запускать в CI.

#### 0.1. Создайте (зарегистрируйте) агента, с которого будет проводиться нагрузочный тест

Согласно идеологии Yandex Load Testing, нагрузка тестируемого сервиса должна осуществляться вычислительных мощностей, находящихся под контролем пользователя. Одна самостоятельная еденица подачи нагрузки (Виртуальная Машина, ПК) называется агентом нагрузочного тестирования.

Инструкции по созданию (регистрации) и подключению агентов НТ:
См.:
- [Создание агента в Compute Cloud](https://yandex.cloud/ru/docs/load-testing/operations/create-agent)
- [Создание внешнего агента](https://yandex.cloud/ru/docs/load-testing/tutorials/loadtesting-external-agent)

#### 0.2. Проведите нагрузочные тесты

О том, как начать пользоваться сервисом и создать свои первые тесты, можно узнать в разделе "Практические руководства" в [документации сервиса](https://yandex.cloud/ru/docs/load-testing/).
См. "Практические руководства" в [документации сервиса](https://yandex.cloud/ru/docs/load-testing/).

#### 0.3. Сохраните файлы конфигураций тестов и тестовые данные

---

## 1. Настройка инфраструктуры

### 1.1. Создайте сервисный аккаунт, от имени которого будет осуществляться создание тестов и управления агентами

1. [Создайте](https://yandex.cloud/ru/docs/iam/quickstart-sa) сервисный аккаунт;

2. Выдайте созданному аккаунту необходимые роли:

<details><summary>Обязательные роли</summary>

- `loadtesting.loadTester`

</details>

<details><summary>(опционально) Роли, необходимые для передачи хранимых в репозитории файлов на исполняющего тесты агента</summary>

В общем случае, во время выполнения теста, агент не имеет доступ к файлам в вашем репозитории. Сделать их доступными для скачивания можно, например, загрузив в Object Storage перед запуском теста.

Необходимые для этого роли:

- `storage.editor` (глобальная роль в каталоге)
- `editor` (ACL конкретного бакета, через который будет происходить обмен файлами)

</details>

<details><summary>(опционально) Роли, необходимые для автоматического создания/удаления агентов из Github Actions</summary>

- `iam.serviceAccounts.user`
- `compute.editor`
- `vpc.user`
- `vpc.publicAdmin`

</details>

3. [Создайте](https://yandex.cloud/ru/docs/iam/concepts/authorization/key) авторизованный ключ для сервисного аккаунта, сохраните `json` файл с ключом локально на диск;

4. Преобразуйте сохраненный файл авторизованного ключа в base64, воспользовавшись стандартной утилитой командной строки:
### 1.1. Создайте сервисный аккаунт, от имени которого будет осуществляться создание тестов и управление агентами

1. [Создайте сервисный аккаунт](https://yandex.cloud/ru/docs/iam/quickstart-sa) в используемом для нагрузочного тестирования каталоге
2. Назначте на созданный аккаунт необходимые роли:
- Обязательные:
- `loadtesting.loadTester`
- Опциональные:
- Для создания и удаления агентов нагрузочного тестирования в Compute Cloud:
- `iam.serviceAccounts.user`
- `compute.editor`
- `vpc.user`
- `vpc.publicAdmin`
- Для заливки файлов в Object Storage:
- `storage.editor` (либо как клобальную роль в каталоге, либо в ACL конкретного бакета)
3. [Создайте авторизованный ключ](https://yandex.cloud/ru/docs/iam/concepts/authorization/key) для сервисного аккаунта, сохраните `json` файл с ключом локально на диск
4. Преобразуйте сохраненный файл ключа в base64, воспользовавшись стандартной утилитой командной строки:

```bash
cat authorized_key.json | base64 > authorized_key.json.pem
```

> [!NOTE]
> Object Storage может использоваться как промежуточное хранилище необходимых для корректной работы теста файлов,
> к которым у агента изначально нет доступа:
> - хранящиеся в репозитории файлы с тестовыми данными
> - собираемые в рамках workflow исполняемые файлы генераторов)
> - ...

> [!WARNING]
> Для того, чтобы агент имел возможность скачать файлы из бакета Object Storage, его сервисному аккаунту должна быть выдана роль `storage.viewer`.

### 1.2. Определите необходимые секреты и переменные в настройках GitHub репозитория

Со страницы вашего GitHub репозитория, перейдите в **Settings -\> Secrets and variables -\> Actions** и добавьте:
В настройках вашего GitHub репозитория, перейдите в раздел **Secrets and variables** -\> **Actions** и добавьте**:

- Секреты:
1. `YC_LOADTESTING_KEY_JSON_BASE64`: `******` - в качестве значения, вставьте содержимое закодированного в base64 файла авторизованного ключа (см. выше).
- Переменные:
1. `YC_LOADTESTING_FOLDER_ID`: `aje*****************` - значение должно соответствовать идентификатору каталога, в котором будут создаваться тесты
2. `YC_LOADTESTING_AGENT_SA_ID`: `b1g*****************` - значение должно соответствовать идентификатору сервисного аккаунта, используемого для авторизации исполняющего тесты агента

> Инструкция по добавлению секретов в репозиторий: [GitHub Security Guides](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)

> Инструкция по добавлению переменных в репозиторий: [GitHub Security Guides](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)
> [!TIP]
> Подробные инструкции:
> - [GitHub Security Guides: как добавить секрет](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)
> - [GitHub Security Guides: как добавить переменную](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)

---

Expand All @@ -94,8 +85,10 @@
- (опционально) файлы с тестовыми данными;
- (опционально) файл `meta.json` с дополнительными параметрами теста (имя, описание, метки, файлы Object Storage, и т.д; см. инструкцию ниже);

> Подробнее о структуре файлов и задании параметров теста: [README-howto-add-test.md](README-howto-add-test.md).
> [!IMPORTANT]
> О структуре файлов и задании параметров теста: [README-howto-add-test.md](README-howto-add-test.md).

> [!TIP]
> Примеры: [sample-tests](sample-tests/).

---
Expand All @@ -104,55 +97,62 @@

### 3.1. Запуск тестов

1. Используя консоль управления, создайте (или подключите внешний) агент нагрузочного тестирования с именем `lt-manual-agent`;
2. Убедитесь, что агент успешно подключился к сервису - статус должен быть `READY_FOR_TEST`;
3. Добавьте шаг с запуском нагрузочного теста на этом агенте:

```yaml
name:
on:
- workflow_dispatch
jobs:
deploy-service:
runs-on: ubuntu-latest
steps:
- run: 'echo "Here we deploy"'
loadtesting-run-smoke:
name: 'execute sample-tests/smoke'
continue-on-error:true
needs:
- deploy-service
runs-on: ubuntu-latest
steps:
# используем actions/checkout для того, чтобы получить доступ к файлам
# в репозитории
- uses: actions/checkout@v4
# используем yandex-cloud/yc-github-loadtesting-ci/test-suite для запуска тестов
- id: run
# экшен для запуска
uses: yandex-cloud/yc-github-loadtesting-ci/test-suite@main
with:
# значение секрета с авторизованным ключом
auth-key-json-base64: ${{ secrets.YC_LOADTESTING_KEY_JSON_BASE64 }}
# идентификатор каталога, в котором будет сохранятся информация
# о запусках тестов.
folder-id: ${{ vars.YC_LOADTESTING_FOLDER_ID }}
# фильтр, по которому сервис будет определять, какой агент (один или несколько)
# должен выполнять тест
agent-filter: "name='lt-manual-agent'"
# перечисление директорий с конфигурациями тестов.
# одна директория - один запущенный тест
test-directories: |-
"${{ github.workspace }}/sample-tests/smoke
```
> Подробнее о параметрах запуска: [Документация yandex-cloud/yc-github-loadtesting-ci/test-suite](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-test-suite).
> [!NOTE]
> Спецификация экшена test-suite: [yandex-cloud/yc-github-loadtesting-ci/test-suite](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-test-suite).

1. Используя консоль управления, создайте (или подключите внешний) агент нагрузочного тестирования с именем `lt-manual-agent`
2. Убедитесь, что агент успешно подключился к сервису - статус должен быть `READY_FOR_TEST`
3. Добавьте шаг с запуском нагрузочного теста на этом агенте
```yaml
name:
on:
- workflow_dispatch
jobs:
deploy-service:
runs-on: ubuntu-latest
steps:
- run: 'echo "Here we deploy"'
loadtesting-run-smoke:
name: 'execute sample-tests/smoke'
continue-on-error:true
needs:
- deploy-service
runs-on: ubuntu-latest
steps:
# используем actions/checkout для того, чтобы получить доступ к файлам
# в репозитории
- uses: actions/checkout@v4
# используем yandex-cloud/yc-github-loadtesting-ci/test-suite для запуска тестов
- id: run
# экшен для запуска
uses: yandex-cloud/yc-github-loadtesting-ci/test-suite@main
with:
# значение секрета с авторизованным ключом
auth-key-json-base64: ${{ secrets.YC_LOADTESTING_KEY_JSON_BASE64 }}
# идентификатор каталога, в котором будет сохранятся информация
# о запусках тестов.
folder-id: ${{ vars.YC_LOADTESTING_FOLDER_ID }}
# фильтр, по которому сервис будет определять, какой агент (один или несколько)
# должен выполнять тест
agent-filter: "name='lt-manual-agent'"
# перечисление директорий с конфигурациями тестов.
# одна директория - один запущенный тест
test-directories: |-
"${{ github.workspace }}/sample-tests/smoke
```
4. Запустите workflow
После первого запуска, результаты выполнения теста (и возможные ошибки) можно будет посмотреть на странице workflow.
### 3.2. (Опционально) Автоматическое создание и удаление агентов
> [!NOTE]
> Спецификация экшена agents-create: [yandex-cloud/yc-github-loadtesting-ci/agents-create](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-agents-create).
> [!NOTE]
> Спецификация экшена agents-delete: [yandex-cloud/yc-github-loadtesting-ci/agents-delete](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-agents-delete).
В целях экономии ресурсов и гарантированной изоляции среды выполнения тестов, можно модифицировать workflow так, чтобы агенты создавались и удалялись автоматически:
```yaml
Expand Down Expand Up @@ -237,10 +237,6 @@ jobs:
agent-ids: ${{ needs.loadtesting-create-agent.outputs.agent-ids }}
```

> Подробнее о параметрах запуска экшена создания агентов: [Документация yandex-cloud/yc-github-loadtesting-ci/agents-create](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-agents-create).

> Подробнее о параметрах запуска экшена удаления агентов: [Документация yandex-cloud/yc-github-loadtesting-ci/agents-delete](https://github.com/yandex-cloud/yc-github-loadtesting-ci/tree/main?tab=readme-ov-file#action-agents-delete).

По сравнению с предыдущим шагом, в примере выше произошли следующие изменения:

- добавлен job `loadtesting-create-agent` для создания агента;
Expand All @@ -249,8 +245,6 @@ jobs:
- условие `if: always()` нужно для того, чтобы удаление агентов происходило даже в случае возникновения ошибки на предыдущих шагах;
- `agent-ids: ${{ needs.loadtesting-create-agent.outputs.agent-ids }}` гарантирует, что удаляться будут только те агенты, которые были созданы на шаге `loadtesting-create-agent`;
---
### 4. (Дополнтительно) Настройте графики регрессий
## 4. (Дополнтительно) Настройте графики регрессий для запускаемых в CI тестов
Чтобы следить за эволюцией производительности сервиса/теста во времени, вы можете создать и настроить [графики регрессий](https://yandex.cloud/ru/docs/load-testing/concepts/load-test-regressions).
Чтобы следить за эволюцией производительности сервиса/теста во времени, вы можете создать и настроить [графики регрессий](https://yandex.cloud/ru/docs/load-testing/concepts/load-test-regressions).

0 comments on commit 8fc9c5b

Please sign in to comment.