Skip to content

Latest commit

 

History

History
185 lines (159 loc) · 16.2 KB

README.md

File metadata and controls

185 lines (159 loc) · 16.2 KB
Raw

terraform-aws-imagebuilder-pipeline

tflint tfsec yamllint misspell pre-commit-check follow on Twitter

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