EC2 Image Builder Pipeline Module

📕 Description

This module is designed to provide a full EC2 Image Builder workflow from pipeline creation through to generation of the AMI itself. It is also designed to be highly customizable by exposing most configuration attributes of the underlying resources; while at the same time this module can be ran with a minimal number of input variables in order to make generating several pipelines quickly a painless process. This module also creates the IAM resources necessary for the build/test stages of EC2 Image Builder to function properly.

⚠️ Notes

• Containers are not yet supported; functionality is planned!

• You MUST specify at least one component to be used in the EC2 image builder recipe. This can either be a custom component (via var.imgb_components) or a managed/shared component (via var.imgb_aws_components). For each custom component, only one of either the data or uri attributes may be entered.

• Component ordering is global across custom and managed component resources. When specifying the order attribute of a component, ensure order uniqueness across both var.imgb_components and var.imgb_aws_components.

• Component ordering cannot currently be changed between terraform apply runs due to the nature of Terraform dynamic blocks and the inability to force ordering of these. If you need to change the component order after creation, destroy then recreate the stack.

• When configuring AMI distribution (imgdistcfg_distribution) the ami_dist_cfg property must contain the AWS variable {{imagebuilder:buildDate}}.

🔍 Using This Module

The only required input variables to the module from your root module are:

• imgb_stackname
• imgrep_parent_img
• imgb_components or imgb_aws_components

By only providing the required input variables, this module will create an EC2 Image Builder pipeline with default settings and manual execution for the creation of an image with the given imgrep_parent_img as the base AMI, and then any given imgb_components or imgb_aws_components are applied on top of them.

Examples

Refer to the examples/ dir for basic and more involved examples.

Requirements

Name	Version
terraform	>= 1.1.0
aws	>= 4.9.0

Providers

Name	Version
aws	>= 4.9.0

Modules

No modules.

Resources

Name	Type
aws_iam_instance_profile.main	resource
aws_iam_policy.custom	resource
aws_iam_policy.s3logs	resource
aws_iam_role.main	resource
aws_iam_role_policy_attachment.custom	resource
aws_iam_role_policy_attachment.s3logs	resource
aws_imagebuilder_component.main	resource
aws_imagebuilder_distribution_configuration.main	resource
aws_imagebuilder_image.main	resource
aws_imagebuilder_image_pipeline.main	resource
aws_imagebuilder_image_recipe.main	resource
aws_imagebuilder_infrastructure_configuration.main	resource

Inputs

Name	Description	Type	Default	Required
imgb_aws_components	A map of objects with each object representing a pre-existing image builder component. To be used with managed AWS, shared, or other preexisting components you would like to reuse that aren't managed by this stack.	map(object({ arn = string parameters = optional(list(object({ name = string value = list(string) }))) order = optional(number) }))	{}	no
imgb_components	A map of objects with each object representing an image builder component to create. If specifying the data attribute, this should be in the form of a relative path to the root module i.e. data/component1.yaml and is mutually exclusive with uri.	map(object({ data = optional(string) uri = optional(string) platform = string version = string description = optional(string) change_description = optional(string) kms_key_id = optional(string) supported_os_versions = optional(set(string)) tags = optional(map(string)) parameters = optional(list(object({ name = string value = list(string) }))) order = optional(number) }))	{}	no
imgb_create_image_now	WARNING significantly increased TF deployment times. A boolean to determine whether or not to create an image at the time of running Terraform in addition to any automated schedule configured.	bool	false	no
imgb_custom_iam_role	A string representing the ARN of a custom IAM role to use in place of one created by this module. Leave default to use the module-created resource.	string	""	no
imgb_custom_instance_profile	A string representing the ARN of a custom instance profile to use in place of one created by this module. Leave default to use the module-created resource.	string	""	no
imgb_custom_policy	A string containing the full custom policy to apply to the role in addition to the managed policies. Leave default to forgo creation of the custom IAM policy resource.	string	""	no
imgb_image_timeout	String representation of a duration i.e. 60m for 60 minutes or 2h for 2 hours, for Terraform to wait for the image to be built, tested, and distributed.	string	null	no
imgb_managed_policies	A set of managed IAM policy ARNs to attach to the image builder instances. This should include EC2InstanceProfileForImageBuilder, EC2InstanceProfileForImageBuilderECRContainerBuilds, AmazonSSMManagedInstanceCore at a minimum.	set(string)	[ "arn:aws:iam::aws:policy/EC2InstanceProfileForImageBuilder", "arn:aws:iam::aws:policy/EC2InstanceProfileForImageBuilderECRContainerBuilds", "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore" ]	no
imgb_stackname	The name for the image builder stack. This is used for naming the resources deployed by this module.	string	n/a	yes
imgdistcfg_description	A description for the EC2 image builder distribution configuration.	string	null	no
imgdistcfg_distribution	A list of AMI distribution configuration objects for the corresponding resource. Defaults to single-AMI output in same region. Custom AMI names MUST contain the AWS variable {{imagebuilder:buildDate}}.	list(object( { region = string license_configuration_arns = optional(set(string)) ami_dist_cfg = optional(object({ ami_tags = optional(map(string)) description = optional(string) kms_key_id = optional(string) name = optional(string) target_account_ids = optional(set(string)) launch_permission = optional(object({ user_groups = optional(set(string)) user_ids = optional(set(string)) organization_arns = optional(set(string)) organizational_unit_arns = optional(set(string)) })) })) container_dist_cfg = optional(object({ container_tags = optional(set(string)) description = optional(string) target_repo = object({ repository_name = string service = string }) })) launch_template_cfg = optional(object({ default = optional(bool) launch_template_id = string account_id = optional(string) })) }))	[ { "ami_dist_cfg": { "name": "{{imagebuilder:buildDate}}" }, "region": "us-east-1" } ]	no
imgdistcfg_kms_arn	The ARN of a KMS key used to encrypt the distribution configuration.	string	null	no
imgdistcfg_license_config_arns	A set of License Manager License Configuration ARNs for use with the image builder distribution configuration.	set(string)	null	no
imgdistcfg_tags	A map of key-value pairs to override the default tags on the distribution configuration.	map(string)	null	no
imginfracfg_description	A description for the EC2 image builder infrastructure configuration.	string	null	no
imginfracfg_instance_types	A set of EC2 instance types to use for building the image.	set(string)	null	no
imginfracfg_keypair	The name of an EC2 key pair in order to connect to image builder worker instances. Leave default for no key pairs - SSM Session Manager can still be used if available.	string	null	no
imginfracfg_logging	A set of objects containing logging options for the infrastructure configuration. Leave default for no logging.	set(object({ s3_logs = object({ s3_bucket_name = string s3_key_prefix = optional(string) }) }))	[]	no
imginfracfg_sg_ids	A set of EC2 security group identifiers to attach to image builder worker instances. Leave default to use the default security group.	set(string)	null	no
imginfracfg_sns_topic_arn	The ARN of an SNS topic for the infrastructure configuration.	string	null	no
imginfracfg_subnet_id	The EC2 subnet identifier to use during building and testing. WARNING You must also set imginfracfg_sg_ids so the instance has security groups attached.	string	null	no
imginfracfg_tags	A map of key-value pairs to override the default tags on the infrastructure configuration.	map(string)	null	no
imginfracfg_term_on_fail	Terminate EC2 instance on build failure - True will terminate on failure and False will retain the instance. Defaults to True.	bool	true	no
imgpipe_EIM_enabled	Enable or disable Enhanced Image Metadata.	bool	true	no
imgpipe_description	A description for the EC2 image builder pipeline.	string	null	no
imgpipe_schedule	The cron schedule, timezone, and pipeline execution start condition object. Leave default for manual running of the pipeline. Default timezone parameter = UTC	set(object({ schedule_expression = string pipeline_execution_start_condition = optional(string) timezone = optional(string) }))	[]	no
imgpipe_status	Enable or disable the image builder pipeline.	string	"ENABLED"	no
imgpipe_tags	A map of key-value pairs to override the default tags on the image pipeline.	map(string)	null	no
imgpipe_tests_enabled	Enable or disable image tests. True will enable tests, False will disable tests.	bool	true	no
imgpipe_timeout_mins	The maximum threshold in minutes for the image testing to timeout and fail. Must be between 60 and 1440 (1 and 24 hours).	number	720	no
imgrep_block_device_maps	A list of block device mappings to apply when creating images. Defaults to no additional block devices.	list(object({ device_name = optional(string) no_device = optional(string) virtual_name = optional(string) ebs = object({ delete_on_termination = optional(bool) encrypted = optional(bool) iops = optional(number) kms_key_id = optional(string) snapshot_id = optional(string) throughput = optional(number) volume_size = optional(number) volume_type = optional(string) }) }))	null	no
imgrep_description	Enter a description for the image recipe.	string	null	no
imgrep_parent_img	The parent image of this image recipe; either the ARN of the base image or an AMI ID. Version in the image ARN can be included or wildcarded.	string	n/a	yes
imgrep_sysmanager_uninstall	Whether to remove the Systems Manager Agent after the image has been built.	bool	false	no
imgrep_tags	A map of key-value pairs to override the default tags on the image recipe.	map(string)	null	no
imgrep_user_data	Base64-encoded user data to provide commands when launching your build instance.	string	null	no
imgrep_version	The semantic version of the image recipe. Defaults to 1.0.0 but any suitable semantic version is accepted.	string	"1.0.0"	no
imgrep_working_dir	The working directory to use for build and test workflows.	string	null	no
region	The region to create the resources from this module.	string	"us-east-1"	no

Outputs

Name	Description
builder_info	n/a
component_info	n/a
distribution_info	n/a
image_info	n/a
pipeline_info	n/a