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.
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.
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.
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.
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
Name | Version |
---|---|
aws | >= 4.0 |
Name | Version |
---|---|
archive | n/a |
aws | >= 4.0 |
null | n/a |
Name | Source | Version |
---|---|---|
asg | terraform-aws-modules/autoscaling/aws | ~> 6.0 |
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 |
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({ |
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) |
[ |
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({ |
[] |
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 |
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 |