How to deploy on Amazon EC2 with Vagrant

vagrant logo

I recently wrote up how to use Terraform to deploy on Amazon EC2. Check it out!

Join 38,000 others and follow Sean Hull on twitter @hullsean.

Why do I want Vagrant?

Vagrant is a really powerful tool for managing virtual machines. If you’re a developer it can make it push-button simple to setup a dev box on your laptop. It manages the images, and uses configuration files to describe specifics of your machines.

In the amazon environment, you can deploy machines just as easily as on your desktop. That’s pretty exciting for those of us already familiar with Vagrant. With that I’ve provided a simple 7 step howto for doing just that!

Also: Are SQL Databases Dead?

1. Use the Mac OS X installer

Fetch your download file here:

Vagrant Installer Downloads

Run the installer. It should do the right thing!

Also: Why Oracle Won’t Kill MySQL

2. Install the vagrant-aws plugin

$ vagrant plugin install vagrant-aws

Also: Bulletproofing MySQL Replication with Checksums

3. Fetch a vagrant box image

Box images vary depending on your “provider” which is vagrant-speak for the environment you’re running in. For aws, they’re some simple json files that tell Vagrant how to work in that environment.

The creator of the plugin has provided a dummy box. Let’s fetch it:

$ vagrant box add dummy

This command is straight out of the readme. What does it do? Take a look:

$ cd /var/root/.vagrant.d/boxes/dummy/aws

$ cat metadata.json
"provider": "aws"

There’s also the info.json file which looks like this:

$ cat info.json
{"url":"","downloaded_at":"2014-01-14 17:42:33 UTC"}

There’s not a whole lot going on here. If you’re deploying VirtualBox VMs with Vagrant, you’d see a VMware4 disk image. But with Amazon, it stores it’s own AMIs on S3, so Vagrant simply fetches them and runs them for you.

Related: Intro to EC2 Cloud Deployments

4. Configure Vagrantfile

Create a directory to hold your vagrant metadata. This would be the name of your machine:

$ cd /var/root
$ mkdir testaws
$ cd testaws
$ vagrant init

Edit the file as follows:

Vagrant.configure("2") do |config|
# = "sean"

config.vm.provider :aws do |aws, override|
aws.access_key_id = "AAAAIIIIYYYY4444AAAA”
aws.secret_access_key = "c344441LooLLU322223526IabcdeQL12E34At3mm”
aws.keypair_name = "iheavy"

aws.ami = "ami-7747d01e"

override.ssh.username = "ubuntu"
override.ssh.private_key_path = "/var/root/iheavy_aws/pk-XHHHHHMMMAABPEDEFGHOAOJH1QBH5324.pem"

If you’re familiar with the Amazon command line tools, you’ve probably setup environment variables. Otherwise these may not be familiar to you, so lets go through them:

Your access_key_id and secret_access_key are two pieces of information Amazon uses to identify your instances and bill you. Those are unique to your environment so keep them close to the vest. Here’s how you create them or find them on your aws dashboard.

The keypair_name is your personal SSH key. You may have one on your laptop which you use to access other servers. If so you can upload to the amazon environment. If not you can also use the dashboard to create your own. Whenever you spinup a server, you can instruct amazon to drop that key on the box in the right place. Then you’ll have secure command line access to the box, without password. Great for automation!

Next is your AMI. This is an important choice, as it determines the OS of the machine you’ll spinup, and many other characteristics. You can go with a Amazon Linux AMI but I quite like the Alestic ones from Eric Hammond. Trusted & reliable.

Looking for an ubuntu AMI? Try this ami locator tool.

Check this: 8 Best Practices for Deplying MySQL on AWS

5. Startup the box

Starting an instance once you’ve configured your Vagrantfile is pretty straightforward.

$ vagrant up —-provider=aws

Related: How to autoscale MySQL on Amazon EC2

6. Verify in the Amazon dashboard

Jump over to your amazon dashboard with this link. If you’re logged in already, that will take you to your EC2 instances. You should see a new one, based on the parameters in your Vagrantfile.

Read: Why devops talent is in short supply

7. Login to your Amazon instance

Last but not least, you’ll want to login. Note I’m explicitly specifying my SSH key here. Your path may vary…

$ ssh -i ./iheavy.pem [email protected]

Also: 5 more things deadly to scalability

Get more. Grab our exclusive monthly Scalable Startups. We share tips and special content. Our latest Why I don’t work with recruiters

  • John Sanabria

    I have been used Vagrant for awhile but I miss some Vagrant’s features in your example. For instance, I did not see what restrictions are for defining particular machine specs, e.g. number of cores and RAM. I did not see also if a particular provisioiner can be used with the new instance, e.g. chef recipes.

    • Sean Hull

      Thx John. Sounds like a good idea for a followup post.

      Do you have a blog?

  • M Lyahovsky

    C:Usersmoshetestaws>vagrant up –provider=aws

    The machine with the name ‘ù-provider=aws’ was not found configured for

    this Vagrant environment.

    i get this after following you to the letter

    • Sean Hull

      Hello M, there are a lot of possibilities. For starters there may be differences on Windows. You might try creating a vagrant linux box on windows, to setup your environment, and launch aws instances from there.

      Good luck!

  • M Lyahovsky

    your step by step got me where others left me hanging but can you run another instance

  • M Lyahovsky

    first of second step doenst even work on linux vagrant plugin install vagrant-aws there is no keyword plugin

  • M Lyahovsky

    now i am doing this on # encoding: utf-7

    Vagrant.configure(“2”) do |config|

    # = “sean”

    config.vm.provider :aws do |aws, override|

    aws.access_key_id = “AKIAJ7ZFF5GNM4PT75XQ”

    aws.secret_access_key = “woEbLLyRSiFiPJ2TiDricnJmyFZqFp8V3TRYD3wW”

    aws.keypair_name = “moshe”

    aws.ami = “ami-7747d01e”

    override.ssh.username = “ubuntu”

    override.ssh.private_key_path = “/var/root/iheavy_aws/pk-XHHHHHMMMAABPEDEFGHOAOJH1QBH5324.pem”


    end mac here is my vagrantfile which is giving me a headache


    If you are not doing this as root, the boxes/ dir is in $HOME/.vagrant.d/boxes/

    Now, why are you doing this as root?

    • Sean Hull

      cause i’m a bad boy. 🙂

  • Andrew Kew

    You dont need step 7, a simple “vagrant ssh” will connect you to your machine via SSH

    • Sean Hull

      Thx Andrew.

  • chetan

    $ cd /var/root/.vagrant.d/boxes/dummy/aws

    This is not showing in my machine help me out…

    • Shaykin Anton

      in my case, on Mac, it was under ~/.vagrant.d/boxes/dummy/0/aws

      • Sean Hull

        Thx Shaykin

  • Kiran Sharma

    Hi Sean,

    i have a few questions. Do I have to run all these command as a root or do I have to create an user vagrant and login as vagrant? Also, do I have to create an iam user as vagrant and use secret key and secret_access_key of that user in the vagrant file?

    When I check, the keypair which I downloaded while creating ec2 instance did not find in the instance. Do I have to upload from my computer to the ec2? or do I have to create it using ssh-keygen? I believe these both are same.


    • Sean Hull

      Depends on where you are in the process. As I recall I was an unprivileged user, who can control virtual box etc. That said there’s a lot of permissions that have to be set right also.

  • Kiran Sharma

    HI Sean,

    I am getting this error when I ran the vagrant up

    C:VAGRANTPROJECTaws>vagrant up –provider=aws

    There is a syntax error in the following Vagrantfile. The syntax error message is reproduced below for convenience:

    C:/VAGRANT/PROJECT/aws/Vagrantfile:10: invalid multibyte char (UTF-8)
    C:/VAGRANT/PROJECT/aws/Vagrantfile:11: invalid multibyte char (UTF-8)
    C:/VAGRANT/PROJECT/aws/Vagrantfile:20: syntax error, unexpected keyword_end, expecting end-of-input

    Here is my configuration

    # -*- mode: ruby -*-
    # vi: set ft=ruby :
    # encoding: Windows-1252————–I have added this line

    Vagrant.configure(2) do |config|
    config.vm.provider :aws do |aws, override|
    aws.access_key_id = “AAAAIIIIYYYY4444AAAA”
    aws.secret_access_key = “c344441LooLLU322223526IabcdeQL12E34At3mm”
    aws.keypair_name = “keypairname”
    aws.ami = “ami-7747d01e”
    override.ssh.username = “ubuntu”
    override.ssh.private_key_path = “c:VAGRANTPROJECTawskeypairname.pem”

    Please note that,

    (i) I have correct value for access_key,secret_key and keypair.
    (ii) The configuration file is edited in notepad. I believe, notepad does not keep multibyte character

    I also tried adding the line below

    aws.region = “us-east-1”

    I would appreciate if you could point me the issue


    • Sean Hull

      Appears you have an Invalid multibyte character. Are you familiar with character sets? For example ascii may be 256 bytes (8 bits or 1 byte) while chinese or other languages may be 2 or 4 bytes (16 or 32 bits).

      So perhaps you entered a non-ascii character into your vangrantfile?

      • POOL-POG

        It’s the curly quotes at the end of the line on the lines with “aws.access_key_id” and “aws.secret_access_key”. They need to be “straight” quotes.

        • Sean Hull

          Thx Pool!

  • imn2

    Hi! You mentioned ssh keys a few times. For the sake of clarity, can you specify in both cases if you mean public or private or both?

  • Milind Sisodiya

    Hi Sean,
    Can you please brief about below line. I am using windows box and through putty I am connecting to aws instance.I have downloaded my “.pem” file under “D:desktop*.pem”
    so what path I have to provide in below line.

    override.ssh.private_key_path = “/var/root/iheavy_aws/pk-XHHHHHMMMAABPEDEFGHOAOJH1QBH5324.pem”

    • Sean Hull

      Hi Milind, I haven’t setup on Windows before. Perhaps try cygwin?