garm-provider-vultr

A garm external provider for Vultr, written in Crystal.

This provider enables garm to manage GitHub Actions self-hosted runners on Vultr cloud instances.

Prerequisites

• Crystal >= 1.14.0
• A Vultr account with API access
• A running garm installation

Building

Development build

shards build --release

Static build (for Docker / container deployment)

The garm container does not have system libraries like libz.so. You must build a statically linked binary:

docker run --rm -v $(pwd):/workspace -w /workspace \
  crystallang/crystal:latest-alpine \
  sh -c "shards install --production && crystal build src/main.cr -o bin/garm-provider-vultr --release --static --no-debug && strip bin/garm-provider-vultr"

The binary will be available at bin/garm-provider-vultr.

Configuration

Provider Config File

Create a JSON configuration file (e.g., /etc/garm/vultr-provider.json):

{
  "api_key": "",
  "region": "ewr",
  "plan": "vc2-1c-1gb",
  "os_id": 1743,
  "sshkey_id": [],
  "enable_ipv6": false,
  "firewall_group_id": "",
  "enable_vpc": false,
  "attach_vpc": []
}

Field	Type	Required	Description
api_key	string	No*	Vultr API key. Prefer using VULTR_API_KEY env var instead.
region	string	Yes	Default Vultr region (e.g., ewr, lax, ord). See Vultr regions.
plan	string	Yes	Default instance plan (e.g., vc2-1c-1gb). See Vultr plans.
os_id	int	Yes**	Default OS template ID (e.g., 1743 for Ubuntu 22.04 x64).
sshkey_id	string[]	No	SSH key IDs to inject into instances.
enable_ipv6	bool	No	Enable IPv6 on instances.
firewall_group_id	string	No	Vultr firewall group ID to apply.
enable_vpc	bool	No	Enable VPC for instances.
attach_vpc	string[]	No	VPC IDs to attach to instances.

* The API key can be provided via the VULTR_API_KEY environment variable (recommended) or in the config file.

** At least one OS source must be provided: os_id, snapshot_id, or image_id (via pool extra_specs).

Pool Extra Specs

Per-pool overrides can be set in the garm pool configuration under extra_specs:

{
  "region": "lax",
  "plan": "vc2-2c-4gb",
  "os_id": 2136,
  "snapshot_id": "",
  "image_id": "",
  "sshkey_id": ["ssh-key-1"],
  "enable_ipv6": true,
  "firewall_group_id": "fw-123",
  "enable_vpc": true,
  "attach_vpc": ["vpc-1"],
  "extra_packages": ["docker.io"],
  "disable_updates": false,
  "enable_boot_debug": false
}

Field	Type	Description
region	string	Override default Vultr region.
plan	string	Override default instance plan.
os_id	int	Override default OS template ID.
snapshot_id	string	Use a Vultr snapshot instead of os_id.
image_id	string	Use a Vultr marketplace image instead of os_id.
sshkey_id	string[]	Override SSH key IDs.
enable_ipv6	bool	Enable IPv6 on instances.
firewall_group_id	string	Override firewall group ID.
enable_vpc	bool	Enable VPC for instances.
attach_vpc	string[]	VPC IDs to attach.
extra_packages	string[]	Extra packages to install via cloud-init (e.g., ["docker.io"]).
disable_updates	bool	Disable OS updates on boot.
enable_boot_debug	bool	Enable boot debug logging.

Pool extra_specs override the provider config defaults.

Environment Variables

Variable	Description
VULTR_API_KEY	Vultr API key (preferred over config file).

The following are set by garm automatically:

Variable	Description
GARM_COMMAND	The operation to execute.
GARM_PROVIDER_CONFIG_FILE	Path to the provider config file.
GARM_CONTROLLER_ID	Unique garm controller ID.
GARM_POOL_ID	Pool ID (for CreateInstance, ListInstances).
GARM_INSTANCE_ID	Instance provider ID (for GetInstance, DeleteInstance, Start, Stop).
GARM_POOL_EXTRASPECS	Base64-encoded pool extra specs JSON.
GARM_INTERFACE_VERSION	Provider interface version.

Garm Configuration

Add the provider to your garm config:

[[provider]]
name = "vultr"
description = "Vultr provider"
provider_type = "external"
  [provider.external]
  config_file = "/etc/garm/vultr-provider.json"
  provider_executable = "/usr/local/bin/garm-provider-vultr"
  interface_version = "0.1.1"
  environment_variables = ["VULTR_API_KEY=your-api-key-here"]

Supported Commands

Command	Description
CreateInstance	Creates a new Vultr instance with cloud-init for runner bootstrap.
DeleteInstance	Deletes a Vultr instance (idempotent - no-op if already deleted).
GetInstance	Returns instance details.
ListInstances	Lists all instances for a given pool.
RemoveAllInstances	Removes all instances tagged with the controller ID.
Start	Starts (boots) a stopped instance.
Stop	Stops (halts) a running instance.

Common Vultr OS IDs

OS ID	OS
1743	Ubuntu 22.04 x64
2136	Ubuntu 24.04 x64
1946	Debian 12 x64
2076	Rocky Linux 9 x64
2187	AlmaLinux 9 x64

Troubleshooting

• API errors: Check that VULTR_API_KEY is set and valid.
• Instance not creating: Verify region, plan, and os_id are valid Vultr values.
• Runner not registering: Check the instance's cloud-init logs at /var/log/cloud-init-output.log.
• Logs: The provider writes diagnostic logs to stderr. Check garm's logs for provider output.

License

Apache-2.0