Configuration As Code

Introduction

Helps you quickly create and maintain your Simulations on Gatling Enterprise Cloud directly from your project configuration through a simple command of your Gatling Build Plugin.

Pre-requisites

On Gatling Enterprise Cloud:

Create an account
Create or join an organization
Create an API Token with Configure permission

For a better understanding, see references for underlying concepts:

Usage

To deploy your Gatling project on Gatling Enterprise Cloud, follow these steps:

Configure the Gatling Enterprise Cloud API Token within your Gatling Build Plugin:
Use the following command for deployment:
- Maven: mvn gatling:enterpriseDeploy
- Gradle: gradle gatlingEnterpriseDeploy
- sbt: sbt Gatling/enterpriseDeploy

Demo projects are available with a fully configured Package Descriptor example for each Build Plugin: Maven, Gradle, and sbt

Default Behavior

When no additional configuration is provided, the deployment process follows these inferred settings:

Creation of a package within the organization:
1. The package is named after the artifact ID of your project.
2. The team assigned to the package is either:
  1. The only team specified in the API Token.
  2. The only team in the organization if the API Token has a global role.
Creation of Simulations within the package:
1. Each Simulation is named after its simulation class.
2. The team assigned to the simulation is inherited from the package.
3. Locations are defaulted by Gatling Enterprise Cloud.

During subsequent deployments without additional configuration, inferred values will be sourced from existing simulations on Gatling Enterprise Cloud based on their names.

This means that if the simulation name remains unchanged but other properties have been modified in the Cloud UI, those modifications will remain.

Package Descriptor

You can use a package descriptor file to specify the deployment configuration and enhance control over the deployment process.

Let’s proceed step by step to create a package descriptor configuration and understand the process involved, from a minimal configuration to a fully qualified one.

Create configuration file

Add a new directory at the root of your project: .gatling and create a new file .gatling/package.conf. This file will be in HOCON format.

.
├── .gatling/
│   └── package.conf
└── src/
    ├── main/
    └── test/

No configuration file or an empty one is valid and will have the Default Behavior described above.

Configure the name of the package.

gatling.enterprise.package {
  name = "My package name"
}

See Consistent deployment to change the name without deploying a new package.

Assign the package to a team

As described in Default Behavior, the team is inferred from the API Token when not specified.

You can configure the Team, however, the API Token must have the Configure permission for the specified team.

gatling.enterprise.package {
  name = "My package name"
  team = "My team name" # or ID with team = "00000000-0000-0000-0000-000000000000"
}

Deploy only selected simulations

To deploy only some of the simulations in your Gatling project, you can configure simulations for a given Package.

Only configured simulation classes will be deployed to Gatling Enterprise Cloud.

For example, a project with multiple simulations com.example.SimulationA and io.gatling.SimulationB , where you only want to deploy com.example.SimulationA.

gatling.enterprise.package {
  name = "My package name"
  team = "My team name"
  simulations = [
    {
      simulation = "com.example.SimulationA"
    }
  ]
}

simulation is the only mandatory field of simulations when specified, other fields (see below) can still be inferred by Default Behavior.

Consistent deployment with ID

Packages and simulations are deployed according to their names. Therefore, any updates of the names made from the Web UI will result in a new deployment.

To avoid this, you can set the package and simulation IDs in the configuration.

These IDs will be logged during your first deployment, such as after your initial Usage.

Package 'My package name' (id='00000000-0000-0000-0000-000000000000') deployed
Simulation 'com.example.SimulationA' (id='00000000-0000-0000-0000-000000000001') deployed

Then, you can freely update names without having new packages or simulations created:

gatling.enterprise.package {
  id = "00000000-0000-0000-0000-000000000000"
  name = "My new package name"
  team = "My team name"
  simulations = [
    {
      id = "00000000-0000-0000-0000-000000000001"
      name = "My new simulation name"
      simulation = "com.example.SimulationA"
    }
  ]
}

Simulation configurations

As we mention in the Default Behavior section, a Simulation includes more than just a simulation.

Each property of a Simulation, can be configured individually or left to default settings, allowing for customization either through configuration or via the Web UI.

gatling.enterprise.package {
  # id = "00000000-0000-0000-0000-000000000000"
  name = "My package name"
  team = "My team name"
  simulations = [
    {
      # id = "00000000-0000-0000-0000-000000000001"
      name = "My simulation name"
      simulation = "com.example.SimulationA"
      locations = [
        {
          name: "Europe - Paris",
          size: 2,
          weight: 30
        },
        {
          name: "AP Pacific - Mumbai",
          size: 2,
          weight: 70
        }
      ]
      parameters {
        ignoreDefaults = false
        systemProperties {
          "com.example.prop.1" = "system prop 1"
          "com.example.prop.2" = "system prop 2"
        }
        environmentVariables {
          SIMULATION_ENV_VAR_1 = "environment 1"
          SIMULATION_ENV_VAR_2 = "environment 2"
        }
      }
      timeWindow {
        rampUp = 10
        rampDown = 10
      }
      stopCriteria = [
        {
          type = "meanCpu",
          timeframeInSeconds = 10,
          threshold = {
            maxPercentage = 90
          }
        },
        {
          type = "globalResponseTime",
          timeframeInSeconds = 10,
          threshold = {
            maxMilliseconds = 90,
            percentile = 50
          }
        },
        {
          type = "globalErrorRatio",
          timeframeInSeconds = 10,
          threshold = {
            maxPercentage = 90
          }
        }
      ]
    }
  ]
}

Properties:

locations (optional) :

name : Location name is one of the following:
- AP - Hong kong
- AP - Tokyo
- AP Pacific - Mumbai
- AP SouthEast - Sydney
- Europe - Paris
- Europe - Dublin
- US East - N. Virginia
- US West - N. California
- US West - Oregon
- An existing Private Location ID
size (optional) : The number of load generators to deploy for the location (default: 1)
weight (optional) : The % of virtual users handled by the load generators of the location (default: even weight)

Locations weights sum must be equal to 100

parameters (optional) :

ignoreDefaults (optional) : Ignore or not Default Load Generator Parameters (default: false, or existing)
systemProperties (optional) : [Java system properties]({{ < ref “/reference/execute/cloud/user/simulations#step-3-load-generator-parameters” >}}) for the simulation (default: empty, or existing)
environmentVariables (optional) : Environment variables for the simulation (default: empty, or existing)

System properties prefix with sensitive. will not be displayed on dashboard. Environment variables prefix with SENSITIVE_ will not be displayed on dashboard.

timeWindow (optional) :

rampUp (optional) : number of second at the beginning of the test to ignore (default: 0, or existing)
rampDown (optional) : number of second at the end of the test to ignore (default: 0, or existing)

stopCriteria (optional)

type: meanCpu, globalResponseTime or globalErrorRatio
timeframeInSeconds: the timeframe during which the threshold must be reached to stop the simulation.
threshold, if globalResponseTime:
- percentile: defines the percentile from which you want to check the response time.
- maxMilliseconds: the max response time, in milliseconds. Run stops if exceeded.
threshold, if meanCpu or globalErrorRation
- maxPercentage: percentage of mean Load Generators CPU usage or requests error rate at which you want the test to stop.

Common settings for simulations

If you need to set up multiple simulations with similar settings, doing so individually can become time-consuming.

To simplify the process, a default section is available for simulation.

Consequently, both example simulations com.example.SimulationA and com.example.SimulationB can share the same basic settings, saving you time and effort.

gatling.enterprise.package {
  # id = "00000000-0000-0000-0000-000000000000"
  name = "My package name"
  team = "My team name" # or ID with team = "00000000-0000-0000-0000-000000000000"
  default {
    simulation {
      locations = [
        {
          name: "Europe - Paris",
          size: 1
        }
      ]
      parameters {
        ignoreDefaults = false
        systemProperties {
          "com.example.prop.1" = "default value for system prop 1"
          "com.example.prop.2" = "default value for system prop 2"
        }
        environmentVariables {
          MY_SIMULATION_ENV_VAR_1 = "default value from environment 1"
          MY_SIMULATION_ENV_VAR_2 = "default value from environment 2"
        }
      }
      timeWindow {
        rampUp = 10
        rampDown = 10
      }
      stopCriteria = [
        {
          type = "meanCpu",
          timeframeInSeconds = 10,
          threshold = {
            maxPercentage = 90
          }
        },
        {
          type = "globalResponseTime",
          timeframeInSeconds = 10,
          threshold = {
            maxMilliseconds = 90,
            percentile = 50
          }
        },
        {
          type = "globalErrorRatio",
          timeframeInSeconds = 10,
          threshold = {
            maxPercentage = 90
          }
        }
      ]
    }
  }
  simulations = [
    {
      # id = "00000000-0000-0000-0000-000000000001"
      simulation = "com.example.SimulationA"
    },
    {
      # id = "00000000-0000-0000-0000-000000000002"
      simulation = "com.example.SimulationB"
      parameters {
        ignoreDefaults = true
        systemProperties {
          "com.example.prop.1" = "override value from system prop 1"
        }
        environmentVariables {
          MY_SIMULATION_ENV_VAR_1 = "override value from environment 1"
        }
      }
      timeWindow {
        rampDown = 20
      }
      stopCriteria = [
        {
          type = "meanCpu",
          timeframeInSeconds = 15,
          threshold = {
            maxPercentage = 95
          }
        }
      ]
    }
  ]
}

ignoreDefaults refer to Default Load Generator Parameters, not to the default configuration block of package.conf file.

For com.example.SimulationB in the example, its properties are combined with the default settings. However, priority is given to the settings specific to SimulationB

{
  # id = "00000000-0000-0000-0000-000000000002"
  simulation = "com.example.SimulationB"
  parameters {
    ignoreDefaults = true
    systemProperties {
      "com.example.prop.1" = "override value for system prop 1"
      "com.example.prop.2" = "default value for system prop 2"
    }
    environmentVariables {
      MY_SIMULATION_ENV_VAR_1 = "override value from environment 1"
      MY_SIMULATION_ENV_VAR_2 = "default value from environment 2"
    }
  }
  timeWindow {
    rampUp = 10
    rampDown = 20
  }
  stopCriteria = [
    {
      type = "meanCpu",
      timeframeInSeconds = 15,
      threshold = {
        maxPercentage = 95
      }
    }
  ]
}

Edit this page on GitHub

Configuration As Code

Introduction

Pre-requisites#

Usage#

Default Behavior#

Package Descriptor#

Create configuration file#

Configure the name of the package.#

Assign the package to a team#

Deploy only selected simulations#

Consistent deployment with ID#

Simulation configurations#

Common settings for simulations#