Terraform AWS Spacelift Workerpool On EC2

Terraform module deploying a Spacelift worker pool on AWS EC2 using an autoscaling group.

This module can optionally deploy a Lambda function to auto-scale the worker pool. The function adds or removes workers depending on the worker pool queue length.

Usage

The most important is that you should provide SPACELIFT_TOKEN and SPACELIFT_POOL_PRIVATE_KEY environmental variables in the configuration variable to the module. More information can be found in the docs.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.57.0"
    }
  }
}

module "my_workerpool" {
  source = "github.com/spacelift-io/terraform-aws-spacelift-workerpool-on-ec2?ref=v2.6.1"

  configuration = <<-EOT
    export SPACELIFT_TOKEN="${var.worker_pool_config}"
    export SPACELIFT_POOL_PRIVATE_KEY="${var.worker_pool_private_key}"
  EOT

  min_size          = 1
  max_size          = 5
  worker_pool_id    = var.worker_pool_id
  security_groups   = var.worker_pool_security_groups
  vpc_subnets       = var.worker_pool_subnets
}

You also need to add the required values for spacelift_api_key_endpoint, spacelift_api_key_id, spacelift_api_key_secret and worker_pool_id to the module block for the Lambda Autoscaler function to set the required SPACELIFT_API_KEY_ENDPOINT, SPACELIFT_API_KEY_ID, SPACELIFT_API_KEY_SECRET_NAME and SPACELIFT_WORKER_POOL_ID parameters.

You can also set the optional autoscaling_max_create and autoscaling_max_terminate values in the module block for Lambda Autoscaler function to set the optional AUTOSCALING_MAX_CREATE and AUTOSCALING_MAX_KILL parameters. These parameters default to 1. These parameters set the maximum number of instances the utility is allowed to create or terminate in a single run.

Default AMI

The default AMI used by this module comes from the spacelift-worker-image repository. You can find the full list of AMIs on the releases page.

ARM-based AMI

You can use an ARM-based AMI by setting the ami_id variable to an arm64 AMI, and ec2_instance_type to an ARM-based instance type (e.g. t4g.micro).

We recommend using Spacelift AMIs because they come with every required tool preinstalled.

You can find an example of ARM-based workerpool in the examples directory.

❗️ If you use custom runner images, make sure they support ARM. The default Spacelift images do support it.

How to generate docs

The generated documentation is between BEGIN_TF_DOCS and END_TF_DOCS comments in the README.md file. Use the following command to update the docs:

$ make docs

Requirements

Name	Version
aws	>= 4.0

Providers

Name	Version
archive	n/a
aws	>= 4.0
null	n/a

Modules

Name	Source	Version
asg	terraform-aws-modules/autoscaling/aws	~> 6.0

Resources

Name	Type
aws_cloudwatch_event_rule.scheduling	resource
aws_cloudwatch_event_target.scheduling	resource
aws_cloudwatch_log_group.log_group	resource
aws_iam_instance_profile.this	resource
aws_iam_role.autoscaler	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.this	resource
aws_lambda_function.autoscaler	resource
aws_lambda_permission.allow_cloudwatch_to_call_lambda	resource
aws_ssm_parameter.spacelift_api_key_secret	resource
null_resource.download	resource
archive_file.binary	data source
aws_ami.this	data source
aws_iam_policy_document.autoscaler	data source
aws_region.this	data source

Inputs

Name	Description	Type	Default	Required
additional_tags	Additional tags to set on the resources	map(string)	{}	no
ami_id	ID of the Spacelift AMI. If left empty, the latest Spacelift AMI will be used.	string	""	no
autoscaler_architecture	Instruction set architecture of the autoscaler to use	string	"amd64"	no
autoscaler_s3_package	Configuration to retrieve autoscaler lambda package from s3 bucket	object({ bucket = string key = string object_version = optional(string) })	null	no
autoscaler_version	Version of the autoscaler to deploy	string	"v0.3.0"	no
autoscaling_max_create	The maximum number of instances the utility is allowed to create in a single run	number	1	no
autoscaling_max_terminate	The maximum number of instances the utility is allowed to terminate in a single run	number	1	no
autoscaling_timeout	Timeout (in seconds) for a single autoscaling run. The more instances you have, the higher this should be.	number	30	no
base_name	Base name for resources. If unset, it defaults to sp5ft-${var.worker_pool_id}.	string	null	no
configuration	User configuration. This allows you to decide how you want to pass your token and private key to the environment - be that directly, or using SSM Parameter Store, Vault etc. Ultimately, here you need to export SPACELIFT_TOKEN and SPACELIFT_POOL_PRIVATE_KEY to the environment.	string	n/a	yes
create_iam_role	Determines whether an IAM role is created or to use an existing IAM role	bool	true	no
custom_iam_role_name	Name of an existing IAM to use. Used when create_iam_role = false	string	""	no
disable_container_credentials	If true, the run container will not be able to access the instance profile credentials by talking to the EC2 metadata endpoint. This is done by setting the number of hops in IMDSv2 to 1. Since the Docker container goes through an extra NAT step, this still allows the launcher to talk to the endpoint, but prevents the container from doing so.	bool	false	no
domain_name	Top-level domain name to use for pulling the launcher binary	string	"spacelift.io"	no
ec2_instance_type	EC2 instance type for the workers. If an arm64-based AMI is used, this must be an arm64-based instance type.	string	"t3.micro"	no
enable_autoscaling	Determines whether to create the Lambda Autoscaler function and dependent resources or not	bool	true	no
enable_monitoring	Enables/disables detailed monitoring	bool	true	no
enabled_metrics	List of CloudWatch metrics enabled on the ASG	list(string)	[ "GroupDesiredCapacity", "GroupInServiceInstances", "GroupMaxSize", "GroupMinSize", "GroupPendingInstances", "GroupStandbyInstances", "GroupTerminatingInstances", "GroupTotalInstances" ]	no
instance_refresh	If this block is configured, start an Instance Refresh when this Auto Scaling Group is updated based on instance refresh configration.	any	{}	no
max_size	Maximum number of workers to spin up	number	10	no
min_size	Minimum numbers of workers to spin up	number	0	no
poweroff_delay	Number of seconds to wait before powering the EC2 instance off after the Spacelift launcher stopped	number	15	no
schedule_expression	Autoscaler scheduling expression	string	"rate(1 minute)"	no
security_groups	List of security groups to use	list(string)	n/a	yes
spacelift_api_key_endpoint	Full URL of the Spacelift API endpoint to use, eg. https://demo.app.spacelift.io	string	null	no
spacelift_api_key_id	ID of the Spacelift API key to use	string	null	no
spacelift_api_key_secret	Secret corresponding to the Spacelift API key to use	string	null	no
tag_specifications	Tag specifications to set on the launch template, which will apply to the instances at launch	list(object({ resource_type = string tags = optional(map(string), {}) }))	[]	no
volume_encryption	Whether to encrypt the EBS volume	bool	false	no
volume_encryption_kms_key_id	KMS key ID to use for encrypting the EBS volume	string	null	no
volume_size	Size of instance EBS volume	number	40	no
vpc_subnets	List of VPC subnets to use	list(string)	n/a	yes
worker_pool_id	ID (ULID) of the the worker pool.	string	n/a	yes

Outputs

Name	Description
autoscaling_group_arn	ARN of the auto scaling group
autoscaling_group_name	Name of the auto scaling group
instances_role_arn	ARN of the IAM role of the EC2 instances. Will only be populated if the IAM role is created by this module
instances_role_name	Name of the IAM role of the EC2 instances. Will only be populated if the IAM role is created by this module
launch_template_id	ID of the launch template