Walkthrough – Custom AWS AMI creation with Aminator
29. July 2014

Used Software

  • python
  • python-boto (https://github.com/boto/boto)
  • aminator (https://github.com/Netflix/aminator)

How It Works

  1. Choose existing AMI (depending on your requirements) as the base-image to customize
  2. Prepare your application with all it’s dependencies in a rpm/deb package
  3. Let Amimator create your ready-to-run AMI based on the choosen base-ami and your applications rpm

At netflix they manually create a so called “federation ami”, containing basic configuration for all machines deployed at neflix (if I got it right). This would be step 1.5 if you want to and might be a good idea in some environments. Read the documentation for further information: https://github.com/Netflix/aminator/wiki


Install base requirements:

sudo yum install python python-pip python-boto git

Install Aminator:

sudo pip install git+https://github.com/Netflix/aminator.git#egg=aminator


Config Push

If you use a built-in AMI, Amazon-Linux f.e. you need to ensure that it is configured properly without ever been booted in reality. This means that it never got the amazon contextualization, configuring available yum repos and so on. Another point is that you might want to deploy your own repo configuration to customize your AMI with own rpm/deb packages.

This can be done by writing a very simple plugin, overwriting the default_conf plugin for your distribution. This can be found here: https://github.com/Netflix/aminator/tree/6d2b0a7f34978fd77b906bb24f4056eeea779c9e/aminator/plugins/distro/default_conf

For RHEL bases systems create the following file: /etc/aminator/plugins/aminator.plugins.distro.redhat.yml (the name matches the one in default_conf to overwrite it)

enabled: true

short_circuit: true
  - /sbin/service

# fstab-esque list of mounts for a chroot environment. ordered.
# # [device, type, mount point, options]
    - [proc, proc, /proc, null]
    - [sysfs, sysfs, /sys, null]
    - [/dev, bind, /dev, null]
    - [devpts, devpts, /dev/pts, null]
    - [binfmt_misc, binfmt_misc, /proc/sys/fs/binfmt_misc, null]

provision_configs: true
  - /etc/resolv.conf
  - /etc/yum.repos.d
  - <your own file or folder here!>

The provision_config_files section of this plugin transfers the defined files or folders from the base system, you run amimator on, to your custom AMI change-root.

AWS API Authentication

You can use either a boto configuration file providing account keys or an IAM role associated with your EC2 instances.

Boto Config

See: http://docs.pythonboto.org/en/latest/boto_config_tut.html

IAM Role

See: https://github.com/Netflix/aminator/wiki/Configuration


  "Statement": [
      "Action": [
      "Effect": "Allow",
      "Resource": [



Simply create a custom AMI based on a base-AMI and rpm/deb package:

sudo aminate my-application-package -B ami-672ce210

Set custom name and suffix for the custom AMI:

sudo aminate my-application-package -B ami-672ce210 -n my-application-v1.22-x86_64-121122062014

Preserve the change-root environment and exit into an interactive shell if errors occur (very good for debugging):

sudo aminate my-application-package -B ami-672ce210 -i --debug --preserve-on-error

Known Issues

Using a amazon-ami as base-ami fails during yum clean-metadata

This is caused by the fact that amazon runs a contextualization-script on startup to define yum repos f.e. Since amimator only change-roots into the machine image (ebs-snapshot), there is no init-process started ever on the machine. After stumbling over this issue, I found the following post and basic info, how to fix that. Also described in this article.




Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.