Skip to content

aws-ia/terraform-aws-ec2-image-builder

Repository files navigation

AWS EC2 Image Builder Module

This terraform module can be used to deploy AWS EC2 Image Builder.

✅ Deployment examples can be found under examples folder.

✅ AWS EC2 image builder documentation for more details about AWS EC2 Image Builder

AWS EC2 Image Builder Architecture

Resources provisioned by the EC2 Image Builder Terraform Module{ width=100% }

Usage

The example below builds an EC2 Image using EC2 Image Builder in an existing VPC and Subnets. EC2 Image Builder simplifies the building, testing, and deployment of Virtual Machine and container images for use on AWS or on-premises. EC2 Image Builder supporting resources EC2 Key Pair, IAM role and Security groups are created by this module by default. This module allows you to bring your own EC2 Key Pair, additional IAM Policy and Security group.

The following is a basic example, see examples folder for more complete examples:

module "ec2-image-builder" {
  source                = "aws-ia/ec2-image-builder/aws"
  name                = "basic-ec2-image"
  vpc_id              = "<ENTER_VPC_ID>"
  subnet_id           = "<ENTER_SUBNET_ID>"
  aws_region          = "<ENTER_AWS_REGION>"
  source_cidr         = ["<ENTER your IP here to access EC2 Image Builder Instances through RDP or SSH>"]
  create_security_group = true
  create_key_pair     = true
  instance_types      = ["c5.large"]
  source_ami_name     = "<ENTER_SOURCE_AMI_NAME>" # e.g.: "Windows_Server-2022-English-Core-Base-*"
  ami_name            = "<ENTER_AMI_NAME>" # e.g.: "Windows 2022 core AMI"
  ami_description     = "<ENTER_AMI_DESCRIPTION>" # e.g.:  "Windows 2022 core AMI provided by AWS"
  recipe_version      = "0.0.1"
  build_component_arn = ["<ENTER_LIST_OF_BUILD_ARNS>"] # e.g.:  arn:aws:imagebuilder:ap-southeast-2:XXXXXXXXXXX:component/win2022build/0.0.1/1
  test_component_arn  = ["<ENTER_LIST_OF_TEST_ARNS>"] # e.g.: arn:aws:imagebuilder:ap-southeast-2:XXXXXXXXXXXX:component/win2022test/0.0.1/1
  s3_bucket_name      = "<ENTER_S3_BUCKET_NAME>"
  custom_policy_arn   = "<ENTER_CUSTOM_POLICY_ARN>"
  platform            = "<Windows or Linux>"
  tags                = "<ENTER_A_MAP_OF_RESOURCE_TAGS_TO_ASSOCIATE_WITH_THE_RESOURCES>"

  managed_components = "<ENTER_LIST OF AWS MANAGED COMPONENTS>"
  # e.g.:
  #managed_components = [{
  #  name    = "powershell-windows",
  #  version = "7.2.10"
  #  },
  #  {
  #    name    = "chocolatey",
  #    version = "1.0.0"
  #}]

  target_account_ids = [
    "<ENTER TARGET AWS ACCOUNT IDS.>"
  ]

  ami_regions_kms_key = {
    "<ENTER AWS REGIONS TO SHARE THE AMI WITH>" = "<ENTER KMS KEYs TO ENCRYPT AMIs ON THE TARGET REGION>",
    "us-west-2"      = "arn:aws:kms:us-west-2:XXXXXXX:key/mrk-XXXXXX",
    "us-east-1"      = "arn:aws:kms:us-east-1:XXXXXX:key/mrk-XXXX",
  }

}

Security

See CONTRIBUTING for more information.

License

Apache-2.0 Licensed. See LICENSE.

Requirements

Name Version
terraform >= 1.0.7
aws >= 4.0.0, < 5.0.0
awscc >= 0.24.0

Providers

Name Version
aws >= 4.0.0, < 5.0.0

Modules

No modules.

Resources

Name Type
aws_iam_instance_profile.iam_instance_profile resource
aws_iam_role.awsserviceroleforimagebuilder resource
aws_iam_role_policy.aws_policy resource
aws_iam_role_policy_attachment.custom_policy resource
aws_iam_role_policy_attachment.imagebuilder resource
aws_iam_role_policy_attachment.ssm resource
aws_imagebuilder_distribution_configuration.imagebuilder_distribution_configuration resource
aws_imagebuilder_image.imagebuilder_image resource
aws_imagebuilder_image_pipeline.imagebuilder_image_pipeline resource
aws_imagebuilder_image_recipe.imagebuilder_image_recipe resource
aws_imagebuilder_infrastructure_configuration.imagebuilder_infrastructure_configuration resource
aws_security_group.security_group resource
aws_security_group_rule.sg_https_ingress resource
aws_security_group_rule.sg_internet_egress resource
aws_security_group_rule.sg_rdp_ingress resource
aws_ami.source_ami data source
aws_iam_policy_document.assume data source
aws_iam_policy_document.aws_policy data source
aws_imagebuilder_components.managed_components data source
aws_vpc.selected data source

Inputs

Name Description Type Default Required
ami_description (Required) Choose a description for the AMI string n/a yes
ami_name (Required) Choose a name for the AMI string n/a yes
aws_region (Required) AWS Region to deploy the resources string n/a yes
name (Required) Choose a name for the project which will be the prefix for every resource string n/a yes
platform (Required) OS: Windows or Linux string n/a yes
source_ami_name (Required) Source AMI name, e.g: Windows_Server-2022-English-Core-Base-* string n/a yes
subnet_id (Required) Subnet ID to deploy the EC2 Image Builder Environment. string n/a yes
vpc_id (Required) VPC ID to deploy the EC2 Image Builder Environment. string n/a yes
ami_regions_kms_key (Optional) A list of AWS Regions to share the AMI with and also target KMS Key in each region map(string) {} no
attach_custom_policy (Required) Attach custom policy to the EC2 Instance Profile, if true, ARN of the custom policy needs to be specified on the variable custom_policy_arn bool false no
build_component_arn (Required) List of ARNs for the Build EC2 Image Builder Build Components list(string) [] no
create_security_group (Optional) Create security group for EC2 Image Builder instances. Please note this security group will be created with default egress rule to 0.0.0.0/0 CIDR Block. In case you want to have a more restrict set of rules, please provide your own security group id on security_group_ids variable bool true no
custom_policy_arn (Optional) ARN of the custom policy to be attached to the EC2 Instance Profile string null no
imagebuilder_image_recipe_kms_key_arn (Required) KMS Key ARN(CMK) for encrypting Imagebuilder Image Recipe Block Device Mapping string null no
instance_key_pair (Optional) EC2 key pair to add to the default user on the builder(In case existent EC2 Key Pair is provided) string null no
instance_types (Optional) Instance type for the EC2 Image Builder Instances.
Will be set by default to c5.large. Please check the AWS Pricing for more information about the instance types.
list(string)
[
"c5.large"
]
no
managed_components (Optional) Specify the name and version of the AWS managed components that are going to be part of the image recipe
list(object({
name = string,
version = string
}))
[] no
recipe_version (Required) The semantic version of the image recipe. This version follows the semantic version syntax. e.g.: 0.0.1 string "0.0.1" no
recipe_volume_size (Optional) Volume Size of Imagebuilder Image Recipe Block Device Mapping string 100 no
recipe_volume_type (Optional) Volume Type of Imagebuilder Image Recipe Block Device Mapping string "gp3" no
s3_bucket_name (Required) S3 Bucket Name which will store EC2 Image Builder TOE logs and is storing the build/test YAML files string "" no
schedule_expression "(Optional) pipeline_execution_start_condition = The condition configures when the pipeline should trigger a new image build.
Valid Values: EXPRESSION_MATCH_ONLY | EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE
scheduleExpression = The cron expression determines how often EC2 Image Builder evaluates your pipelineExecutionStartCondition.
e.g.: "cron(0 0 * * ? *)"
list(object({
pipeline_execution_start_condition = string,
scheduleExpression = string
}))
[] no
security_group_ids (Optional) Security group IDs for EC2 Image Builder instances(In case existent Security Group is provided) list(string) [] no
source_ami_owner (Optional) Owner of the AMI , default: amazon string "amazon" no
source_cidr (Required) Source CIDR block which will be allowed to RDP or SSH to EC2 Image Builder Instances list(string) [] no
tags (Optional) A map of resource tags to associate with the resource map(string) {} no
target_account_ids (Optional) A list of target accounts to share the AMI with list(string) [] no
terminate_on_failure (Optional) Change to false if you want to connect to a builder for debugging after failure bool true no
test_component_arn (Required) List of ARNs for the Build EC2 Image Builder Test Components list(string) [] no
timeout (Optional) Number of hours before image time out. Defaults to 2h. string "2h" no

Outputs

Name Description
ami AMI created by Terraform