Menu
AWS OpsWorks
User Guide (API Version 2013-02-18)

Using Custom AMIs

AWS OpsWorks Stacks supports two ways to customize instances: custom Amazon Machine Images (AMIs) and 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 prebundle 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.

The following are the primary reasons to consider using Chef recipes:

  • They are more flexible than custom AMIs.

  • They are easier to update.

  • They can perform updates on running instances.

In practice, the optimal solution might be a combination of both approaches. For more information on recipes, see Cookbooks and Recipes.

How Custom AMIs work with AWS OpsWorks Stacks

To specify a custom AMI for your instances, select Use custom AMI as the instance's operating system when you create a new instance. AWS OpsWorks Stacks then displays a list of the custom AMIs in the stack's region and you select the appropriate one from the list. For more information, see Adding an Instance to a Layer.

Note

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

This topic discusses some general issues that you should consider before creating or using a custom AMI.

Startup Behavior

When you start the instance, AWS OpsWorks Stacks uses the specified custom AMI to launch a new Amazon EC2 instance. AWS OpsWorks Stacks then uses cloud-init to install the AWS OpsWorks Stacks agent on the instance and the agent runs the instance's Setup recipes followed by the Deploy recipes. After the instance is online, the agent runs the Configure recipes for every instance in the stack, including the newly added instance.

Choosing a Layer

The AWS OpsWorks Stacks agent usually does not conflict with installed packages. However, the instance must be a member of at least one layer. AWS OpsWorks Stacks always runs that layer's recipes, which could cause problems. You should understand exactly what a layer's recipes do to an instance before adding an instance with a custom AMI to that layer.

To see which recipes a particular layer type runs on your instance, open a stack that includes that layer. Then click Layers in the navigation pane, and click Recipes for the layer of interest. To see the actual code, click the recipe name.

Tip

For Linux AMIs, one way to reduce the possibility of conflicts is to use AWS OpsWorks Stacks to provision and configure the instance that is the basis for your custom AMI. For more information, see Create a Custom Linux AMI from an AWS OpsWorks Stacks Instance.

Handling Applications

In addition to packages, you might also want to include an application in the AMI. If you have a large complex application, including it in the AMI can shorten the instance's startup time. You can include small applications in your AMI, but there is usually little or no time advantage relative to having AWS OpsWorks Stacks deploy the application.

One option is to include the application in your AMI and also create an app that deploys the application to the instances from a repository. This approach shortens your boot time but also provides a convenient way to update the application after the instance is running. Note that Chef recipes are idempotent, so the deployment recipes won't modify the application as long as the version in the repository is the same as the one on the instance.

Creating a Custom AMI for AWS OpsWorks Stacks

To use a custom AMI with AWS OpsWorks Stacks, 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 a 64-bit version of one of the AWS OpsWorks Stacks-supported AMIs.

  • For Linux AMIs, use OpsWorks to create an Amazon EC2 instance, based on the configuration of its associated layers.

Tip

Be aware that an AMI might not work with all instance types, so make sure that your starting AMI is compatible with the instance types that you plan to use. In particular, the R3 instance types require a hardware-assisted virtualization (HVM) AMI.

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.

Note

By default, AWS OpsWorks Stacks 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. By default, custom AMIs based on Amazon Linux are automatically updated to the new version when it is released. The recommended practice is to lock your custom AMI to a specific Amazon Linux version, which allows you to defer the update until you have tested the new version. For more information, see How do I lock my AMI to a specific version?.

Create a Custom AMI using Amazon EC2

The simplest way to create a custom AMI—and the only option for Windows AMIs—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 a 64-bit version of one of the AWS OpsWorks Stacks-supported AMIs.

  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.

Create a Custom Linux AMI from an AWS OpsWorks Stacks Instance

If you want to use a customized AWS OpsWorks Stacks Linux 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 Stacks instance

  1. Create a Linux 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 Stacks.

  2. Edit the layers and disable AutoHealing.

  3. Add an instance with your preferred Linux distribution 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, log in with SSH, and run the following commands, in order, depending upon your instance operating system.

    For an Amazon Linux instance in either a Chef 11 or Chef 12 stack

    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/ /etc/chef

      Note

      For instances in a Chef 12 stack, add the following two folders to this command:

      • /var/chef

      • /opt/chef

    4. sudo rpm -e opsworks-agent-ruby

    5. sudo rpm -e chef

    For an Ubuntu 16.04 LTS instance in a Chef 12 stack

    1. sudo systemctl stop opsworks-agent

    2. 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/ /var/chef /opt/chef /etc/chef

    3. sudo apt-get -y remove chef

    4. sudo dpkg -r opsworks-agent-ruby

    For other supported Ubuntu versions in a Chef 12 stack

    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/ /var/chef /opt/chef /etc/chef

    4. sudo apt-get -y remove chef

    5. sudo dpkg -r opsworks-agent-ruby

  5. This step depends on the instance type:

    • For an Amazon EBS-backed instance, use the AWS OpsWorks Stacks 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 Stacks 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' ','). Do not remove the apt public keys when bundling. The default ec2-bundle-vol command handles this task.

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

Create a Custom Windows AMI

The following procedures create custom AMIs for Windows Server 2012 R2. You can choose other Windows Server operating systems in the Amazon EC2 management console; the oldest available release of Windows Server is Windows Server 2003 R2.

Important

Currently, the AWS OpsWorks Stacks agent cannot be installed on—and AWS OpsWorks Stacks cannot manage—Windows-based instances that use a system UI language other than English - United States (en-US).

Creating a Custom Windows AMI with Sysprep

Creating custom Windows AMIs by using Sysprep typically results in a slower instance launch, but a cleaner process. The first-time startup of an instance created from an image created with Sysprep takes more time because of Sysprep activities, restarts, AWS OpsWorks Stacks provisioning, and the first AWS OpsWorks Stacks run, including setup and configuration. Complete the steps for creating a custom Windows AMI in the Amazon EC2 console.

To create a custom Windows AMI with Sysprep

  1. In the Amazon EC2 console, choose Launch Instance.

  2. Find Microsoft Windows Server 2012 R2 Base, and then choose Select.

  3. Choose the instance type that you want, and then choose Configure Instance Details. Make configuration changes to the AMI, including machine name, storage, and security group settings. Choose Launch.

  4. After the instance boot process finishes, get your password, and then connect to the instance in a Windows Remote Desktop Connection window.

  5. On the Windows Start screen, choose Start, and then begin typing ec2configservice until the results show the EC2ConfigServiceSettings console. Open the console.

  6. On the General tab, make sure that the Enable UserData execution check box is filled (although this option is not required for Sysprep, it is required for AWS OpsWorks Stacks to install its agent). Clear the check box for the Set the computer name of the instance... option, because this option can cause a restart loop with AWS OpsWorks Stacks.

  7. On the Image tab, set Administrator Password to either Random to allow Amazon EC2 to automatically generate a password that you can retrieve with an SSH key, or Specify to specify your own password. Sysprep saves this setting. If you specify your own password, store the password in a convenient place. We recommend that you do not choose Keep Existing.

  8. Choose Apply, and then choose Shutdown with Sysprep. When you are prompted to confirm, choose Yes.

  9. After the instance has stopped, in the Amazon EC2 console, right-click the instance in the Instances list, choose Image, and then choose Create Image.

  10. On the Create Image page, provide a name and description for the image, and specify the volume configuration. When you have finished, choose Create Image.

  11. Open the Images page, and wait for your image to change from the pending stage to available. Your new AMI is ready to use.

Creating a Custom Windows AMI Without Sysprep

Complete the steps for creating a custom Windows AMI in the Amazon EC2 console.

To create a custom Windows AMI without Sysprep

  1. In the Amazon EC2 console, choose Launch Instance.

  2. Find Microsoft Windows Server 2012 R2 Base, and then choose Select.

  3. Choose the instance type that you want, and then choose Configure Instance Details. Make configuration changes to the AMI, including machine name, storage, and security group settings. Choose Launch.

  4. After the instance boot process finishes, get your password, and then connect to the instance in a Windows Remote Desktop Connection window.

  5. On the instance, open C:\Program Files\Amazon\Ec2ConfigService\Settings\config.xml, change the following two settings, and then save and close the file:

    • Ec2SetPassword to Enabled

    • Ec2HandleUserData to Enabled

  6. Disconnect from the Remote Desktop session, and return to the Amazon EC2 console.

  7. In the Instances list, stop the instance.

  8. After the instance has stopped, in the Amazon EC2 console, right-click the instance in the Instances list, choose Image, and then choose Create Image.

  9. On the Create Image page, provide a name and description for the image, and specify the volume configuration. When you have finished, choose Create Image.

  10. Open the Images page, and wait for your image to change from the pending stage to available. Your new AMI is ready to use.

Adding a New Instance by Using a Custom Windows AMI

After your image changes to the available state, you can create new instances that are based on your custom Windows AMI. When you choose Use custom Windows AMI from the Operating system list, AWS OpsWorks Stacks displays a list of custom AMIs.

To add a new instance based on a custom Windows AMI

  1. When your new AMI is available, go to the AWS OpsWorks Stacks console, open the Instances page for a Windows stack, and choose + Instance near the bottom of the page to add a new instance.

  2. On the New tab, choose Advanced.

  3. On the Operating system drop-down list, choose Use custom Windows AMI.

  4. On the Custom AMI drop-down list, choose the AMI that you created, and then choose Add Instance.

You can now start and run the instance.