The AWS external provider allows garm to create Linux and Windows runners on top of AWS virtual machines.

Clone the repo:

git clone https://github.com/cloudbase/garm-provider-aws

Build the binary:

cd garm-provider-aws
go build .

Copy the binary on the same system where garm is running, and point to it in the config.

The config file for this external provider is a simple toml used to configure the AWS credentials it needs to spin up virtual machines.

region = "eu-central-1"
subnet_id = "sample_subnet_id"

[credentials]
    access_key_id = "sample_access_key_id"
    secret_access_key = "sample_secret_access_key"
    session_token = "sample_session_token"

After you add it to garm as an external provider, you need to create a pool that uses it. Assuming you named your external provider as aws in the garm config, the following command should create a new pool:

garm-cli pool create \
    --os-type windows \
    --os-arch amd64 \
    --enabled=true \
    --flavor t2.small \
    --image ami-0d5f36b04ca291a9f \
    --min-idle-runners 0 \
    --repo 5b4f2fb0-3485-45d6-a6b3-545bad933df3 \
    --tags aws,windows \
    --provider-name aws

This will create a new Windows runner pool for the repo with ID 5b4f2fb0-3485-45d6-a6b3-545bad933df3 on AWS, using the image with AMI ID ami-0d5f36b04ca291a9f and instance type t2.small. You can, of course, tweak the values in the above command to suit your needs.

Here an example for a Linux pool:

garm-cli pool create \
    --os-type linux \
    --os-arch amd64 \
    --enabled=true \
    --flavor t2.small \
    --image ami-04c0bb88603bf2e3d \
    --min-idle-runners 0 \
    --repo 5b4f2fb0-3485-45d6-a6b3-545bad933df3 \
    --tags aws,ubuntu \
    --provider-name aws

Always find a recent image to use. For example to see available Windows server 2022 images, run something like aws ec2 describe-images --region eu-central-1 --owners self amazon --filters "Name=platform,Values=windows" "Name=name,Values=*Windows_Server-2022*".

Garm supports sending opaque json encoded configs to the IaaS providers it hooks into. This allows the providers to implement some very provider specific functionality that doesn't necessarily translate well to other providers. Features that may exists on AWS, may not exist on Azure or OpenStack and vice versa.

To this end, this provider supports the following extra specs schema:

{
    "$schema": "http://cloudbase.it/garm-provider-aws/schemas/extra_specs#",
    "type": "object",
    "description": "Schema defining supported extra specs for the Garm AWS Provider",
    "properties": {
        "subnet_id": {
            "type": "string",
            "pattern": "^subnet-[0-9a-fA-F]{17}$"
        }
    },
	"additionalProperties": false
}

To set it on an existing pool, simply run:

garm-cli pool update --extra-specs='{"subnet_id":"subnet-0e7a29d5cf6e54789"}' <POOL_ID>

You can also set a spec when creating a new pool, using the same flag.

Workers in that pool will be created taking into account the specs you set on the pool.