Follow

Add an Instance

Updated:

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 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-1a, us-east-1b, us-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: 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.

Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request

Comments

  • Avatar
    Roger Zimmerman

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

     

  • 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:

    environment.rb:
    return api.post("/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?

  • 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: 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

Powered by Zendesk