Design considerations

This section describes important design decisions and configuration options for the Distributed Load Testing on AWS solution, including supported applications, test types, scheduling options, and deployment considerations.

Supported applications

This solution supports testing cloud-based applications and on-premises applications as long as you have network connectivity from your AWS account to your application. The solution supports APIs that use HTTP or HTTPS protocols.

Test types

Distributed Load Testing on AWS supports multiple test types: simple HTTP endpoint tests, JMeter, K6, and Locust.

Simple HTTP endpoint tests

The web console provides an HTTP Endpoint Configuration interface that allows you to test any HTTP or HTTPS endpoint without writing custom scripts. You define the endpoint URL, select the HTTP method (GET, POST, PUT, DELETE, etc.) from a dropdown menu, and optionally add custom request headers and body payloads. This configuration enables you to test APIs with custom authorization tokens, content types, or any other HTTP headers and request bodies required by your application.

When you configure an HTTP endpoint, the solution converts your configuration into a test plan that is executed by the bundled Apache JMeter binary through the Taurus framework. Simple HTTP Endpoint tests do not accept a test archive, so they cannot override the bundled JMeter binary or plugins. If you need to run HTTP endpoint tests with a patched JMeter, use the JMeter test type instead. For security considerations, refer to Apache JMeter.

JMeter tests

When creating a test scenario using the web console, you can upload a JMeter test script. The solution uploads the script to the scenarios S3 bucket. When Amazon ECS tasks run, they download the JMeter script from S3 and execute the test.

If you have JMeter input files, you can zip the input files together with the JMeter script. You can choose the zip file when you create a test scenario.

If you would like to include plugins, any .jar files that are included in a /plugins subdirectory in the bundled zip file will be copied to the JMeter extensions directory and be available for load testing.

If you include JMeter plugins, the .jar files must be bundled in a subdirectory named /plugins within the root of the zip file. Relative to the root of the zip file, the path to the jar files must be ./plugins/BUNDLED_PLUGIN.jar.

For more information about how to use JMeter scripts, refer to JMeter User’s Manual.

K6 tests

The solution supports K6 framework-based testing. You can upload the K6 test file along with any necessary input files in an archive file. The web console displays a license acknowledgment message when you create a new K6 test; for license and security details, refer to Grafana K6.

Locust tests

The solution supports Locust framework-based testing. You can upload the Locust test file along with any necessary input files in an archive file.

Scheduling tests

The solution provides three execution timing options for running load tests:

When you select Run Once, you specify the run time in 24-hour format and the run date when the load test should start running.

When you select Run on a Schedule, you can either manually enter a cron expression or select from common cron patterns (such as every hour, daily at a specific time, weekdays, or monthly). The cron expression uses a fine-grained schedule format with fields for minutes, hours, day of month, month, day of week, and year. You must also specify an expiry date, which defines when the scheduled test should stop running. For more information on how scheduling works, refer to the Test scheduling workflow section of this guide.

Concurrent tests

This solution creates an Amazon CloudWatch dashboard for each test that displays the combined output of all tasks running in the Amazon ECS cluster in real time. The CloudWatch dashboard shows average response time, number of concurrent users, number of successful requests, and number of failed requests. The solution aggregates each metric by the second and updates the dashboard every minute.

User management

During initial configuration, you provide a username and email address that Amazon Cognito uses to grant you access to the solution’s web console. The console does not provide user administration. To add additional users, you must use the Amazon Cognito console. For more information, refer to Managing Users in User Pools in the Amazon Cognito Developer Guide.

For migrating existing users to Amazon Cognito user pools, refer to the AWS blog Approaches for migrating users to Amazon Cognito user pools.

Identity provider federation

The solution’s Amazon Cognito user pool supports federation with external identity providers (IdPs) using SAML 2.0 or OpenID Connect (OIDC) protocols. Federation allows users to sign in to the web console using their existing corporate or organizational credentials instead of Cognito-native credentials. Federated users receive the same access permissions as users created directly in the Cognito user pool.

The solution already deploys the Cognito user pool, domain, app client, and hosted UI. To enable federation, you only need to register your identity provider and enable it on the existing app client.

If you deploy the optional MCP Server integration, federated users can also access the MCP Server using the same Cognito user pool credentials.

Prerequisites

Before configuring federation, you need the following:

Step 1: Configure your identity provider

Configure your external identity provider with the following values so that it can communicate with the solution’s Cognito user pool.

For SAML identity providers:

For OIDC identity providers:

For details on what your IdP needs, refer to Adding SAML identity providers to a user pool or Adding OIDC identity providers to a user pool in the Amazon Cognito Developer Guide.

Step 2: Register the identity provider in Cognito

Add your external identity provider to the solution’s existing Cognito user pool using the Amazon Cognito console.

For step-by-step instructions, refer to Adding user pool sign-in through a third party in the Amazon Cognito Developer Guide.

Step 3: Configure attribute mappings

Configure attribute mappings between your identity provider’s claims and the Cognito user pool attributes. At a minimum, map the user’s email claim from the external provider to the Cognito email attribute. Consider also mapping name or nickname if your identity provider supplies them.

For instructions, refer to Specifying identity provider attribute mappings for your user pool in the Amazon Cognito Developer Guide.

Step 4: Enable the identity provider on the app client

In the Amazon Cognito console, find the app client created by the solution and enable your new identity provider under the hosted UI settings.

For instructions, refer to Configuring a user pool app client in the Amazon Cognito Developer Guide.

Disabling or deleting the default Cognito user

After configuring federation, you may want to disable or delete the default user that was created during stack deployment. This is optional — the default user continues to work alongside federated sign-in.

To disable a user, navigate to the solution’s Cognito user pool in the Amazon Cognito console, select the Users tab, choose the user, and select Disable user access. To delete a user, you must first disable them, then choose Delete user. Disabling a user revokes their tokens and prevents sign-in while preserving the account; deleting permanently removes it.

For more details, refer to Managing and searching for user accounts in the Amazon Cognito Developer Guide.

Regional deployment

This solution uses Amazon Cognito which is available in specific AWS Regions only. Therefore, you must deploy this solution in a region where Amazon Cognito is available. For the most current service availability by Region, refer to the AWS Regional Services List.