AWS locations configuration

Private Locations on your AWS account.

Instance specifications

The follow recommendations help you to select the best instances and tune them for maximum performance.

  • We recommend instances with at least 4 cores for your load generators.
  • As Gatling load tests tend to be CPU bound, we recommend using instances from the “Compute Optimized” family.
  • In our experience, it seems that Intel CPUs perform better than AMD and ARM Graviton ones when it comes to TLS. As a result, we recommend using c7i.xlarge instances or larger.
  • You might want to tune the Xmx JVM options to half of the physical memory. See jvm-options configuration below. If you don’t, the JVM will use a max heap size of 1/4th of the physical memory.

Permissions

AWS private locations requires the control plane to have access to AWS credentials from the default credential provider chain.

See the AWS documentation for the Default Credential Provider Chain.

System requirements

AWS EC2 private locations rely on some dependencies.

So when using a custom image, make sure following are available:

Control plane configuration file

control-plane {
  # Control plane token
  token = "cpt_example_c7oze5djp3u14a5xqjanh..."
  # Control plane token with an environment variable
  token = ${?CONTROL_PLANE_TOKEN}
  # Control plane description (optional)
  description = "my control plane description"
  # Locations configurations
  # Server configuration (optional)
  # server {
    # port = 8080 # (optional, default: 8080)
    # bind-address = "0.0.0.0" # (optional, default: 0.0.0.0)

    # # PKCS#12 certificate (optional)
    # certificate {
    # path = "/path/to/certificate.p12"
    #  password = ${CERTIFICATE_PASSWORD} # (optional)
    # }
  # }
  locations = [
    {
      # Private location ID, must be prefixed by prl_, only consist of numbers 0-9, 
      # lowercase letters a-z, and underscores, with a max length of 30 characters
      id = "prl_private_location_example"
      # Private location description (optional)
      description = "Private Location on AWS"
      # Private location type
      type = "aws"
      # Configuration specific to AWS type configuration
      region = "eu-west-1"
      # Engine (optional, default classic)
      engine = "classic" # Possible values: classic or javascript
      # Certified AMI configuration
      ami {
        type = "certified"
        # java = latest # See engine section
      }
      # Custom AMI configuration (alternative to certified AMI)
      # ami = {
      #   type = custom
      #   id = "ami-00000000000000000"
      # }
      # Absolute path of the directory where executable binaries will be stored
      # executable-dir = "/tmp"
      # Security groups
      security-groups = ["sg-mysecuritygroup"]
      # Instance type
      instance-type = "c7i.xlarge"
      # Spot instances (optional, default: false)
      # Set to true to use Spot Instances instead of On-Demand Instances, or to "preferred" to prioritize Spot Instances and provision any remaining instances as On-Demand if Spot capacity is unavailable.
      # spot = true # Possible values: true, false or "preferred"
      # Subnets
      subnets = ["subnet-a", "subnet-b"]
      # Automatically associate a public IPv4 (optional, default true)
      # auto-associate-public-ipv4 = true
      # Elastic IP addresses (optional, not compatible with auto-associate-public-ipv4)
      # You will only be able to deploy a number of load generators up to the number of Elastic IP addresses you have configured.
      # elastic-ips = ["203.0.113.3", "203.0.113.4"]
      # Profile name (optional)
      # profile-name = ""
      # IAM Instance profile (optional)
      # iam-instance-profile = ""
      # IAM Instance profile per team (optional), falls back to iam-instance-profile
      # when the run's team has no entry
      # iam-instance-profiles-by-team-id {
      #   "team_00000000000000000000000000" = ""
      # }
      # Custom tags (optional)
      tags {
       # ExampleKey = "ExampleValue"
      }
      # Custom tags for each AWS resource type (optional)
      # Only resources types mentioned further are managed
      tags-for {
        instance {
          # ExampleKey = "ExampleValue"
        }
        volume {
          # ExampleKey = "ExampleValue"
        }
        network-interface {
          # ExampleKey = "ExampleValue"
        }
      }
      
      # Java configuration (following configuration properties are optional)
      # System properties (optional)
      system-properties {
        # ExampleKey = "ExampleValue"
      }
      # Overwrite JAVA_HOME definition (optional)
      # java-home = "/usr/lib/jvm/zulu"
      # JVM Options (optional)
      # Default ones, that can be overridden with precedence:
      # [
      #   "-XX:MaxInlineLevel=20", 
      #   "-XX:MaxTrivialSize=12", 
      #   "-XX:+IgnoreUnrecognizedVMOptions", 
      #   "--add-opens=java.base/java.nio=ALL-UNNAMED", 
      #   "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED"
      # ]
      # Based on your instance configuration, you may want to update Xmx and Xms values.
      # If your load generators are running on Java 24 or newer,
      # we also recommend enforcing the new ZGC garbage collector.
      # jvm-options = ["-XX:+UseZGC", "-Xmx4G", "-Xms512M"]
    }
  ]
}

Engine

The engine specified for a location determines the compatible package formats (JavaScript or JVM) for Gatling packages.

Each engine (classic or javascript) supports specific Java versions, where latest is defaulted.

The table below outlines the supported Java versions for certified Gatling images:

Engine Supported Java Versions
classic 25 or latest
javascript latest

Assign an IAM instance profile per team

Use iam-instance-profile to attach a single IAM instance profile to every load generator started by this location.

To assign a different IAM instance profile to each team instead of sharing one profile across the whole organization, use iam-instance-profiles-by-team-id. Find a team’s ID on the Teams page:

control-plane {
  locations = [
    {
      # ...
      iam-instance-profile = "<default-profile>" # (optional)
      iam-instance-profiles-by-team-id {
        "team_00000000000000000000000000" = "<team-specific-profile>"
      }
    }
  ]
}

For a given run, the Control Plane resolves the IAM instance profile in this order:

  1. the profile mapped to the run’s team ID in iam-instance-profiles-by-team-id, if any
  2. otherwise, the iam-instance-profile default, if set
  3. otherwise, no IAM instance profile is attached to the instance

Review the tags Gatling applies automatically

In addition to tags and tags-for, the Control Plane always applies a set of reserved tags, prefixed with Gatling:, to the AWS resources it provisions. You can’t override these tags.

Tag Description
Gatling:RunId ID of the run
Gatling:LocationId ID of the private location
Gatling:ControlPlaneVersion Version of the Control Plane that provisioned the resource
Gatling:TestName Name of the test
Gatling:TeamId ID of the team that triggered the run
Gatling:TeamName Name of the team that triggered the run
Gatling:TestId ID of the test

The same reserved tags are applied to instances provisioned by Gatling Enterprise Cloud’s Managed AWS locations.

Edit this page on GitHub