Skip to content

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

License

Notifications You must be signed in to change notification settings

spacelift-io/terraform-aws-spacelift-workerpool-on-ec2

Repository files navigation

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 >= 5.55.0

Providers

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

Modules

Name Source Version
asg terraform-aws-modules/autoscaling/aws ~> 8.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.autoscaler 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

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published