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
util
,app
.Default: none.
- name
-
Required
string
Default: none.
- instance_size
-
Optional
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
- volume_size
-
Optional
number - a value in GB between
5
and1024
.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-1a
,us-east-1b
,us-east-1c
, orus-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: 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.
Has support been added for provisioning the M3/C3 instance types through the API?
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:
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?
@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: https://github.com/engineyard/engineyard-cloud-client
As for programmatically getting your app master snapshot, it's a little janky but this should do it...
https://gist.github.com/jaustinhughey/aaf37c370f73c4be4095