Updated: January 16th, 2013
Remove an instance
Allows you to remove a utility or an application instance.
Important: The remove instances endpoint does not guard against removing all instances of the requested type.
Who can use it
Any user with an Engine Yard Cloud login and API token for the environment.
To remove an instance
POST https://cloud.engineyard.com:443/api/v2/environments/YOUR_ENVIRO_ID_GOES_HERE/remove_instances
Parameters
- role
-
Required
util
,app
.Default: none.
- name
-
Required for util instance
Optional for app instance
string
Default: none.
Valid response example
{
"request":
{
"role": "util",
"name": "foo"
},
"instance":
{
"amazon_id": "i-9999e9aa",
"availability_zone": "us-west-2a",
"bootstrapped_at": "2012-12-19T22:00:55+00:00",
"chef_status":
[{
"message": "Preparing to shutdown instance and take snapshots...",
"timestamp": "2013-01-03T03:15:42+00:00"
}],
"error_message": null,
"id": 999999,
"name": "foo",
"role": "util",
"size": "medium_cpu_64",
"status": "decommissioning",
"public_hostname": "ec2-50-112-65-999.us-west-2.compute.amazonaws.com",
"private_hostname": "ip-10-252-29-99.us-west-2.compute.internal"
},
"status":"accepted"
}
Invalid response example
{
"request":
{"role":"util"},
"errors":
{
"name": ["must be provided for util instances"],
"instance": ["environment has no matching running instances"]
},
"status":"rejected"
}
Curl example
This is an example of a simple remove 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/remove_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 remove 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.
It appears we can only remove one instance at a time using the API? I just issued two remove instance commands. The first one was accepted. The second one returned the following:
{"error":{"message":"Failed to save resource: Awsm::DeprovisionInstanceRequest: [\"50976772-d52b-45a3-b3a3-287a55ebcf6f\"]: Deprovision request 2b5cf53e-facf-4500-baae-f76df59f2153 is currently running","id":null}}
I'm trying to automate the adding and removing of app instances (poor man's autoscaling :), so would really like to be able to remove in bulk (just like I can do with add). Even better would be for both the add and remove instance API's to be able to take a parameter/count of how many instances (so that I don't have to issue individual commands for each instance).
Hi Chris,
The API is attempting to remove the same instance you're already de-provisioning. A work-around is for you to select the instance by its Amazon ID explicitly. Can you do that as part of your scripting? If not, I can open a ticket to change the behavior to skip over any currently de-provisioning instances.
--Tasha
The ideal for us would be to have the API (both this remove, and the add instance API) allow you to specify the number of instances to remove/add. But if that's not possible, then I can look into fetching the ID's, and figuring out a (random) removal (I think since we allocate randomly across zones, I can simply just select the first or last N instances and retain pretty good cross-zone coverage.). I'll try that out, but I'd love to hear what the EY team thinks about adding ability to specify N instances to add/remove - it'd make setting up scripts to "autoscale" easier, and somewhat simulate what you can do in the dashboard (I'm ok with a limit/max of 10 instances at a time if that's necessary).
Hi Chris,
I am opening a ticket and a sprint team will tackle this next week.
--Tasha
Great! I look forward to it.
Hi Chris,
The behavior has now been changed so that each time you request to decommission a server, a server will be decommissioned (regardless of whether or not another server is already decommissioned).
--Tasha
Feature request = Add support for not snapshotting the instance on termination.