Categories: ADMIN GUIDE CLOUD

Chart configuration

This page provides practical configuration examples for common Step Helm chart deployment scenarios. For a complete reference of all available Helm values and their detailed descriptions, please refer to the Helm Values documentation.

Additional Resources:

Database configuration

Step supports two database backends: MongoDB (default) and PostgreSQL. You must choose one - they cannot be used simultaneously. You will find in the below sub-sections explanations relative to each database as well as some Helm values configuration samples.

MongoDB Configuration (Default)

MongoDB is enabled by default in the Step Helm chart : it runs as a standalone instance.

# MongoDB configuration (default)
mongodb:
  enabled: true
  replicaCount: 1
  fullnameOverride: "mongodb"
  architecture: "standalone"
  
  # Graceful shutdown hook - waits for external operations to complete before shutdown
  # This prevents data corruption by allowing the controller to release its connections
  # The complete preStop hook script is available in the default step.values.yaml file
  # See: https://step.dev/knowledgebase/29/setup/installation/kubernetes/helmvalues/
  lifecycleHooks:
    preStop:
      # See step.values.yaml for the complete preStop hook implementation
  
  # Allow sufficient time for graceful shutdown
  terminationGracePeriodSeconds: 180
  
  image:
    registry: docker.io
    repository: bitnamilegacy/mongodb
    tag: 5.0.24-debian-11-r20
  auth:
    enabled: false
  persistence:
    enabled: true
    storageClass: "default"
    size: 30Gi
  resources:
    requests:
      cpu: "500m"
      memory: "2000Mi"
    limits:
      cpu: "2000m"
      memory: "2000Mi"

# Ensure PostgreSQL is disabled when using MongoDB
postgresql:
  enabled: false
postgresqlha:
  enabled: false

PostgreSQL Standalone Configuration

For PostgreSQL standalone configuration, disable MongoDB and enable PostgreSQL:

# PostgreSQL standalone configuration
postgresql:
  enabled: true
  image:
    registry: docker.io
    repository: bitnamilegacy/postgresql
    tag: 15.3.0-debian-11-r7
  global:
    postgresql:
      auth:
        postgresPassword: init
        database: "step"
  fullnameOverride: "postgresql"
  architecture: "standalone"
  primary:
    # Graceful shutdown hook - waits for external active queries to complete before shutdown
    # This prevents data corruption by allowing the controller to release its connections
    # The complete preStop hook script is available in the default step.values.yaml file
    # See: https://step.dev/knowledgebase/29/setup/installation/kubernetes/helmvalues/
    lifecycleHooks:
      preStop:
        # See step.values.yaml for the complete preStop hook implementation
    
    # Allow sufficient time for graceful shutdown
    terminationGracePeriodSeconds: 180
    
    extraEnvVars:
      - name: POSTGRESQL_EXTRA_FLAGS
        value: "-c max_connections=300"
    persistence:
      storageClass: "default"
      size: "30Gi"
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: 2000m
        memory: 2000Mi

# Ensure MongoDB and PostgreSQL HA are disabled
mongodb:
  enabled: false
postgresqlha:
  enabled: false

PostgreSQL High Availability Configuration

For PostgreSQL with high availability (3 replicas + pgpool), use:

# PostgreSQL HA configuration
postgresqlha:
  enabled: true
  fullnameOverride: "postgresqlha"
  
  # Allow sufficient time for graceful shutdown
  terminationGracePeriodSeconds: 180
  
  postgresql:
    maxConnections: 300
    image:
      registry: docker.io
      repository: bitnamilegacy/postgresql-repmgr
      tag: 15.4.0-debian-11-r0
    username: "postgres"
    password: "init"
    database: "step"
    repmgrUsername: "repmgr"
    repmgrPassword: "repmgr"
    repmgrDatabase: "repmgr"
    replicaCount: 3
    
    # Graceful shutdown hook - waits for external active queries to complete before shutdown
    # This prevents data corruption by allowing the controller to release its connections
    # The complete preStop hook script is available in the default step.values.yaml file
    # See: https://step.dev/knowledgebase/29/setup/installation/kubernetes/helmvalues/
    lifecycleHooks:
      preStop:
        # See step.values.yaml for the complete preStop hook implementation
    
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: 2000m
        memory: 2000Mi
  persistence:
    storageClass: "default"
    size: "30Gi"
  pgpool:
    useLoadBalancing: false
    adminPassword: "pgpool"
    reservedConnections: 1
    numInitChildren: 100
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: 2000m
        memory: 2000Mi

# Ensure MongoDB and standalone PostgreSQL are disabled
mongodb:
  enabled: false
postgresql:
  enabled: false

Important Notes:

  • Only enable one database type at a time
  • PostgreSQL configurations include automatic database and table initialization
  • Adjust storage classes and resource allocations according to your cluster requirements
  • Default passwords should be changed in production environments

Ingress definition

The Step Helm chart provides comprehensive Ingress configuration options to expose the Step Controller UI to external traffic. The chart provides flexible configuration for different deployment scenarios.

Basic Ingress Configuration

The simplest ingress configuration to expose Step on a custom domain:

ingress:
  enabled: true
  host: step.your-domain.com
  domain: your-domain.com
  ingressClassName: nginx

Advanced Ingress Configuration

For production deployments with custom annotations, TLS, and additional paths:

ingress:
  enabled: true
  host: step.your-company.com
  domain: your-company.com
  ingressClassName: nginx
  
  # Custom path configuration
  defaultEndpointPath: "/"
  defaultEndpointPathType: "Prefix"
  
  # Nginx-specific annotations for production
  annotations:
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "60"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    nginx.ingress.kubernetes.io/client-body-buffer-size: "50m"
    nginx.ingress.kubernetes.io/proxy-body-size: "300m"
  
  # TLS configuration
  defaultSecretName: "step-tls-secret"

Multiple Host Configuration

Configure multiple hosts and additional paths for complex routing scenarios:

ingress:
  enabled: true
  host: step.your-domain.com
  domain: your-domain.com
  ingressClassName: nginx
  
  # Additional paths on the default host
  hostAdditionalPaths:
    - path: /example
      pathType: Prefix
      backend:
        service:
          name: step-example-service
          port:
            number: 8888
  
  # Additional ingress rules for other hosts
  extraRules:
    - host: step-dev.your-domain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: step-controller
                port:
                  number: 8080
  
  # TLS configuration for multiple hosts
  extraTls:
    - hosts:
        - step.your-domain.com
        - step-dev.your-domain.com
      secretName: step-multi-host-tls

Important Notes:

  • The host parameter should be the fully qualified domain name where Step will be accessible
  • The domain parameter should match your DNS zone
  • Different ingress controllers require specific annotations - adjust according to your setup
  • For production environments, always configure TLS/SSL certificates
  • Large file uploads may require increased proxy body size limits

Controller configuration

The Step Controller is the central component that manages test execution, provides the web UI, and coordinates with agents. The following examples show various Controller configuration scenarios suitable for different deployment requirements.

Basic Controller Configuration

Simple Controller setup with minimal configuration for development or testing environments:

controller:
  enabled: true
  
  # Technology stack
  tech:
    type: java
    version: 21
  
  # Basic resource allocation (standard flavor)
  resources:
    requests:
      cpu: "750m"
      memory: "2500Mi"
    limits:
      cpu: "2000m"
      memory: "2500Mi"
  
  # Lifecycle hooks
  lifecycleHooks:
    preStop:
      exec:
        command: ["/bin/bash", "-c", "pkill --signal SIGTERM -e java"]
  
  # Basic configuration
  config:
    port: 8080
    NON_HEAP_MEMORY_MB: 750
    JAVA_OPTS: ""
    
  # Enable data persistence
  persistence:
    enabled: true
    pvc:
      data:
        mountPath: "/home/controller/data"
        size: "30Gi"
        storageClass:
          name: "default"

Production Controller Configuration

Production-ready Controller setup with security contexts, resource limits, and comprehensive monitoring:

controller:
  enabled: true
  
  # Technology configuration
  tech:
    type: java
    version: 21
  
  # Security configuration
  podSecurityContext:
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
    fsGroupChangePolicy: "OnRootMismatch"
  
  containerSecurityContext:
    runAsNonRoot: true
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL
  
  # Resource allocation for production workloads (performance flavor)
  resources:
    requests:
      cpu: "3500m"
      memory: "10000Mi"
    limits:
      cpu: "3500m"
      memory: "10000Mi"
  
  # Node placement
  nodeSelector:
    workload-type: "step-controller"
  
  tolerations:
    - key: "controller-nodes"
      operator: "Equal"
      value: "true"
      effect: "NoSchedule"
  
  # Termination grace period
  terminationGracePeriodSeconds: 120
  
  # Lifecycle hooks
  lifecycleHooks:
    preStop:
      exec:
        command: ["/bin/bash", "-c", "pkill --signal SIGTERM -e java"]
  
  # Health probes
  probes:
    startupProbe:
      httpGet:
        path: /
        port: gui
      failureThreshold: 60
      periodSeconds: 10
    livenessProbe:
      httpGet:
        path: /
        port: gui
      initialDelaySeconds: 30
      periodSeconds: 30
    readinessProbe:
      httpGet:
        path: /
        port: gui
      initialDelaySeconds: 15
      periodSeconds: 10
  
  # Configuration
  config:
    port: 8080
    NON_HEAP_MEMORY_MB: 6000
    
    # Additional Step properties
    additionalProperties:
      plugins.PrometheusControllerPlugin.enabled: true
      cosmetics.folder: /home/controller/data/cosmetics
      encryption.manager.keypair.folder: /home/controller/data/encryptionmanager
      plugins.EncryptionManagerControllerPlugin.enabled: true
  
  # Comprehensive persistence configuration
  persistence:
    enabled: true
    pvc:
      data:
        mountPath: "/home/controller/data"
        size: "100Gi"
        storageClass:
          name: "fast-ssd"
        accessModes:
          - ReadWriteOnce
      log:
        enabled: true
        mountPath: "/home/controller/log"
        size: "50Gi"
        storageClass:
          name: "standard"

Advanced Controller Configuration

Controller with custom dependencies, volumes, and advanced features:

controller:
  enabled: true
  
  # Technology configuration
  tech:
    type: java
    version: 21
  
  # Custom lifecycle hooks
  lifecycleHooks:
    preStop:
      exec:
        command: ["/bin/bash", "-c", "pkill --signal SIGTERM -e java"]
  
  # Extra init containers for setup tasks
  extraInitContainers:
    - name: sample-container
      image: alpine:latest
      command: ['sh', '-c', 'echo Sample container running']
      resources:
        limits:
          cpu: "100m"
          memory: "128Mi"
        requests:
          cpu: "50m"
          memory: "64Mi"
  
  # Custom secrets and configuration
  extraSecrets:
    stringData:
      custom-config-url: "https://config.your-company.com/step"
    data:
      custom-cert: "LS0tLS1CRUdJTi..." # base64 encoded certificate
  
  # Mount custom volumes
  extraVolumeMounts:
    - name: "custom-config"
      mountPath: "/opt/config"
      readOnly: true
    - name: "custom-certs"
      mountPath: "/opt/certs/custom.crt"
      subPath: custom-cert
    - name: "shared-storage"
      mountPath: "/shared"
  
  extraVolumes:
    - name: "custom-config"
      configMap:
        name: "step-custom-config"
    - name: "custom-certs"
      secret:
        secretName: "step-controller"
    - name: "shared-storage"
      persistentVolumeClaim:
        claimName: "shared-pvc"
  
  # Environment variables
  extraEnvVars:
    - name: "CUSTOM_CONFIG_URL"
      valueFrom:
        secretKeyRef:
          name: "step-controller"
          key: custom-config-url
    - name: "ENVIRONMENT"
      value: "production"
  
  # Configuration with external dependencies
  config:
    port: 8080
    NON_HEAP_MEMORY_MB: 6000
    
    # Install external dependencies (see [Install dependencies section](#install-dependencies-to-your-pods-before-startup))
    FULL_STEP_DP: "https://your-repository.com/jmeter-5.6.2.zip,https://your-repository.com/custom-tools-1.0.0.zip"
    
    JAVA_OPTS: "-Djavax.net.ssl.trustStore=/opt/certs/cacerts -Djavax.net.ssl.trustStorePassword=changeit"
    
    # Custom properties
    additionalProperties:
      plugins.jmeter.home: "/home/controller/jmeter-5.6.2/apache-jmeter-5.6.2/"
      plugins.pdftest.gsexe: "/home/controller/ghostscript/bin/ghostscript"
      plugins.soapui.home: "/home/controller/soapui-5.7.0/SoapUI-5.7.0/"
      custom.property: "custom-value"
    
    # Custom logback configuration
    logbackConfiguration: |
      <configuration scan="true" scanPeriod="60 seconds">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
          <encoder>
            <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
          </encoder>
        </appender>
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
          <file>/home/controller/log/step.log</file>
          <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>/home/controller/log/step.%d{yyyy-MM-dd}.%i.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
          </rollingPolicy>
          <encoder>
            <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
          </encoder>
        </appender>
        <logger name="step" level="debug" />
        <logger name="org.lightcouch" level="error" />
        <root level="info">
          <appender-ref ref="STDOUT" />
          <appender-ref ref="FILE" />
        </root>
      </configuration>      
  
  # Resource allocation (enterprise-grade flavor)
  resources:
    requests:
      cpu: "8000m"
      memory: "12000Mi"
    limits:
      cpu: "8000m"
      memory: "12000Mi"
  
  # Persistence with multiple volumes
  persistence:
    enabled: true
    pvc:
      data:
        mountPath: "/home/controller/data"
        size: "100Gi"
        storageClass:
          name: "fast-ssd"
      log:
        enabled: true
        mountPath: "/home/controller/log"
        size: "20Gi"
        storageClass:
          name: "standard"
  
  # Additional volume claim templates
  extraVolumeClaimTemplates:
    - metadata:
        name: "temp-storage"
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: "50Gi"
        storageClassName: "fast"

Important Notes:

  • These configuration samples are examples only - all URLs, paths, versions, and values should be updated according to your specific requirements and environment
  • Resource allocation: Adjust CPU and memory limits based on your expected workload and cluster capacity
  • Persistence: Consider your storage requirements and choose appropriate storage classes for data and logs
  • Security: Always configure appropriate security contexts and secrets management for production deployments
  • Dependencies: Use FULL_STEP_DP for custom dependency URLs with install scripts - ensure they contain valid install.sh files (see Install dependencies section)
  • Monitoring: Enable Prometheus plugin and configure appropriate health probes for production environments

Agent pools configuration

Step supports multiple agent pools with different technologies and configurations. Agent pools are defined as list entries, allowing you to create specialized agents for different test scenarios. By default, only the Java agent pool is enabled with 1 replica.

Basic Agent Pool Configuration

The default configuration includes three agent types: Java, .NET, and Node.js. Only the Java agent is enabled by default:

agent:
  pools:
    # Java Agent Pool (default enabled)
    - name: "java"
      displayName: "java-enterprise-agent"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 1
      tech:
        type: java
        version: 21
      startup:
        # Enable XVFB (virtual display) for UI testing with browsers/desktop apps
        xvfb: true
      config:
        agentPort: 33333
        NON_HEAP_MEMORY_MB: "1500"
        tokenGroups:
          - capacity: 1
            tokenConf:
              attributes:
                tech: java
              properties:
                tokenProp1: tokenValue1
        properties:
          prop1: "value1"
    
    # .NET Agent Pool (disabled by default)
    - name: "dotnet"
      displayName: "dotnet-enterprise-agent"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 0  # Set to desired number to enable
      tech:
        type: dotnet
        version: 8
      startup:
        # Enable XVFB (virtual display) for UI testing with browsers/desktop apps
        xvfb: true
      config:
        agentPort: 33333
        tokenGroups:
          - capacity: 1
            tokenConf:
              attributes:
                tech: dotnet
    
    # Node.js Agent Pool (disabled by default)  
    - name: "nodejs"
      displayName: "nodejs-enterprise-agent"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 0  # Set to desired number to enable
      tech:
        type: nodejs
        version: 20
      startup:
        # Enable XVFB (virtual display) for UI testing with browsers/desktop apps  
        xvfb: true
      config:
        agentPort: 33333
        tokenGroups:
          - capacity: 1
            tokenConf:
              attributes:
                tech: nodejs

Advanced Agent Pool Configuration

Production-ready agent pool with resource limits, security context, and external dependencies:

agent:
  pools:
    - name: "java-production"
      displayName: "Production Java Agent"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 3
      
      # Technology configuration
      tech:
        type: java
        version: 21
      
      # Security configuration
      podSecurityContext:
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 1000
        fsGroupChangePolicy: "OnRootMismatch"
      
      containerSecurityContext:
        runAsNonRoot: true
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
      
      # Resource allocation
      resources:
        requests:
          cpu: "500m"
          memory: "1800Mi"
        limits:
          cpu: "2000m"
          memory: "1800Mi"
      
      # Node placement
      nodeSelector:
        workload-type: "testing"
      
      tolerations:
        - key: "testing-nodes"
          operator: "Equal"
          value: "true"
          effect: "NoSchedule"
      
      # Agent configuration
      startup:
        # Enable XVFB (virtual display) for UI testing with browsers/desktop apps
        xvfb: true
      
      terminationGracePeriodSeconds: 60
      
      config:
        # Install external dependencies (see [Install dependencies section](#install-dependencies-to-your-pods-before-startup))
        FULL_STEP_DP: "https://your-repository.com/jmeter-5.6.2.zip,https://your-repository.com/k6-0.46.0.zip"
        JAVA_OPTS: "-Xms512m"
        NON_HEAP_MEMORY_MB: "1500"
        
        # Multiple token groups for load balancing
        tokenGroups:
          - capacity: 5
            tokenConf:
              attributes:
                tech: java
                type: ui-testing
                environment: production
              properties:
                tokenProp1: "value1"
          - capacity: 3
            tokenConf:
              attributes:
                tech: java
                type: api-testing
                environment: production
              properties:
                tokenProp2: "value2"
        
        # Global agent properties
        properties:
          plugins.jmeter.home: "/home/agent/jmeter"
          plugins.soapui.home: "/home/agent/soapui-5.7.0/SoapUI-5.7.0"
          plugins.k6.folder: "/home/agent/k6"
          plugins.pdftest.gsexe: "/usr/bin/ghostscript"

Java Agent Forker Configuration

The Java Agent Forker allows a single agent pod to spawn multiple child agents, providing better resource utilization. Available in Step 29+.

Basic Agent Forker Configuration

Simple forker setup with minimal configuration:

agent:
  pools:
    - name: "java-forker-basic"
      displayName: "Basic Java Agent with Forker"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 1
      
      # Enable agent forker (Step 29+)
      agentForker:
        enabled: true
      
      tech:
        type: java
        version: 21
      
      startup:
        # Enable XVFB (virtual display) for UI testing with browsers/desktop apps
        xvfb: true
      
      config:
        tokenGroups:
          - capacity: 5  # Forker can handle multiple tokens
            tokenConf:
              attributes:
                tech: java
                type: any
              properties:
                tokenProp1: "value1"

Advanced Agent Forker Configuration

Production-ready forker setup with custom settings and lifecycle management:

agent:
  pools:
    - name: "java-forker-advanced"
      displayName: "Advanced Java Agent with Forker"
      # Enable agent provisioning: allows automatic provisioning of agents based on plan requirements
      # See: https://step.dev/knowledgebase/29/userdocs/agent-provisioning/
      agentProvisioningTemplate: "true"
      replicaCount: 2
      
      # Enable agent forker with custom settings (Step 29+)
      agentForker:
        enabled: true
        javaPath: "/opt/java/openjdk/bin/java"
        vmArgs: "-Xms256m -Xmx1024m"
        startTimeoutMs: 20000
        shutdownTimeoutMs: 10000
        gridPort: 0
        agentPortRangeStart: 34000
        agentPortRangeEnd: 34100
      
      tech:
        type: java
        version: 21
      
      # Lifecycle hooks for proper shutdown
      lifecycleHooks:
        preStop:
          exec:
            command: ["/bin/bash", "-c", "pkill --signal SIGTERM -e java"]
      
      resources:
        requests:
          cpu: "100m"
          memory: "2000Mi"
        limits:
          cpu: "4000m"
          memory: "4000Mi"
      
      config:
        JAVA_OPTS: "-Dcom.sun.management.jmxremote -Djava.rmi.server.hostname=127.0.0.1"
        NON_HEAP_MEMORY_MB: "300"
        
        tokenGroups:
          - capacity: 10  # Forker can handle multiple tokens
            tokenConf:
              attributes:
                tech: java
                type: any
                $supportsCustomDockerImage: true
              properties:
                tokenProp1: "value1"

Specialized Agent Configuration

Configure agents with custom images, volumes, and specific tooling:

agent:
  pools:
    - name: "custom-agents"
      displayName: "Custom UI Testing Agents"
      replicaCount: 2
      
      # Custom runtime image
      image: "your-registry.com/step-custom:latest"
      
      tech:
        type: java
        version: 17
      
      # Custom secrets and configuration
      extraSecrets:
        stringData:
          custom-config-url: "http://your-service:8080/config"
        data:
          custom-cert: "LS0tLS1CRUdJTi..." # base64 encoded certificate
      
      # Mount custom volumes
      extraVolumeMounts:
        - name: "custom-config"
          mountPath: "/opt/custom-config"
          readOnly: true
        - name: "custom-cert"
          mountPath: "/opt/certs/custom.crt"
          subPath: custom-cert
      
      extraVolumes:
        - name: "custom-config"
          configMap:
            name: "custom-config"
        - name: "custom-cert"
          secret:
            secretName: "custom-agents"
      
      # Environment variables
      extraEnvVars:
        - name: "CUSTOM_CONFIG_URL"
          valueFrom:
            secretKeyRef:
              name: "custom-agents"
              key: custom-config-url
      
      config:
        # Install external dependencies (see [Install dependencies section](#install-dependencies-to-your-pods-before-startup))
        FULL_STEP_DP: "https://your-repository.com/chromedriver-119.zip,https://your-repository.com/geckodriver-0.33.zip"
        
        tokenGroups:
          - capacity: 2
            tokenConf:
              attributes:
                tech: java
                browser: chrome
                ui-testing: "true"
              properties:
                tokenProp1: "value1"
        
        properties:
          webdriver.chrome.driver: "/home/agent/chromedriver"
          webdriver.gecko.driver: "/home/agent/geckodriver"

Multi-Technology Agent Configuration

Configure different agent pools for various testing technologies:

agent:
  pools:
    # High-performance Java agents for load testing
    - name: "java-load"
      replicaCount: 5
      tech:
        type: java
        version: 21
      resources:
        requests:
          cpu: "1000m"
          memory: "2000Mi"
        limits:
          cpu: "2000m"
          memory: "2000Mi"
      config:
        # Install external dependencies (see [Install dependencies section](#install-dependencies-to-your-pods-before-startup))
        FULL_STEP_DP: "https://your-repository.com/jmeter-5.6.2.zip"
        tokenGroups:
          - capacity: 3
            tokenConf:
              attributes:
                tech: java
                type: load-testing
    
    # .NET agents for Windows-specific testing
    - name: "dotnet-windows"
      replicaCount: 2
      tech:
        type: dotnet
        version: 8
      nodeSelector:
        kubernetes.io/os: windows
      tolerations:
        - key: "os"
          operator: "Equal"
          value: "windows"
          effect: "NoSchedule"
      config:
        tokenGroups:
          - capacity: 2
            tokenConf:
              attributes:
                tech: dotnet
                os: windows
    
    # Node.js agents for modern web testing
    - name: "nodejs-web"
      replicaCount: 3
      tech:
        type: nodejs
        version: 20
      config:
        # Install external dependencies (see [Install dependencies section](#install-dependencies-to-your-pods-before-startup))
        FULL_STEP_DP: "https://your-repository.com/playwright-1.40.0.zip"
        tokenGroups:
          - capacity: 2
            tokenConf:
              attributes:
                tech: nodejs
                type: web-testing
                playwright: "true"

Important Notes:

  • These configuration samples are examples only - all URLs, paths, versions, and values should be updated according to your specific requirements and environment
  • The /home/agent path is reserved for agent binaries - use alternative paths like /opt/, /tmp/, or /var/ when mounting custom volumes to agents
  • XVFB configuration: XVFB (X Virtual Framebuffer) provides a virtual display server for headless UI testing. Set startup.xvfb: true for UI testing (browser automation, desktop applications), set to false for API-only testing to reduce resource usage
  • Agent pools support horizontal scaling by increasing replicaCount
  • Agent provisioning enables automatic provisioning of agents based on plan requirements (see Agent Provisioning)
  • Token groups define the capacity and attributes for agent selection in plans
  • Use FULL_STEP_DP for custom dependency URLs with install scripts (see Install dependencies section)
  • The agent forker feature is only available for Java agents in Step 29+
  • Always configure appropriate resource limits for production deployments

Optional configuration settings

Use additional volumes and volumes mounts

Below sample demonstrate how to add extra volumes and volumes mounts to your Pods.

Assuming that a secret called “my-company-secret” is mounted by a K8s administrator in your namespace, you could mount it to your Agents pods by adding the below in your values file, in the Agent section: 

...
extraVolumeMounts:
- mountPath: /opt/my-company-secret
  name: my-company-secret
  readOnly: true
extraVolumes:
- name: my-company-secret
  secret:
    secretName: my-company-secret
...

That way, your secret content will be mounted to the Agent(s) at /opt/my-company-secret.

Consult the official Kubernetes storage documentation at https://kubernetes.io/docs/concepts/storage/ for more details.

Mount the Step licenses via a pre-deployed secret

Assuming you do not want to use the values file to store the Step licenses, but instead use a Secret called “licenses” created in your namespace by an administrator, you could use the below sample: 

...
controller:
...
  extraVolumeMounts:
  - name: licenses
    mountPath: "/home/controller/licenses/licenses.json"
    subPath: "licenses.json"
  - name: licenses
    mountPath: "/home/controller/licenses/step-enterprise.licenseconfig.json"
    subPath: "step-enterprise.licenseconfig.json"
  ...
  extraVolumes:
  - name: licenses
    secret:
      secretName: licenses
   ...

Also ensure that the values fields “controller.licenses” and “controller.licenseconfig” are removed from your values file prior to your Helm installation / upgrade.

Add lifecycle hooks to your Pods

Assuming you would like to perform Agent post start actions, for instance adding a CA cert to a NSSB database store, add the below to your values file, in the Agent section:

...
lifecycleHooks:
  postStart:
    exec:
      command:
      - /bin/bash
      - -c
      - certutil -d /home/agent/.pki/nssdb -N --empty-password && certutil -A -n "My Company Root CA" -t "TCu,Cu,Tu" -i /home/agent/my-company-secret/ca.crt -d sql:/home/agent/.pki/nssdb/
...

Consult the official Kubernetes Pod lifecycle documentation at https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/ for more details.

Install dependencies to your PODs (before startup)

It is possible to install external dependencies before startup of the Controller or the Agents Pods using the FULL_STEP_DP special property, as per below: 

...
  config:
    FULL_STEP_DP: "https://nexus.mycompany.ch/mydependency-1.0.0.zip,https://artifactory.mycompany.ch/myotherdependency-1.0.0.zip"
 ...

The dependencies have to be specified as fully qualified URLs, comma separated, without extra spaces.

There are requirements for the dependencies installation:

  • They must be zip archives
  • There must be an “install.sh” file in the archive root -> the “install.sh” script will be executed on the Pods at startup, and can be used to perform various tasks before startup

Step Controller additional properties

It is possible to customize the Step Controller configuration file by appending extra properties, using the config.additionalProperties setting:

...
config:
  additionalProperties:
    cosmetics.folder: /home/controller/data/cosmetics
    cosmetics.interceptedResourceList: step-variables.css,logotopleft.png
    encryption.manager.keypair.folder: /home/controller/data/encryptionmanager
    plugins.EncryptionManagerControllerPlugin.enabled: true
    plugins.PrometheusControllerPlugin.enabled: true
    plugins.jmeter.home: /home/controller/jmeter-5.6.2/apache-jmeter-5.6.2/
    plugins.pdftest.gsexe: /home/controller/ghostscript/bin/ghostscript
    plugins.soapui.home: /home/controller/soapui-5.7.0/SoapUI-5.7.0/
    ...
...

Override default logback configuration (Step Controller and Java Agent only)

It is possible to override the default Step Controller and Java Agent logback.xml configuration file using the *.config.logbackConfiguration setting.

Below an example for the Step Controller:

...
controller:
  config:
    logbackConfiguration: |
      <configuration scan="true" scanPeriod="60 seconds">
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
          <encoder>
            <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
          </encoder>
        </appender>
        <logger name="org.lightcouch" level="error" /> 
        <root level="info">
         <appender-ref ref="STDOUT" />
        </root>
      </configuration>      
...

Use a custom access matrix

It is possible to define a custom access matrix to be used via the Controller values, as per below example:

...
controller:
  config:
    customAccessMatrix: |
      ,guest,tester,developer,admin
      plan-read,x,x,x,x
      plan-write,,x,x,x
      plan-delete,,x,x,x
      plan-execute,,x,x,x
      on-behalf-of,,,,x
      kw-read,x,x,x,x
      ...

Use a custom CA for your Java application

Assuming there is a secret called “controller-ca” deployed in your namespace containing a “cacerts” file you want to use with your Java application, you could use below example to configure the Step controller to use it:

...
controller:
  extraVolumeMounts:
  - name: "controller-ca"
    mountPath: /tmp/certs/java/cacerts
    subPath: cacerts
  extraVolumes:
  - name: "controller-ca"
    secret:
      secretName: "controller-ca"
  config:
    JAVA_OPTS: "-Djavax.net.ssl.trustStore=/tmp/certs/java/cacerts -Djavax.net.ssl.trustStorePassword=YOUR_CA_PASSWORD"
...
Same configuration is applicable for the Step agents.

See Also