This post was written by Anoop Rachamadugu – AWS Cloud Architect.

The EC2 Image Builder service helps users to build and maintain server images to use with Amazon EC2 and on-premises using automated build pipelines. As new images are created by the pipelines, you can configure automated tests to validate the image, before distributing it to your production workloads. You can use a combination of AWS-provided tests and custom tests that you have authored yourself to validate the image.

In this blog post, I walk through how you can test an EC2 Image Builder pipeline using Chef InSpec. Chef InSpec is an open-source framework for testing and auditing your applications and infrastructure. Chef InSpec works by comparing the actual state of your system with the desired state that you write in Chef InSpec code. Chef InSpec then generates the findings in a report. I configure the image builder pipeline to either progress or fail based on the results of the report.


The solution in this blog comprises of an EC2 Image Builder document that is completed during the test stage of an Image Builder pipeline. This document downloads the Chef InSpec installer from Amazon S3 and installs it. It then downloads the test cases from Amazon S3 and performs the tests. After running the test cases, it returns the exit code of the process and uploads the test report to Amazon S3. The Image Builder pipeline either progresses or fails based on the value of the exit code.

I use Windows Server 2016 as the target operating system. The Chef InSpec installer and test cases are already uploaded to Amazon S3 for this walk through. The following image represents this flow.

Image Builder Testing Activities


To get started with this solution, you need the following:

  • Download the Chef InSpec installer and upload it to a S3 bucket. I use version 4.23.4 of the installer for Windows Server 2016
  • An EC2 Image Builder pipeline with an IAM role configured that provides permissions for the following functions:
    • Download the Chef InSpec installer and test cases from an S3 bucket
    • Upload the test results to an S3 bucket
  • The solution consists of two files, which can be downloaded from the amazon-ec2-image-builder Github repository

Chef InSpec test cases

For the purpose of this blog, I use the “inspec-test-cases.rb” file that contains the test cases to complete on the server. With the following code, I am testing to determine if the AWS Systems Manager Agent (SSM Agent) is installed on the server and the service is in a running state.

Image 1

This “inspec-test-cases.rb” file is already uploaded to an Amazon S3 bucket. The S3 bucket location is later referenced in the Chef InSpec document.

Creating the Chef InSpec document

The EC2 Image Builder document is carried out during the test stage of an Image Builder pipeline. The first section of the inspec-test-windows-component.yml document specifies the name and description to describe the document’s purpose and a schemaVersion.

Image 2

The first step is to create a working directory on the server. You do this by using the CreateFolder command.

Image 3

Then, use the S3Download command to download the installer from Amazon S3 and store it in the InSpec working directory created in the previous step. Replace <S3_PATH_TO_INSPEC_INSTALLER.MSI> with the location where the InSpec installer resides on Amazon S3.

Image 4

After downloading the installer, use the ExecutePowerShell action to install InSpec on the server.

Image 5

After installing InSpec on the server, download the InSpec test cases “inspec-test-cases.rb” from Amazon S3 using the S3Download action to the working directory. Replace <S3_PATH_TO_INSPEC_TEST.RB> with the location where the InSpec tests resides on Amazon S3.

Image 6

After completing those steps, you have installed InSpec and downloaded the test cases on the server. The final step of the document is to perform the tests. You do this using the ExecutePowerShell command. First, launch InSpec as a process and accept the chef license agreement.

The InSpec report generates as an HTML file and then uploads to Amazon S3. Replace <S3_BUCKET_NAME_REPORT_OUTPUT> with the name of the Amazon S3 bucket where the report should be uploaded to. The final step involves returning the exit code from the InSpec process. The image builder pipeline either progresses further or fails based on the return code.

Image 7

Now, I create a document that downloads the Chef InSpec, completes test cases, and uploads the results to Amazon S3.

Next, I use this document to create a component in Image Builder and select the test component in the image recipe. The image recipe can then be used when creating an image pipeline. The blog post Automate OS Image Build Pipelines with EC2 Image Builder provides a tutorial demonstrating how to create an image pipeline with the EC2 Image Builder console. For more information, review Getting started with EC2 Image Builder.

After the successful completion of the image builder pipeline, the InSpec test report can be downloaded from the Amazon S3 location specified in the document. Here’s a sample output of the test results where all the InSpec tests have passed.

RSpec Code Examples


In this blog post, I walked through how you can test an image builder pipeline using  InSpec to determine if the Amazon SSM Agent is installed and running on the server. I reviewed the steps in the document to install and run InSpec on the server. I also note the sample InSpec tests that are run on the server and the report generated.

The amazon-ec2-image-builder-samples GitHub repository provides a number of examples for getting started with EC2 Image Builder. AWS continues to use this repository for publishing sample content. We hope Image Builder is providing value and making it easier for you to build virtual machine (VM) images.