Add an Instance

Updated: June 21st, 2013

Add an instance

Allows you to add a utility or an application instance.

Note: Adding multiple instances using this endpoint causes an application integration and quick Chef run for every instance added. If your application is sensitive to these events then you should add only one instance at a time.

Who can use it

Any user with an Engine Yard Cloud login and API token for the environment.

To add an instance





util, app.

Default: none.




Default: none.



small, small_64, medium_ram, medium_ram_64, medium_cpu, medium_cpu_64, large, xlarge, xlarge_cpu, xlarge_ram, doublexlarge_ram, quadxlarge_ram, quadxlarge_io.

Default: medium_cpu.

Note: Utility instances default to either 32-bit or 64-bit, depending on the account default. Application instances are created the same size as the app master. Database instances are created the same as the DB master.

Here is the list of supported instance types: here



number - a value in GB between 5 and 1024.

Default: 15 GB



number - the ID of the snapshot that you want to use to create the new instance. For example, snap-99999999.


Logic for app servers

Is there a completed snapshot from with in the last hour? If so, use it. If not ...

Is there an in-progress snapshot? If so, use it. If not ...

Then kick off a new snapshot and use it.

Logic for utility servers

Utility servers are assumed not to be taken from a snapshot unless you provide the snapshot ID and name of the util instance.



string - the AZ where you want the new instance to be. For example, if your environment is in US East (N. Virginia) region, then you specify us-east-1a, us-east-1b, us-east-1c, or us-east-1d.

Default: Distributed across the region's availability zones.

Valid response example

"role": "util",
"name": "foo"
"amazon_id": null,
"availability_zone": null,
"bootstrapped_at": null,
"chef_status": null,
"error_message": null,
"id": 999999,
"name": "foo",
"role": "util",
"size": "medium_cpu",
"status": "starting",
"public_hostname": null,
"private_hostname": null
"status": "accepted"

Invalid response example

{"name":["can't be blank"]},

Curl example

This is an example of a simple add instance operation using curl:

curl -v -H "X-EY-Cloud-Token: ENGINEYARD_API_TOKEN" -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"request": {"role":"util","name":"foo"}}'

Where ENGINEYARD_API_TOKEN looks something like this: 76f2d43d79bedd9bc74654a1ded733c9 See Get the API Token.

And where YOUR_ENVIRO_ID_GOES_HERE is a number. For example, 99999. See Get Environment Data.

Check status

You can check the status of add instance operations in progress by using the Engine Yard Cloud dashboard, or programmatically, using the API. See Get Instance Provisioning Status.

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.


  • Avatar
    Roger Zimmerman

    Has support been added for provisioning the M3/C3 instance types through the API? 


    Comment actions Permalink
  • Avatar
    jonathan thomas

    Although the API may accept snapshot_id and volume_size (two parameters I care about).
    It looks like the client gem does not support that:

    return"/environments/#{id}/add_instances", :request => {
              "role" => opts[:role],
              "name" => opts[:name]


    1) Aside from maintaining my own copy of the gem, that allows me to pass other parameters to that request,
    is there a branch that already includes the aforementioned attributes in the request?

    2) How do I (programmatically) get the most recent snapshot_ids from my app_master?

    Comment actions Permalink
  • Avatar
    J. Austin Hughey

    @Roger - We'll have to get back to you on that one; I was looking for documentation on something similar myself and I don't see it yet. I know you left this comment several months ago, but I figure some follow-up is better than none.

    @Jonathan - There have been recent updates to engineyard-cloud-client that will probably do what you want. Check out the main github repo:

    As for programmatically getting your app master snapshot, it's a little janky but this should do it...

    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk