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.


Please sign in to leave a comment.