AWS OpsWorks
User Guide (API Version 2013-02-18)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Using Custom AMIs

AWS OpsWorks supports two ways to customize instances: custom Amazon Machine Images (AMIs) and custom Chef recipes. Both approaches give you control over which packages and package versions are installed, how they are configured, and so on. However, each approach has different advantages, so the best one depends on your requirements.

The following are the primary reasons to consider using a custom AMI:

  • You want to pre-bundle specific packages instead of installing them after the instance boots.

  • You want to control the timing of package updates to provide a consistent base image for your layer.

  • You want instances—load-based instances in particular—to boot as quickly as possible.

Chef recipes are more flexible than custom AMIs, easier to update, and can perform updates on running instances. In practice, the optimal solution might be a combination of both approaches. For more information on custom recipes, see Cookbooks and Recipes and Customizing AWS OpsWorks.


You cannot use a custom AMI as a stack's default operating system. You can specify custom AMIs only when you add new instances to layers. For more information, see Adding an Instance to a Layer and Create a New Stack.

To use a custom AMI with AWS OpsWorks, you must first create an AMI from a customized instance. You can choose from two basic approaches:

  • Use the Amazon EC2 console or API to create and customize an instance, based on one of the AWS OpsWorks-supported AMIs: Amazon Linux or Ubuntu 12.04 LTS.

  • Use OpsWorks to create an Amazon EC2 instance, based on the configuration of its associated layers.

You then use the Amazon EC2 console or API to create a custom AMI from the customized instance. You can use your custom AMIs in any stack that is in the same region by adding an instance to a layer and specifying your custom AMI. For more information on how to create an instance that uses a custom AMI, see Adding an Instance to a Layer.


By default, AWS OpsWorks installs all Amazon Linux updates on boot, which provides you with the latest release. In addition, Amazon Linux releases a new version approximately every six months, which can involve significant changes. To defer updating to a new version, you can lock your custom AMI to a specified version. For more information on how to lock an AMI, see the Amazon Linux FAQ. For more information about Amazon Linux and AWS OpsWorks, see Operating Systems.

The simplest way to create a custom AMI is to perform the entire task by using the Amazon EC2 console or API. For more details about the following steps, see Creating Your Own AMIs.

To create a custom AMI using Amazon EC2 console or API

  1. Create an instance by using one of the following AMIs: Amazon Linux or Ubuntu 12.04 LTS.

  2. Customize the instance from Step 1 by configuring it, installing packages, and so on. Remember that everything you install will be reproduced on every instance based on the AMI, so don’t include items that should be specific to a particular instance.

  3. Stop the instance and create a custom AMI.

If you want to use a customized AWS OpsWorks instance to create an AMI, you should be aware that every Amazon EC2 instance created by OpsWorks includes a unique identity. If you create a custom AMI from such an instance, it will include that identity and all instances based on the AMI will have the same identity. To ensure that the instances based on your custom AMI have a unique identity, you must remove the identity from the customized instance before creating the AMI.

To create a custom AMI from an AWS OpsWorks instance

  1. Create a stack and add one or more layers to define the configuration of the customized instance. You can use built-in layers, customized as appropriate, as well as fully custom layers. For more information, see Customizing AWS OpsWorks.

  2. Edit the layers and disable AutoHealing.

  3. Add an instance to the layer or layers and start it. We recommend using an Amazon EBS-backed instance. Open the instance's details page and record its Amazon EC2 ID for later.

  4. When the instance is online, connect to it with SSH and run the following commands, in order:

    1. sudo /etc/init.d/monit stop

    2. sudo /etc/init.d/opsworks-agent stop

    3. sudo rm -rf /etc/aws/opsworks/ /opt/aws/opsworks/ /var/log/aws/opsworks/ /var/lib/aws/opsworks/ /etc/monit.d/opsworks-agent.monitrc /etc/monit/conf.d/opsworks-agent.monitrc /var/lib/cloud/

  5. This step depends on the instance type:

    • For an Amazon EBS-backed instance, use the AWS OpsWorks console to stop the instance and create the AMI as described in Creating an Amazon EBS-Backed Linux AMI..

    • For an instance store-backed instance, create the AMI as described in Creating an Instance Store-Backed Linux AMI and then use the AWS OpsWorks console to stop the instance.

      When you create the AMI, be sure to include the certificate files. For example, you can call the ec2-bundle-vol command with the -i argument set to -i $(find /etc /usr /opt -name '*.pem' -o -name '*.crt' -o -name '*.gpg' | tr '\n' ',').

  6. Clean up your stack by returning to the AWS OpsWorks console and deleting the instance from the stack.