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

POST https://cloud.engineyard.com:443/api/v2/environments/YOUR_ENVIRO_ID_GOES_HERE/add_instances

Parameters


role

Required

utilapp.

Default: none.


name

Required

string

Default: none.


instance_size

Optional

smallsmall_64medium_rammedium_ram_64medium_cpumedium_cpu_64largexlargexlarge_cpuxlarge_ramdoublexlarge_ramquadxlarge_ramquadxlarge_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


volume_size

Optional

number - a value in GB between 5 and 1024.

Default: 15 GB


snapshot_id

Optional

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

Defaults

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.


availability_zone

Optional

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-1aus-east-1bus-east-1c, or us-east-1d.

Default: Distributed across the region's availability zones.

Valid response example

{
"request":
{
"role": "util",
"name": "foo"
},
"instance":
{
"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

{
"request":
{"role":"util"},
"errors":
{"name":["can't be blank"]},
"status":"rejected"
}

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"}}' https://cloud.engineyard.com:443/api/v2/environments/YOUR_ENVIRO_ID_GOES_HERE/add_instances

Where ENGINEYARD_API_TOKEN looks something like this: 76f2d43d79bedd9bc74654a1ded733c9See 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.