Kubernetes locations configuration

    Private Locations on your Kubernetes cluster.

    Instance specifications

    We recommend that you use for your own load generators pods with at least 4 cores. See CPU requests and limits configuration below.

    You might want to tune the Xmx JVM options to half of the memory request. See jvm-options configuration below. If you don’t, the JVM will use a max heap size of 1/4th of the physical memory.

    Also, if you’re deploying your load generators in the same cluster as the application under test, we recommend that you isolate the load generators on their dedicated nodes, using taints and tolerations. See tolerations configuration below.

    Permissions

    To use Kubernetes private locations, the control plane must have access to your Kubernetes cluster.

    If the control plane is launched from outside the cluster, you have to give access to a valid Kubernetes file. See Organizing Cluster Access Using kubeconfig Files. The .kube folder can be mounted in /app, and absolute path must be set in a KUBECONFIG environment variable (e.g. KUBECONFIG=/app/.kube/config)

    If the control plane is launched from inside the cluster, please refer to our Kubernetes Control plane deployment documentation

    System requirements

    Kubernetes private locations image 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
  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 Kubernetes"
      # Private location type
      type = "kubernetes"
      # Namespace (optional, default based on kubernetes configuration)
      namespace = "gatling"
      # Engine (optional, default classic)
      engine = "classic" # Possible values: classic or javascript
      # Certified image configuration
      # They are hosted on Docker Hub, and available for the linux/amd64 and linux/arm64 platforms
      image {
        type = certified
        java = latest # See engine section
      }
      # Custom image configuration
      # You can build your own images from https://github.com/gatling/frontline-injector-docker-image
      # image {
      #   type = custom
      #   image = "gatlingcorp/classic-openjdk:latest"
      # }
      # Job definition (optional)
      # See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#job-v1-batch for properties
      job = { include "job.json" }
      # 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.
      # jvm-options = ["-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 21 or latest
    javascript latest

    Example JSON Job Definition

    When configuring the control plane, you may include a job definition that adheres to the Kubernetes Job API schema. This job definition manages the deployment and execution of Gatling simulations on Kubernetes.

    Several aspects of this job schema are enforced by the control plane:

    • spec.parallelism: Automatically set to match the number of instances configured for the simulation at the specified location, ensuring the workload is distributed as intended.
    • spec.backoffLimit: Set to 0 to disable any retries, ensuring that failed simulations do not automatically restart.
    • spec.template.spec.restartPolicy: Enforced as Never to prevent the creation of unintended instances.
    • spec.template.spec.containers: The job is restricted to a single container in the pod specification, which will run the Gatling simulation.
    • spec.template.spec.containers[0].image: The container image is determined by your configuration (certified or custom) and cannot be set within the job definition itself.
    • spec.template.spec.containers[0].command: Reserved for initiating the Gatling script and should not be modified within the job definition.

    Here is an example of a basic JSON job definition:

    {
  "apiVersion": "batch/v1",
  "kind": "Job",
  "metadata": {
    "generateName": "gatling-job-",
    "namespace": "gatling"
  },
  "spec": {
    "template": {
      "metadata": {
        "annotations": {
          "example-key": "example-value"
        },
        "labels": {
          "example-key": "example-value"
        },
        "namespace": "gatling"
      },
      "spec": {
        "containers": [
          {
            "env": [
              {
                "name": "env-key",
                "value": "env-value"
              }
            ],
            "name": "gatling-container",
            "resources": {
              "limits": {
                "memory": "512Mi",
                "cpu": "4"
              },
              "requests": {
                "memory": "512Mi",
                "cpu": "4"
              }
            }
          }
        ],
        "securityContext": {
          "sysctls": []
        }
      }
    },
    "ttlSecondsAfterFinished": 60
  }
}

    Key Elements of the Example Job Definition

    • apiVersion: Specifies the API version for the Job resource, which is batch/v1 in this case.
    • kind: Indicates that this is a Job resource.
    • metadata.generateName: A prefix for the name of the job. Kubernetes will append a unique suffix to ensure the job name is unique.
    • metadata.namespace: The namespace in which the job will be created. Ensure this matches your configuration.
    • spec.template.metadata: Contains metadata such as annotations and labels for the job template.
    • spec.template.spec.containers: The container definition, including environment variables and resource limits.
    • resources.limits and resources.requests: Specify the resources (memory and CPU) the container can use and the minimum resources it is guaranteed.
    • securityContext.sysctls: Configures kernel parameters for the container, such as enabling TCP connection time wait reuse.
    • ttlSecondsAfterFinished: The job’s time-to-live after completion. After this time, the job will be automatically deleted by Kubernetes.

    Deploy resources using Helm

    Gatling provides Helm chart to set up Kubernetes resources for Private Locations, visit our dedicated GitHub repository

    Edit this page on GitHub

    ← Kubernetes locations installation
    Dedicated locations installation →