terraform-aws-imagebuilder-pipeline

Terraform module for creating EC2 Image Builder Pipelines

Example

Here's what using the module will look like. Note that this module needs at least one recipe and component to be useful. See examples for details.

module "test_pipeline" {
  source  = "rhythmictech/imagebuilder-pipeline/aws"

  description = "Testing pipeline"
  name        = "test-pipeline"
  recipe_arn  = module.test_recipe.recipe_arn
  public      = false
}

About

Allows the creation of EC2 Image Builder Pipelines

Build Scheduling

Builds are scheduled by a cron pattern. The pipeline takes a schedule argument as follows:

  schedule_cron = "cron(0 0 * * mon)"
  schedule_pipeline_execution_start_condition = "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE"
    

The default expects an upstream AMI as a parent image and will build weekly only if an updated image is found upstream. By setting schedule_pipeline_execution_start_condition = "EXPRESSION_MATCH_ONLY", the build pipeline will always run.

When scheduling linked jobs, it is important to be mindful of the cron schedules. If both pipelines run with schedule_cron = "cron(0 0 * * mon)", the downstream build will always run one week late. Due to the testing phase and startup/teardown time, even a short EC2 Image Builder process can take over 15 minutes to run end to end. Complex test suites can take much longer.

See Amazon's EC2 Image Builder API Reference for further details.

Providing Launch Template configurations

If you want to update launch configurations as part of the Image Build process, you can provide them with the launch_template_configurations variable. It accepts a map of regions, where each region is a list of launch template configuration maps (one per account) for that region. It will look like this:

  launch_template_configurations  = {
    "us-east-1" = [
      {
        launch_template_id = "lt-0f1aedef76c015126"
        account_id         = "123456789012"
      },
      {
        launch_template_id = "lt-0f1aedef86c049140"
        account_id         = "234567890123"
        default            = "false"
      }
    ]
    "us-west-1" = [
      {
        launch_template_id = "lt-0f1aedef76c015113"
        account_id         = "123456789012"
      }
    ]
  }

Note that you do not have to provide a launch template configuration for every account and region you build AMIs in. You will also need to set up IAM permissions in the destination accounts per https://docs.aws.amazon.com/imagebuilder/latest/userguide/cross-account-dist.html. (You will need to set similar permissions via additional_iam_policy_arns for your own image builder pipeline if it is writing to your own account)

Providing your own Distribution Configuration

By default this module will try to handle the aws_imagebuilder_distribution_configuration configuration by itself. This works for more simple builds that only need to create EC2 images, but it may not be suitable for all users. The custom_distribution_configs aims to handle this by allowing users to provide a list of distribution configuration blocks, based off of the terraform described at https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_distribution_configuration#distribution. Where additional configuration blocks are present, they must be replaced with a map of the same name. An example of this is:

  custom_distribution_configs = [
    {
      region = "us-east-1",
      ami_distribution_configuration = {
        name = "example-build-{{ imagebuilder:buildDate }}"
        launch_permission = {
          user_ids = ["123456789012"]
        }
      }
      launch_template_configuration = {
        launch_template_id = "lt-0123456789abcde"
      }
    },
    {
      region = "us-west-1"
      ami_distribution_configuration = {
        name = "example-build-{{ imagebuilder:buildDate }}"
      }
      ...
    }
  ]

Requirements

Name	Version
terraform	>= 0.14
aws	>= 4.22.0

Providers

Name	Version
aws	4.66.0

Modules

No modules.

Resources

Name	Type
aws_iam_instance_profile.this	resource
aws_iam_policy.log_write	resource
aws_iam_policy.secret_read	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.additional	resource
aws_iam_role_policy_attachment.core	resource
aws_iam_role_policy_attachment.log_write	resource
aws_iam_role_policy_attachment.secret_read	resource
aws_imagebuilder_distribution_configuration.this	resource
aws_imagebuilder_image_pipeline.this	resource
aws_imagebuilder_infrastructure_configuration.this	resource
aws_iam_policy_document.assume	data source
aws_iam_policy_document.log_write	data source
aws_iam_policy_document.secret_read	data source
aws_secretsmanager_secret.ssh_key	data source

Inputs

Name	Description	Type	Default	Required
additional_iam_policy_arns	List of ARN policies for addional builder permissions	list(string)	[]	no
container_recipe_arn	ARN of the container recipe to use. Must change with Recipe version	string	null	no
custom_distribution_configs	To use your own distribution configurations for the ImageBuilder Distribution Configuration, supply a list of distribution configuration blocks as defined at https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_distribution_configuration#distribution	any	[]	no
description	description of component	string	null	no
enabled	Whether pipeline is ENABLED or DISABLED	bool	true	no
enhanced_image_metadata_enabled	Whether additional information about the image being created is collected. Default is true.	bool	true	no
image_name	The name prefix given to the AMI created by the pipeline (a timestamp will be added to the end)	string	""	no
image_recipe_arn	ARN of the image recipe to use. Must change with Recipe version	string	null	no
image_tests_enabled	Whether to run tests during image creation	bool	true	no
image_tests_timeout_minutes	Maximum time to allow for image tests to run	number	60	no
instance_key_pair	EC2 key pair to add to the default user on the builder	string	null	no
instance_metadata_http_put_hop_limit	The number of hops that an instance can traverse to reach its metadata.	number	null	no
instance_metadata_http_tokens	Whether a signed token is required for instance metadata retrieval requests. Valid values: required, optional.	string	"optional"	no
instance_types	Instance types to create images from. It's unclear why this is a list. Possibly because different types can result in different images (like ARM instances)	list(string)	[ "t3.medium" ]	no
kms_key_id	KMS Key ID to use when encrypting the distributed AMI, if applicable	string	null	no
launch_template_configurations	A map of regions, where each region is a list of launch template configuration maps (one per account) for that region. Not used when custom_distribution_configs is in use.	any	{}	no
license_config_arns	If you're using License Manager, your ARNs go here	set(string)	null	no
log_bucket	Bucket to store logs in. If this is ommited logs will not be stored	string	null	no
log_prefix	S3 prefix to store logs at. Recommended if sharing bucket with other pipelines	string	null	no
name	name to use for component	string	n/a	yes
public	Whether resulting AMI should be public	bool	false	no
regions	Regions that AMIs will be available in	list(string)	[ "us-east-1", "us-east-2", "us-west-1", "us-west-2", "ca-central-1" ]	no
resource_tags	Key-value map of tags to apply to resources created by this pipeline	map(string)	null	no
schedule_cron	Schedule (in cron) for when pipeline should run automatically https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-imagebuilder-imagepipeline-schedule.html	string	""	no
schedule_pipeline_execution_start_condition	Start Condition Expression for when pipeline should run automatically https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-imagebuilder-imagepipeline-schedule.html	string	"EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE"	no
schedule_timezone	Timezone (in IANA timezone format) that scheduled builds, as specified by schedule_cron, run on	string	"Etc/UTC"	no
security_group_ids	Security group IDs for the Image Builder	list(string)	null	no
shared_account_ids	AWS accounts to share AMIs with. If this is left null AMIs will be public	set(string)	[]	no
shared_organization_arns	Set of AWS Organization ARNs to allow access to the created AMI	set(string)	null	no
shared_ou_arns	Set of AWS Organizational Unit ARNs to allow access to the created AMI	set(string)	null	no
sns_topic_arn	SNS topic to notify when new images are created	string	null	no
ssh_key_secret_arn	If your ImageBuilder Components need to use an SSH Key (private repos, etc.), specify the ARN of the secretsmanager secret containing the SSH key to add access permissions (use arn OR name, not both)	string	null	no
ssh_key_secret_name	If your ImageBuilder Components need to use an SSH Key (private repos, etc.), specify the Name of the secretsmanager secret containing the SSH key to add access permissions (use arn OR name, not both)	string	null	no
subnet	Subnet ID to use for builder	string	null	no
tags	map of tags to use for component	map(string)	{}	no
terminate_on_failure	Change to false if you want to connect to a builder for debugging after failure	bool	true	no

Outputs

Name	Description
pipeline_arn	ARN of EC2 Image Builder Pipeline
role_name	The name of the IAM role for use if additional permissions are needed.

The Giants underneath this module

• pre-commit.com/
• terraform.io/
• github.com/tfutils/tfenv
• github.com/segmentio/terraform-docs