Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

Private locations allow you to run Gatling Enterprise Edition load tests entirely inside your own network, without exposing any internal endpoints to the public internet or sharing credentials with Gatling. A lightweight Control Plane agent runs on your infrastructure and acts as a bridge between Gatling Enterprise and your load generators—it polls the Gatling Enterprise API for pending runs, provisions the required load generator instances, and streams test metrics back to the platform.
Private locations are only available on Gatling Enterprise paid plans and must be activated for your organization. To request access, contact technical support.

​
Architecture overview

The Control Plane is the only component you operate. It runs as a Docker container and requires outbound HTTPS access to the Gatling Enterprise API. There are no inbound connections required from Gatling to your network. 
Gatling Enterprise API
        ↑ (poll for runs / push metrics)
        |
  [Control Plane container] ← your network
        |
        ↓ (spawn)
  [Load Generator instances/pods]
        |
        ↓ (traffic)
  [Application Under Test]
The Control Plane agent is distributed as a Docker image: gatlingcorp/control-plane. It supports the linux/amd64 and linux/arm64 platforms.

​
Supported providers

Amazon Web Services (AWS)

Spawn EC2 instances as load generators inside your VPC. The Control Plane runs on ECS Fargate.

Microsoft Azure

Run load generators as Azure Virtual Machines. The Control Plane runs on Azure Container Apps.

Google Cloud Platform (GCP)

Spawn Compute Engine VMs as load generators. The Control Plane runs on Cloud Run or a VM.

Kubernetes

Run load generators as Kubernetes batch jobs. The Control Plane runs as a Deployment with RBAC.

Dedicated Machines

Run load generators on any Docker-capable host, on-premises or in any cloud.

​
Setting up a Control Plane

1

Create a Control Plane in the UI

Navigate to Private Locations in the Gatling Enterprise navigation bar (visible only when the feature is activated on your organization).
Only organization system administrators can manage private locations.
Click Create control plane and provide a unique identifier. The identifier must be lowercase, may contain underscores, and has a maximum length of 30 characters.
2

Copy the Control Plane token

After creation, a token is displayed. Copy it immediately—it will not be shown again. Store it securely in your secrets manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or Kubernetes Secrets).
3

Write the configuration file

The Control Plane reads a HOCON configuration file mounted at /app/conf/control-plane.conf. The minimum required configuration is:
control-plane {
  # Your control plane token
  token = ${?CONTROL_PLANE_TOKEN}

  # Optional description
  description = "My private load testing location"

  # Define one or more private locations
  locations = [
    {
      # ID must start with prl_, only lowercase letters, digits, underscores
      id = "prl_my_location"
      description = "My private location"
      # Provider-specific configuration goes here
      # ...
    }
  ]
}
For provider-specific configuration keys, see the documentation for your chosen provider (AWS, Azure, GCP, Kubernetes, or Dedicated).
4

Run the Control Plane container

Launch the Docker container with the configuration file mounted:
docker run \
  -e CONTROL_PLANE_TOKEN="cpt_example_..." \
  -v /path/to/control-plane.conf:/app/conf/control-plane.conf \
  gatlingcorp/control-plane
For production deployments, use the provider-specific installation guides (ECS, Container Apps, GKE, Helm, etc.).
5

Verify the Control Plane status

Return to Private Locations in the Gatling Enterprise UI. Within a few seconds, the Control Plane status should change to Up. Click the eye icon for detailed status information.
StatusMeaning
UninitializedThe Control Plane has never contacted the API
UpThe Control Plane is healthy and polling for runs
DownThe Control Plane was Up but has not polled recently

​
Configuration reference

​
Default system properties block

Use the default block to apply system properties to all locations managed by a Control Plane: 
control-plane {
  token = ${?CONTROL_PLANE_TOKEN}

  default {
    locations {
      system-properties = {
        "sysprop-example" = "default-value"
      }
    }
  }

  locations = [ ... ]
}
Local location properties override the defaults. Additional local properties are merged on top of defaults.
The default block can only be used to set system properties. Other settings (such as instance type) must be configured per location.

​
Control Plane server (private packages)

When private packages are enabled, the Control Plane exposes a server on port 8080 by default. The /info endpoint provides a health check.
ParameterDefaultDescription
server.port8080Listening port
server.bind-address0.0.0.0Network interface to bind
server.certificate—Optional PKCS#12 certificate for TLS without a reverse proxy

​
Using private locations in a test

When configuring a test in the Tests view, click Private in the locations step to select from your available private locations.
Private and managed locations cannot be mixed within the same test. A test must use exclusively one or the other.

Infrastructure as Code

Automate Control Plane and private location deployment with Terraform modules and Helm charts.

Dedicated IPs

Assign fixed IP addresses to your load generators for firewall whitelisting.

Local Install

Run Gatling open-source locally to write and validate simulations before deploying to Enterprise.

Build docs developers (and LLMs) love

Get started for freeTalk to us