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:

For a better understanding, see references for underlying concepts:

Usage

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

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

Default Behavior

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

  1. 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.
  2. 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.

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"
}

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 = [
    {
      classname = "com.example.SimulationA"
    }
  ]
}

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

Consistent deployment with ID

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"
      classname = "com.example.SimulationA"
    }
  ]
}

Simulation configurations

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

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"
      classname = "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
      }
    }
  ]
}

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)

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)

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)

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
      }
    }
  }
  simulations = [
    {
      # id = "00000000-0000-0000-0000-000000000001"
      classname = "com.example.SimulationA"
    },
    {
      # id = "00000000-0000-0000-0000-000000000002"
      classname = "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
      }
    }
  ]
}

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"
  classname = "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
  }
}

Edit this page on GitHub