Creating a test agent

Written by

Yandex Cloud

Updated at November 14, 2025

Setting up the infrastructure
Creating a test agent
Creating a temporary test agent

Setting up the infrastructure

Create a service account for your test agent:
1. Create a service account named sa-loadtest in the folder that will host the agent to generate the load.
2. Assign the loadtesting.generatorClient role to the service account.
Configure a test agent security group.

Creating a test agent

Note

If you need an agent for one-off use, you can create a temporary agent. A temporary test agent will be created for a particular test and deleted once the test is over.

If you do not have an SSH key pair yet, create one.
Create an agent:
Management console

CLI
1. In the management console, select the folder where you want to create the agent.
2. In the list of services, select Load Testing.
3. In the Agents tab, click Create agent.
4. Enter a name for the agent, e.g., agent-008.
5. Specify the same availability zone as the one hosting your test target.
6. Under Agent:
  - Select the appropriate agent type. For more information, see Agent performance.
  - Specify the subnet hosting your test target. Make sure you created and set up a NAT gateway in that subnet.
  - If you have access to security groups, select a preset agent security group.
7. Under Access, specify the agent access credentials:
  - Select the sa-loadtest service account.
  - Under Login, enter the username.
    
    Alert
    
    Do not use root or other reserved usernames. To perform operations requiring root privileges, use the sudo command.
  - In the SSH key field, paste the contents of the public key file.
8. Click Create.
9. Wait for the VM to create. Make sure the agent status has changed to Ready for test.
  Note
  
  If the agent creation process has stopped at Initializing connection, make sure the following conditions are met:
  
  The agent has a public IP address and access to loadtesting.api.cloud.yandex.net:443.
  
  The target subnet has a configured NAT gateway.
  
  The service account assigned to the agent has the required roles.
If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.
1. See the description of the CLI command for creating an agent:
  yc loadtesting agent create --help
2. Select the same availability zone as the one hosting your test target.
3. Select the subnet hosting your test target. Make sure you created and set up a NAT gateway in that subnet.
  
  To get a list of available subnets using the CLI, run this command:
  yc vpc subnet list
  Result:
  +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+ | ID | NAME | NETWORK ID | ROUTE TABLE ID | ZONE | RANGE | +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+ | e2lfkhps7bol******** | default-ru-central1-b | enpnf7hajqmd******** | | ru-central1-b | [10.129.0.0/24] | | e9bgnq1bggfa******** | default-ru-central1-a | enpnf7hajqmd******** | | ru-central1-a | [10.128.0.0/24] | | fl841n5ilklr******** | default-ru-central1-d | enpnf7hajqmd******** | | ru-central1-d | [10.130.0.0/24] | +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
4. Select the security group. Make sure to configure the security group in advance.
  
  To get a list of available security groups using the CLI, run this command:
  yc vpc security-group list
  Result:
  +----------------------+---------------------------------+--------------------------------+----------------------+ | ID | NAME | DESCRIPTION | NETWORK-ID | +----------------------+---------------------------------+--------------------------------+----------------------+ | enp414a2tnnp******** | default-sg-enpnf7hajqmd******** | Default security group for | enpnf7hajqmd******** | | | | network | | | enpctpve7951******** | sg-load-testing-agents | | enpnf7hajqmd******** | | enpufo9ms0gi******** | sg-load-testing-targets | | enpnf7hajqmd******** | +----------------------+---------------------------------+--------------------------------+----------------------+
5. Get the ID of sa-loadtest service account, specifying its name:
  yc iam service-account get sa-loadtest
  Result:
  id: ajespasg04oc******** folder_id: b1g85uk96h3f******** created_at: "2024-12-04T17:38:57Z" name: sa-loadtest last_authenticated_at: "2024-12-12T19:10:00Z"
6. Create an agent in the default folder:
  yc loadtesting agent create \ --name agent-008 \ --labels origin=default,label-key=label-value \ --zone default-ru-central1-a \ --network-interface subnet-id=e9bgnq1bggfa********,security-group-ids=enpctpve7951******** \ --cores 2 \ --memory 2G \ --service-account-id ajespasg04oc******** --metadata-from-file user-data=metadata.yaml
  Where:
  - --name: Agent name.
  - --labels: Agent labels.
  - --zone: Availability zone to host the agent.
  - --network-interface: Agent network interface settings:
    
    subnet-name: ID of the selected subnet.
    
    security-group-ids: Security group IDs.
  - --cores: Number of CPU cores the agent can use.
  - --memory: Amount of RAM allocated to the agent.
  - --service-account-id: Service account ID.
  - --metadata-from-file: <key>=<value> pair with the name of the file containing the public SSH key path. For an example of the metadata.yaml configuration file, see VM metadata.
  For more information on how to create an agent with the CLI, see the Yandex Cloud Examples repository.
Assign a public IP address to your agent to enable access over SSH:
Management console

CLI
1. In the management console, select the folder with the agent.
2. Select Compute Cloud.
3. Select the agent-008 VM.
4. Under Network interface, in the top-right corner, click and select Add public IP address.
5. In the window that opens:
  - In the Public address field, select Auto.
  - Click Add.
To assign a public IP address to an agent, run the following CLI command:
```
yc compute instance add-one-to-one-nat \
  --id=<VM_ID> \
  --network-interface-index=<VM_network_interface_number> \
  --nat-address=<IP_address>
```
Where:
- --id: VM ID. You can get a list of available VM IDs in the folder using the yc compute instance list CLI command.
- --network-interface-index: VM network interface number. The default value is 0. To get a list of VM network interfaces and their numbers, run yc compute instance get <VM_ID>.
- --nat-address: Public IP address to assign to the VM. This is an optional setting. If you skip it, the VM will get a public IP address automatically.
  
  You can get a list of reserved public IP addresses available in the folder using the yc vpc address list CLI command. The IP address and the VM must be in the same availability zone.
Here is a possible use case:
```
yc compute instance add-one-to-one-nat \
  --id=fhmsbag62taf******** \
  --network-interface-index=0 \
  --nat-address=51.250.*.***
```
Result:
```
id: fhmsbag62taf********
folder_id: b1gv87ssvu49********
created_at: "2022-05-06T10:41:56Z"
...
network_settings:
  type: STANDARD
placement_policy: {}
```
For more information about the yc compute instance add-one-to-one-nat command, see the CLI reference.

Creating a temporary test agent

Management console

In the management console, select the folder for testing.
In the list of services, select Load Testing.
In the Tests tab, click Create test.
In the Agents section, click Temporal.
Under Temporal agent settings:
- Select a suitable agent type. For more information, see Agent performance.
Warning

To run a temporary test agent, first assign these additional roles to your sa-loadtest service account: compute.editor, iam.serviceAccounts.user, vpc.user, and vpc.publicAdmin.
- Select the sa-loadtest service account.
- Specify the subnet hosting your test target.
- If you have access to security groups, select a preset agent security group.

Creating a test agent

Setting up the infrastructureSetting up the infrastructure

Creating a test agentCreating a test agent

Creating a temporary test agentCreating a temporary test agent

Was the article helpful?

Setting up the infrastructure

Creating a test agent

Creating a temporary test agent