Release 2.9.0 - Improved Architecture, Spot Instances, Flexible Configuration

Published on January 17, 2025 | Written by Andreas

We are happy to announce version 2.9.0 of HyperEnv for GitHub Actions Runners which includes the following new features and changes.

Release 2.9.0 - Improved Architecture, Spot Instances, Flexible Configuration

Improved Architecture

We reworked HyperEnv’s architecture. Until now, an incoming event from GitHub was processed by API Gateway, Lambda, and SQS.

  1. API Gateway recieves HTTP request from GitHub.
  2. API Gateway invokes the Lambda function named webhook.
  3. The Lambda function webhook verifies the incoming webhook event.
  4. The Lambda function webhook sends a message to SQS.
  5. Another Lambda function called consumer polls SQS for messages.
  6. The Lambda function consumer processes the message, registers a just-in-time GitHub runner and launches an EC2 instance.

The architecture ensured a reliable processing of the GitHub webhook events. The usage of SQS enabled a reliable and scalable retry mechanism to handle rate limiting or other issues when launching EC2 instances.

However, SQS does not allow fine-granular configuration of the retry mechanism. That’s why we decided to change the architecture and replace SQS with Step Functions. Step Functions allow us to optimize the retry mechanism in case an EC2 instance cannot be launched. That’s especially important, because of the feature we will discuss next: the usage of spot instances to reduce costs.

The following figure illustrated the new architecture.

  1. API Gateway recieves HTTP request from GitHub.
  2. API Gateway invokes the Lambda function named webhook.
  3. The Lambda function webhook verifies the incoming webhook event.
  4. The Lambda function webhook starts an execution of the Step Function runner-orchestrator.
  5. The Step Function invokes the Lambda function consumer which tries to launch a spot instance.
  6. In case a spot instance is not available in the selected availability zone, the Step Function retries launching a spot instance in another availability zone.
  7. In case it is not possible to launch a spot instance, the Step Function continuse and calls the Lambda function consumer again to launch an on-demand instance.

Improved HyperEnv architecture leverages Step Functions

On top of that, the Step Function waits for the EC2 instance to start the hyperenv service. In case of a failure or timeout, Step Functions will retry by launching another EC2 instance.

Spot Instances

We aim to provide a cost effective solution to depoloy self-hosted GitHub runners on AWS. There are three major methods to reduce costs for Amazon EC2:

  • Shut down EC2 instances, that are not running any workloads.
  • Get discounts by using spare capacity in Amazon’s data centers with spot instances.
  • Commit to a certain usage of virtual machines upfront to get discounts.

As HyperEnv launches a temporary EC2 instance for every GitHub job and terminates the instance right after the job finished, you are not paying for unused compute capacity.

However, to cut costs even more, we’ve added support for spot instances with version 2.9.0. The following screenshot shows the spot prices for an m5.large instance. During the past 3 months, making use of spot instances instead of on-demand instances would have saved you about 60% of the EC2 instance costs.

There are two ways to enable spot instances for your HyperEnv deployment.

  1. Update the CloudFormation stack and set the parameter SpotInstance to true.
  2. Set the configuration option spot=true for a specific GitHub workflow as described in the next section.

Please note, there is one catch when using spot instances. It is possible, that AWS terminates a running spot instance to free capacity for other customers. Based on our observation, those spot interruptions are very rare for short running instances. However, there is a low risk that a GitHub job will be interrupted when using spot instances. So ensure you are using spot instances for GitHub workflows where interruption of a running job will not cause a big issue.

Flexible Configuration

We have learned from your feedback, that not all GitHub workflows come with the same compute requirements. That’s why simplify configuring HyperEnv for each GitHub workflow.

Just add the tag hyperenv-config to the runs-on parameter of a GitHub workflow. Doing so allows you to override the default instance type (parameter InstanceType) and spot instance configuration (parameter SpotInstance) from HyperEnv’s CloudFormation stack.

  • spot: Launch spot instance instead of on-demand instance (allowed values: true or false).
  • instance: Define the instance type for the virtual machine (allowed values: see supported instance types below).
name: hyperenv-demo
on:
  workflow_dispatch
jobs:
  hyperenv-demo:
    runs-on:
    - hyperenv:
    - hyperenv-config:instance=t3.small,spot=true
    steps:
    - run: 'echo "Hello HyperEnv"'

By the way, the flexiblity to configure an instance type inside the GitHub workflow definition allows you to use smaller instance types for jobs, that require little compute capacity. Doing so will reduce costs even further.

Here is a list of all instance types supported by HyperEnv.

t3.small
t3.medium
t3.large
t3.xlarge
t3.2xlarge
m5.large
m5.xlarge
m5.2xlarge
m5.4xlarge
m5.8xlarge
m5.12xlarge
m5.16xlarge
m5.24xlarge
m6i.large
m6i.xlarge
m6i.2xlarge
m6i.4xlarge
m6i.8xlarge
m6i.12xlarge
m6i.16xlarge
m6i.24xlarge
m6i.32xlarge
m7i.large
m7i.xlarge
m7i.2xlarge
m7i.4xlarge
m7i.8xlarge
m7i.12xlarge
m7i.16xlarge
m7i.24xlarge
m7i.48xlarge
g4dn.xlarge
g4dn.2xlarge
g4dn.4xlarge
g4dn.8xlarge
g4dn.12xlarge
g4dn.16xlarge

Update HyperEnv

So it’s time to update HyperEnv now. Please follow our upgrade guide to do so. Don’t be afraid, version 2.9.0 is fully backwards compatible and updating HyperEnv does not interrupt running GitHub jobs.

Feedback welcome!

We love to hear your feedback on version 2.9.0. Are you missing any features? Is there anything we can improve? Please let us know: hello@hyperenv.com.