Using Custom AMIs
Important
The AWS OpsWorks Stacks service reached end of life on May 26, 2024 and has been disabled for both new and existing customers.
We strongly recommend customers migrate their workloads to other solutions as soon as possible. If you have questions about migration, reach out to the AWS Support Team on AWS re:Post
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 about 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. While it might
be possible to create instances with other operating systems (such as CentOS
6.x) that have been created from custom or community-generated AMIs,
these are not officially supported.
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.
Note
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 options:
-
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.
Before you create a custom Linux AMI, disable noexec
on the
/tmp
partition to allow AWS OpsWorks Stacks to install its agent on custom
Linux instances.
Note
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?
Topics
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
-
Create an instance by using a 64-bit version of one of the AWS OpsWorks Stacks-supported AMIs.
-
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.
-
Stop the instance and create a custom AMI.
Create a Custom Linux AMI from an AWS OpsWorks Stacks Instance
To use a customized AWS OpsWorks Stacks Linux instance to create an AMI, 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 includes that identity, and all instances based on the AMI 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
-
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.
-
Edit the layers and disable AutoHealing.
-
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.
-
When the instance is online, log in with SSH, and perform one of the next four steps, depending upon your instance operating system.
-
For an Amazon Linux instance in either a Chef 11 or Chef 12 stack, or a Red Hat Enterprise Linux 7 instance in a Chef 11 stack, do the following.
-
sudo /etc/init.d/monit stop
-
sudo /etc/init.d/opsworks-agent stop
-
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
-
-
sudo rpm -e opsworks-agent-ruby
-
sudo rpm -e chef
-
-
For an Ubuntu 16.04 LTS or 18.04 LTS instance in a Chef 12 stack, do the following.
-
sudo systemctl stop opsworks-agent
-
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
-
sudo apt-get -y remove chef
-
sudo dpkg -r opsworks-agent-ruby
-
systemctl stop apt-daily.timer
-
systemctl stop apt-daily-upgrade.timer
-
rm /var/lib/systemd/timers/stamp-apt-daily.timer
-
rm /var/lib/systemd/timers/stamp-apt-daily-upgrade.timer
-
-
For other supported Ubuntu versions in a Chef 12 stack, do the following.
-
sudo /etc/init.d/monit stop
-
sudo /etc/init.d/opsworks-agent stop
-
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
-
sudo apt-get -y remove chef
-
sudo dpkg -r opsworks-agent-ruby
-
-
For a Red Hat Enterprise Linux 7 instance in a Chef 12 stack, do the following.
-
sudo systemctl stop opsworks-agent
-
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 /var/chef
-
sudo rpm -e opsworks-agent-ruby
-
sudo rpm -e chef
-
-
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 defaultec2-bundle-vol
command handles this task.
-
-
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 2022 Base. You can choose other Windows Server operating systems in the Amazon EC2 management console.
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).
Topics
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
-
In the Amazon EC2 console, choose Launch Instance.
-
Find Microsoft Windows Server 2022 Base, and then choose Select.
-
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.
-
After the instance boot process finishes, get your password, and then connect to the instance in a Windows Remote Desktop Connection window.
-
On the Windows Start screen, choose Start, and then begin typing
ec2configservice
until the results show the EC2ConfigServiceSettings console. Open the console. -
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. -
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. -
Choose Apply, and then choose Shutdown with Sysprep. When you are prompted to confirm, choose Yes.
-
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.
-
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.
-
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
-
In the Amazon EC2 console, choose Launch Instance.
-
Find Microsoft Windows Server 2022 Base, and then choose Select.
-
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.
-
After the instance boot process finishes, get your password, and then connect to the instance in a Windows Remote Desktop Connection window.
-
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
toEnabled
-
Ec2HandleUserData
toEnabled
-
-
Disconnect from the Remote Desktop session, and return to the Amazon EC2 console.
-
In the Instances list, stop the instance.
-
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.
-
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.
-
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
-
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.
-
On the New tab, choose Advanced.
-
On the Operating system drop-down list, choose Use custom Windows AMI.
-
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.