Self-Hosted Runner Pools

Self-hosted Runner Pools enable you to provision Runners to run pipelines on any infrastructure, including inside on-premise environments and behind firewalls. The Runner Pool is packaged as an executable that can be can be deployed in a container or Virtual Machine (VM).

Authentication

Self-hosted Runner Pools require a unique identifier (RUNNER_MANAGER_ID), as well as an authentication token (RUNNER_MANAGER_KEY) to authenticate with the agent server.

RUNNER_MANAGER_KEY is similar to a password, and should be stored securely. It can also be regenerated from Sophos Factory, which will immediately invalidate any runners, or runner pools that are currently using the key until their configuration files are updated.

Changing the key requires a re-deployment of the Runner Pool.

You can find these values by navigating to Account Settings –> Runner Pools –> Click a runner pool –> Click Show Key

Deploying the Runner Pool

Configuring Runner Pool

The Runner Pool requires configuration for both authentication, as well as the provider which is used for provisioning runners.

{
  "ENVIRONMENT": "The name of your environment. Our pre-built helm chart defaults this to `prod`",
  "RUNNER_MANAGER_KEY": "The secure password used to authenticate with Sophos Factory.",
  "RUNNER_MANAGER_ID": "The unique identifier of the Runner Pool.",
}

CloudFormation Provider Configuration

{
    "RUNNER_EC2_IMAGE_REGION": "The AWS region where the AMI is located.",
    "RUNNER_EC2_INSTANCE_TYPE": "The AWS EC2 Instance Type to deploy.",
    "RUNNER_EC2_SUBNETS": "An array of AWS VPC subnet ID strings.",
    "RUNNER_EC2_SECURITY_GROUP_ID": "The security group ID to apply to the EC2 VM.",
    "RUNNER_EC2_IMAGE_ACCOUNT_ID": "The AWS account number where the AMI is located. Default is 835705546860",
    "RUNNER_EC2_IMAGE_PREFIX": "AMI image prefix used to search for Runner AMIs. Defaults to factory_runner_x64_centos8_2.0.*_*ENV*_",
    "RUNNER_EC2_AUTOLATEST": "If true, automatically uses latest Runner AMI.",
}

Kubernetes Provider Configuration

{
    "RUNNER_K8S_IMAGE_REGISTRY": "Location of the container registry. Defaults to 864584331736.dkr.ecr.us-west-2.amazonaws.com",
    "RUNNER_K8S_IMAGE_REPOSITORY": "Name of container repository. Defaults to 'sophos/fac-runner'",
    "RUNNER_K8S_IMAGE_TAG": "Container tag to use. Defaults to 'latest'",
    "RUNNER_K8S_NAMESPACE": "Namespace to deploy Runners to. Defaults to `${ prefix }-${ env }-runner`",
    "RUNNER_K8S_CPU_REQUEST": "CPU units to request for Runner pod.",
    "RUNNER_K8S_CPU_LIMIT": "CPU units to limit Runner pod to.",
    "RUNNER_K8S_MEM_REQUEST": "Memory units to request for Runner pod.",
    "RUNNER_K8S_MEM_LIMIT": "Memory units to limit for Runner Pod."
}

Docker Provider Configuration

See Docker Provider Configuration.

Customizing Runner

A runner may be customized by extending our Runner Containers/AMIs, or by downloading the binary and building your own.

Runner Configuration

Runner customization can be achieved by overriding configuration. By default, it will look for the configuration file in /etc/runner-agent.json. You may also specify the path to the configuration file by setting the CONFIG_PATH environment variable.

Below is an example runner configuration file with all possible fields and their default values. All of these fields are optional.

{
  "AGENT_API_BASE_URL": "https://agent-api.refactr.it/v1",
  "LOG_PATH": "/var/log/runner-agent",
  "LOG_FILENAME_PATTERN": "runner-agent-%DATE%.log",
  "LOG_RETENTION": 20,
  "LOG_LEVEL": "info",
  "WORKSPACE_PATH": "/opt/runner-agent/workspace"
}

• AGENT_API_BASE_URL: The base URL of the agent API.
• LOG_PATH: Path to the directory where log files will be written.
• LOG_FILENAME_PATTERN: If LOG_PATH is provided, specifies the log file naming pattern. Occurrences of %DATE% will be replaced with the current date in YYYY-MM-DD format.
• LOG_RETENTION: The retention duration for log files. If a number is provided, this is the maximum number of log files. If a string ending in d is provided, such as 20d, this is the number of days before log files are deleted.
• LOG_LEVEL: The verbosity of log output. Valid values are info, warning, debug, or error.
• WORKSPACE_PATH: Path to the root of the runner workspace. Pipeline run directories will be created within this directory.