Running external agents for load testing

You can use Yandex Load Testing for service load testing with external agents.

An external agent is a physical or virtual server with the load testing tool and load generators, which is hosted outside Load Testing.

Running load testing and viewing its results from an external agent is similar to doing that from the Load Testing agent. For more information, see Getting started with Yandex Load Testing.

Load testing with an external agent is used when:

• The testing target includes multiple instances, and the total inbound and outgoing traffic from them does not exceed the Load Testing agent capacity.
• The requests being sent to the testing target require large computing capacity.
• The information security rules require that the agent resides in its own infrastructure.
• Compute Cloud VM computing resources are limited.

To run load testing using an external agent:

1. Get your cloud ready.
2. Set up your infrastructure.
3. Configure the environment.
4. Install the external agent.
5. Run the external agent.
6. Create a test.
7. View the testing results.

If you no longer need the connected external agent, delete it from Load Testing.

Getting startedGetting started

Sign up in Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or register a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Required paid resourcesRequired paid resources

At the Preview stage, Load Testing is free of charge.

Set up your infrastructureSet up your infrastructure

Set up a service accountSet up a service account

1. Create a service account, e.g., sa-loadtest, in the folder where you are going to connect the external agent.

2. Assign the loadtesting.editor and loadtesting.generatorClient roles to the service account.

3. Create authorized keys for the service account.

   Save public and private keys as a single file by clicking Download file with keys.

Create a secret with authorized keysCreate a secret with authorized keys

Configure the environmentConfigure the environment

1. Install and initialize the Yandex Cloud CLI.

2. Install and run Docker.

3. Authenticate in Container Registry as a user or with a Docker credential helper.

   Use the endpoint of the registry with external agent Docker images: cr.yandex/yc/.

Install the external agentInstall the external agent

1. Pull a Docker image with the external agent by running this command:

   docker pull cr.yandex/yc/ya-lt-agent:latest
   

   Result:

   latest: Pulling from yc/ya-lt-agent
   df6635ed1257: Pull complete 
   7a51fa4387ba: Pull complete 
   Digest: sha256:fad262e94a8b4021b13336ae31c738ec1e77eb6a8971528429c67d28********
   Status: Downloaded newer image for cr.yandex/yc/ya-lt-agent:latest
   cr.yandex/yc/ya-lt-agent:latest
   

2. Download the file with the public and private authorized keys from Lockbox:

   yc lockbox payload get <secret_name> \
     --key <secret_key> \
     > <file_name>
   

   Where:

   • <secret_name>: Name of the secret with the authorized keys, e.g., secret-loadtest.
   • <secret_key>: Non-secret ID of the secret with the authorized keys, e.g., key-loadtest.
   • <file_name>: Name of the file the authorized keys are saved to, e.g., secret-key.json.

   Warning

   In Windows, use CMD to run the above command. If you use PowerShell, the file will have incorrect encoding. Make sure the encoding of the downloaded file is UTF-8.

3. Create a configuration file for the external agent, e.g., config.yaml, and copy the following parameters into it:

   client_workdir: '/var/lib/tank_agent/client'
   tankapi_host: localhost
   tankapi_port: 8083
   load_testing_host: 'loadtesting.api.cloud.yandex.net'
   load_testing_port: '443'
   logging_host: 'ingester.logging.yandexcloud.net'
   logging_port: '443'
   object_storage_url: 'https://storage.yandexcloud.net'
   storage_file: '/tmp/yandex-tank/storage.data'
   iam_token_service_url: 'iam.api.cloud.yandex.net:443'
   agent_id_file: '/run/agentid'
   private_key: '/run/sa_key.json'
   
   agent_name: <external_agent_name>
   folder_id: <folder_ID>
   

   Where:

   • agent_name: External agent name, e.g., external-agent.
   • folder_id: ID of the folder where you are going to connect the external.

Run the external agentRun the external agent

1. To run a Docker container with the external agent, run the following command in the terminal:

   docker run \
     -it \
     --mount type=bind,source=<path_to_file_with_authorized_keys>,target=/run/sa_key.json \
     --mount type=bind,source=<path_to_configuration_file>,target=/run/config.yaml \
     --env LOADTESTING_AGENT_CONFIG=/run/config.yaml \
     cr.yandex/yc/ya-lt-agent:latest
   

   Where:

   • <path_to_file_with_authorized_keys>: Absolute path to the file with the authorized keys, e.g., /home/user/secret-key.json.
   • <path_to_configuration_file>: Absolute path to the configuration file, e.g., /home/user/config.yaml.

   You can also specify the external agent configuration using the environment variables for different Docker containers.

   Example of running an external agent with environment variables

   docker run \
     -it \
     --mount type=bind,source=<path_to_file_with_authorized_keys_in_host_OS>,target=/run/sa_key.json \
     --env LOADTESTING_AGENT_CONFIG=<path_to_configuration_file_in_container> \
     --env LOADTESTING_AGENT_NAME='<external_agent_name>' \
     --env LOADTESTING_FOLDER_ID='<folder_ID>' \
     --env LOADTESTING_SA_KEY_FILE=<path_to_file_with_authorized_keys_in_container> \
     cr.yandex/yc/ya-lt-agent:latest
   

   Where:

   • LOADTESTING_AGENT_CONFIG: Required parameter that indicates the path to the configuration file of the external agent in the container.
   • LOADTESTING_AGENT_NAME: External agent name.
   • LOADTESTING_FOLDER_ID: Folder ID.
   • LOADTESTING_SA_KEY_FILE: Path to the file with the authorized keys in the container.

   You can use the following environment variables instead of the authorized key file:

   • LOADTESTING_SA_ID: Service account ID.
   • LOADTESTING_SA_KEY_ID: ID of the service account authorized key.
   • LOADTESTING_SA_KEY_PAYLOAD: Value of the service account private authorized key.

   External agents are authorized using a JWT.

   Each time the Docker container is run, the external agent is assigned a new ID in Load Testing. You can keep the same ID between container runs, for example, to link testing results to a specific agent. To do this, use a Docker volume to store a file with the external agent ID (the agent_id_file parameter in the agent configuration file). The volume data is stored independently of the Docker container: if you stop and delete the container, both the volume and the container data will remain intact.

   Example of running an external agent with a constant ID

   Create a Docker volume, e.g., external_agent_1_volume:

   docker volume create external_agent_1_volume
   

   Run the external agent with a mounted volume:

   docker run \
     -it \
     --mount source=external_agent_1_volume,target=/run \
     --mount type=bind,source=<path_to_file_with_authorized_keys>,target=/run/sa_key.json \
     --mount type=bind,source=<path_to_configuration_file>,target=/run/config.yaml \
     --env LOADTESTING_AGENT_CONFIG=/run/config.yaml \
     cr.yandex/yc/ya-lt-agent:latest
   

2. Check that the external agent is available in Load Testing:

   Management console

   1. In the management console, select Load Testing.

   2. In the left-hand panel, go to the Operations tab.

   3. Make sure the Register an agent operation completed successfully.

   4. In the left-hand panel, go to the Agents tab.

   5. Make sure the external agent, e.g., external-agent, has the Ready for test status.

Create a testCreate a test

Run load testing. In the Agents field, select an external agent, e.g., external-agent.

View the testing resultsView the testing results

How to delete the resources you createdHow to delete the resources you created

To delete the external agent from Load Testing:

See alsoSee also

• Load testing using multiple agents