Send an authentication request#

From a command prompt, send a POST tokens request to the Identity service. Include your username and API key as shown in the following example.

$ curl https://identity.api.rackspacecloud.com/v2.0/tokens  \
 -X POST \
 -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName","apiKey":"$apiKey"}}}' \
 -H "Content-type: application/json" \
 | python -m json.tool

Review the authentication response#

If your credentials are valid, the Identity service returns an authentication response that includes the following information:

• an authentication token
• a service catalog with information about the services you can access.
• user information and role assignments

In the following example, the ellipsis (...) represents other service endpoints, which are not shown. The values shown in this and other examples vary because the information returned is specific to your account.

Example: Authentication response

{
        "access": {
                "token": {
                        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                        "expires": "2014-11-24T22:05:39.115Z",
                        "tenant": {
                                "id": "110011",
                                "name": "110011"
                        },
                        "RAX-AUTH:authenticatedBy": [
                                "APIKEY"
                        ]
                 },
                "serviceCatalog": [
                        {
                                "name": "cloudDatabases",
                                "endpoints": [
                                        {
                                        "publicURL": "https://syd.databases.api.rackspacecloud.com/v1.0/110011",
                                        "region": "SYD",
                                        "tenantId": "110011"
                                        },
                                        {
                                                "publicURL": "https://dfw.databases.api.rackspacecloud.com/v1.0/110011",
                                                "region": "DFW",
                                                "tenantId": "110011"
                                        },
                                        {
                                                "publicURL": "https://ord.databases.api.rackspacecloud.com/v1.0/110011",
                                                "region": "ORD",
                                                "tenantId": "110011"
                                        },
                                        {
                                                "publicURL": "https://iad.databases.api.rackspacecloud.com/v1.0/110011",
                                                "region": "IAD",
                                                "tenantId": "110011"
                                        },
                                        {
                                                "publicURL": "https://hkg.databases.api.rackspacecloud.com/v1.0/110011",
                                                "region": "HKG",
                                                "tenantId": "110011"
                                        }
                                ],
                                "type": "rax:database"
                        },

                        ...

                        {
                                "name": "cloudDNS",
                                "endpoints": [
                                        {
                                                "publicURL": "https://dns.api.rackspacecloud.com/v1.0/110011",
                                                "tenantId": "110011"
                                        }
                                ],
                                "type": "rax:dns"
                        },
                        {
                                "name": "rackCDN",
                                "endpoints": [
                                        {
                                                "internalURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
                                                "publicURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
                                                "tenantId": "110011"
                                        }
                                ],

                                "type": "rax:cdn"
                        }
                ],
                "user": {
                        "id": "123456",
                        "roles": [
                                {
                                        "description": "A Role that allows a user access to keystone Service methods",
                                        "id": "6",
                                        "name": "compute:default",
                                        "tenantId": "110011"
                                },
                                {
                                        "description": "User Admin Role.",
                                        "id": "3",
                                        "name": "identity:user-admin"
                                }
                        ],
                        "name": "jsmith",
                        "RAX-AUTH:defaultRegion": "ORD"
                }
        }
}

If the request was successful, you can find the authentication token and other information in the authentication response. You'll need these values to submit requests to the API. See Configure environment variables.

If the request failed, review the response message and the following error message descriptions to determine next steps.

400 Invalid request body: unable to parse Auth data. Please review XML or JSON formatting

Review the authentication request for syntax or coding errors. If you are using cURL, see the Using cURL.

401 Unable to authenticate user with credentials provided.

Verify the authentication credentials submitted in the authentication request. If necessary, contact your Rackspace Cloud Administrator or Rackspace Support to get valid credentials.

Configure environment variables#

The authentication response returns the following values that you need to include when you make service requests to the Autoscale API.

token ID

The token ID value is required to confirm your identity each time you access the service. Include it in the X-Auth-Token header for each API request.

The expires attribute indicates the date and time that the token will expire, unless it is revoked prior to the expiration. To get a new token, submit another authentication request. For more information, see Manage tokens and token expiration.

tenant ID

The tenant ID provides your account number. For most Rackspace Cloud service APIs, the tenant ID is appended to the API endpoint in the service catalog automatically. For Rackspace Cloud Services, the tenant ID has the same value as the tenant name.

endpoint

The API endpoint provides the URL that you use to access the API service. For guidance on choosing an endpoint, see Service access.

To make it easier to include the values in API requests, use the export command to create environment variables that can be substituted for the actual values. For example, you can create an API_ENDPOINT variable to store the URL for accessing an API service. To reference the value in an API request, prefix the variable name with a $, for example $API_ENDPOINT.

Create environment variables

1. In the token section of the authentication response, copy the token id and tenant id values from the token object.

   {
             "access": {
                     "token": {
                             "id": "AA2345631l1NVdD6D1OCauKA0e9fioquZqVlS-hpbCqQ5Yx1zLOREGf4efBh10CfB5AvjC1yld4ZNJUouE7DA0QB0n5nRbdDsYADA-ORICIqHNqOVS_kYmedqDh75c_PLe123456789101",
                             "expires": "2015-11-18T18:35:45.013Z",
                             "tenant": {
                                     "id": "123456",
                                     "name": "123456"
                             },
                             "RAX-AUTH:authenticatedBy": [
                                     "APIKEY"
                             ]
     },
   

2. Export the token ID to an environment variable that can be supplied in the X-Auth-Token header required in each API request.

   $ export AUTH_TOKEN="token-id"
   

   Replace token-id with the authentication token id value returned in the authentication response.

3. Export the tenant ID to an environment variable that can be supplied in requests that require you to specify a tenant ID or tenant name.

   $ export TENANT_ID="tenant-id"
   

   Replace tenant-id with the authentication token id value returned in the authentication response.

4. In the service catalog section of the authentication response, copy the publicURL value for the Autoscale API, version, and region that you want to access.

   This example shows the endpoints available for the Autoscale API.

   {
                   "name": "RackspaceAutoscale",
                   "endpoints": [
                                   {
                                                   "region": "HKG",
                                                   "tenantId": "123456",
                                                   "publicURL": "https://hkg.autoscale.api.rackspacecloud.com/v1.0/123456",
                                   },
                                   {
                                                   "region": "SYD",
                                                   "tenantId": "123456",
                                                   "publicURL": "https://syd.autoscale.api.rackspacecloud.com/v1.0/123456",
                                   },
                                   {
                                                   "region": "DFW",
                                                   "tenantId": "123456",
                                                   "publicURL": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/123456",
                                   },
                                   {
                                                   "region": "IAD",
                                                   "tenantId": "123456",
                                                   "publicURL": "https://iad.autoscale.api.rackspacecloud.com/v1.0/123456",
                                   },
                                   {
                                                   "region": "ORD",
                                                   "tenantId": "123456",
                                                   "publicURL": "https://ord.autoscale.api.rackspacecloud.com/v1.0/123456",
                                   }
                   ],
                   "type": "rax:autoscale"
   },
   

5. Copy the URL, and then export it to an environment variable.

   $ export API_ENDPOINT="publicURL"
   

   Replace publicURL with the publicURL value listed in the service catalog.

   Note

   The Identity service returns an endpoint URL with your tenant ID (account ID). With Rackspace Auto Scale, you have two options for including the tenant ID in API requests.

   • Include it in the URL.

     https://dfw.autoscale.api.rackspacecloud.com/v1.0/123456
     

   • Submit API requests to the base endpoint https://dfw/autoscale.api.rackspace.cloud.com/v1.0, and specify the tenant ID value in the X-Project-ID header in each request with the value set to the tenant ID.

   For details, see Service access endpoints.

List cloud server images#

Before you create a server through the Cloud Server API, you need to obtain a list of available images so that you can choose one for your new server.

After you choose an image, copy its image ID. You use this image ID when you create the server.

Use the Cloud Servers API to issue a List Images request to retrieve a list of options available for configuring your server. The following example shows how to request a list cloud server images.

Requesting a list of cloud server images

   curl -X GET \
   -H "Content-Type: application/json" \
   -H "X-Auth-token:{auth-token}" \
   https://ord.servers.api.rackspacecloud.com/v2/{tenant-id}/images?type=SNAPSHOT | python -mjson.tool

1. After creating your server you customize it so that it can process
   your requests. For example, if you are building a webhead
   scaling group, configure Apache to start on launch and serve
   the files that you need.

2. After you have created and customized your server, save its image
   and record the imageID value that is returned in the response body.

Create a cloud server#

After you have obtained the imageID for the server image you want to create, you need to create your cloud server. Auto Scale will use the configuration info in this server image as a blueprint for create new server images.

You can create a server using one of the following methods:

1. Create a server through the Cloud Control Panel.
2. Create a server through the Cloud Servers API by using a Create Server request.

Create a cloud server image#

After you have created a Cloud Server, you need to create an image, which Auto Scale will use to create new servers.

You can create a server image using one of the following methods:

1. Create a server image through the Cloud Control Panel. Make sure to record the imageID value for the image you have created.
2. Create a server image through the Cloud Servers API by using a Create Image request to obtain the imageID value, use a List Images request.

Create a scaling group#

Now you are ready to create your first scaling group. For this exercise, you will create a schedule-based scaling group that will trigger a scaling event at 11 P.M. daily. The following example shows how to create a schedule-based scaling group by submitting a POST request using cURL.

{
   "launchConfiguration":{
      "args":{
         "loadBalancers":[
            {
               "port":80,
               "loadBalancerId":237935
            }
         ],
         "server":{
            "name":"autoscale_server",
            "imageRef":"7cf5ffc3-7b20-46fd-98e4-fefa9908d7e8",
            "flavorRef":"performance1-2",
            "OS-DCF:diskConfig":"AUTO",
            "networks":[
               {
                  "uuid":"11111111-1111-1111-1111-111111111111"
               },
               {
                  "uuid":"00000000-0000-0000-0000-000000000000"
               }
            ]
         }
      },
      "type":"launch_server"
   },
   "groupConfiguration":{
      "maxEntities":10,
      "cooldown":360,
      "name":"testscalinggroup",
      "minEntities":0
   },
   "scalingPolicies":[
      {
         "cooldown":0,
         "name":"scale up by 1",
         "change":1,
         "type":"schedule",
         "args":{
            "cron":"23 * * * *"
         }
      }
   ]
}

If the POST request is successful, the response data will be returned in JSON format as shown in the following example:

{
   "group":{
      "groupConfiguration":{
         "cooldown":360,
         "maxEntities":10,
         "metadata":{

         },
         "minEntities":0,
         "name":"testscalinggroup"
      },
      "id":"48692442-2dbe-4311-955e-bc29f02ae311",
      "launchConfiguration":{
         "args":{
            "loadBalancers":[
               {
                  "loadBalancerId":237935,
                  "port":80
               }
            ],
            "server":{
               "OS-DCF:diskConfig":"AUTO",
               "flavorRef":"performance1-2",
               "imageRef":"7cf5ffc3-7b20-46fd-98e4-fefa9908d7e8",
               "name":"autoscale_server",
               "networks":[
                  {
                     "uuid":"11111111-1111-1111-1111-111111111111"
                  },
                  {
                     "uuid":"00000000-0000-0000-0000-000000000000"
                  }
               ]
            }
         },
         "type":"launch_server"
      },
      "links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/",
            "rel":"self"
         }
      ],
      "scalingPolicies":[
         {
            "args":{
               "cron":"23 * * * *"
            },
            "change":1,
            "cooldown":0,
            "id":"9fa63149-c93d-4116-8069-74d68f48fadc",
            "links":[
               {
                  "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/policies/9fa63149-c93d-4116-8069-74d68f48fadc/",
                  "rel":"self"
               }
            ],
            "name":"scale up by 1",
            "type":"schedule"
         }
      ],
      "scalingPolicies_links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/policies/",
            "rel":"policies"
         }
      ],
      "state":{
         "active":[

         ],
         "activeCapacity":0,
         "desiredCapacity":0,
         "name":"testscalinggroup",
         "paused":false,
         "pendingCapacity":0
      }
   }
}

Delete a scaling group#

You can use the Auto Scale API to deactivate and delete one or more scaling groups. Your options for deleting the scaling group depend on whether your scaling group has active entities or not.

When a group contains no servers, you can eliminate the group by sending a DELETE request to its group ID.

The following two options are possible for deleting a scaling group:

• If there are no active entities in your configuration, use the DELETE request to delete the scaling group.
• If there are active entities, then force delete the group by submitting a DELETE request with force parameter to true.

Delete a scaling group with no active entities

To delete a scaling policy group that has no active entities, submit a DELETE request with the tenantID and groupIDparameters specified in the request URL as shown in the following example:

http -vv DELETE https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/ X-Auth-Token:XXXXXXXXXXXXXXXX

If the DELETE request is successful, a 204 response code with no response body will be returned. If the request fails, a 403 response code will be returned with a message stating that your group still has active entities as shown in the following example:

Group d5f5f3ad-faef-4c8f-99c4-0e931189c521 for tenant 829409 still has entities.

Delete a scaling group using FORCE DELETE

The Auto Scale API provides an option for users to force delete a scaling group that has active servers. The FORCE DELETE option will remove all servers in the configuration from the load balancer(s) and then delete the server.

To use the FORCE DELETE option, submit a DELETE request with the tenantId and groupIdparameters specified in the request URL, and set the force parameter to true.

DELETE /{tenantId}/groups/{groupId}?force=true

Upon successful submission of this request the minEntities and maxEntities parameters will automatically be set to 0 and the deletion of the group will begin. If the DELETE request is successful, a 204 response code with an empty response body will be returned.

List scaling groups#

GET /v1.0/{tenantId}/groups

This operation lists the scaling groups that are available for a specified tenant.

This table shows the possible response codes for this operation:

{
   "groups":[
      {
         "id":"e41380ae-173c-4b40-848a-25c16d7fa83d",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/e41380ae-173c-4b40-848a-25c16d7fa83d/",
               "rel":"self"
            }
         ],
         "state":{
            "active":[

            ],
            "activeCapacity":0,
            "desiredCapacity":0,
            "paused":false,
            "pendingCapacity":0,
            "name":"testscalinggroup198547"
         }
      },
      {
         "id":"f82bb000-f451-40c8-9dc3-6919097d2f7e",
         "state":{
            "active":[

            ],
            "activeCapacity":0,
            "desiredCapacity":0,
            "paused":false,
            "pendingCapacity":0,
            "name":"testscalinggroup198547"
         },
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/f82bb000-f451-40c8-9dc3-6919097d2f7e/",
               "rel":"self"
            }
         ]
      }
   ],
   "groups_links":[

   ]
}

Create scaling group#

POST /v1.0/{tenantId}/groups

This operation creates a scaling group.

This operation creates a scaling group or a collection of servers and load balancers that are managed by a scaling policy. To describe the group, specify the scaling group configuration, launch configuration, and optional scaling policies in the request body in JSON format.

If the request succeeds, the response body describes the created group in JSON format. The response includes an ID and links for the group.

The number of resources entities that are specified in minEntities and maxEntities overrides the amount of resources that can be specified in a policy. See also Using the min and max values with policies.

You can specify custom metadata for your group configuration using the optional metadata parameter.

This table shows the possible response codes for this operation:

{
   "launchConfiguration":{
      "args":{
         "loadBalancers":[
            {
               "port":80,
               "loadBalancerId":237935
            }
         ],
         "server":{
            "name":"autoscale_server",
            "imageRef":"7cf5ffc3-7b20-46fd-98e4-fefa9908d7e8",
            "flavorRef":"performance1-2",
            "OS-DCF:diskConfig":"AUTO",
            "networks":[
               {
                  "uuid":"11111111-1111-1111-1111-111111111111"
               },
               {
                  "uuid":"00000000-0000-0000-0000-000000000000"
               }
            ]
         }
      },
      "type":"launch_server"
   },
   "groupConfiguration":{
      "maxEntities":10,
      "cooldown":360,
      "name":"testscalinggroup",
      "minEntities":0
   },
   "scalingPolicies":[
      {
         "cooldown":0,
         "name":"scale up by 1",
         "change":1,
         "type":"schedule",
         "args":{
            "cron":"23 * * * *"
         }
      }
   ]
}

{
   "group":{
      "groupConfiguration":{
         "cooldown":360,
         "maxEntities":10,
         "metadata":{

         },
         "minEntities":0,
         "name":"testscalinggroup"
      },
      "id":"48692442-2dbe-4311-955e-bc29f02ae311",
      "launchConfiguration":{
         "args":{
            "loadBalancers":[
               {
                  "loadBalancerId":237935,
                  "port":80
               }
            ],
            "server":{
               "OS-DCF:diskConfig":"AUTO",
               "flavorRef":"performance1-2",
               "imageRef":"7cf5ffc3-7b20-46fd-98e4-fefa9908d7e8",
               "name":"autoscale_server",
               "networks":[
                  {
                     "uuid":"11111111-1111-1111-1111-111111111111"
                  },
                  {
                     "uuid":"00000000-0000-0000-0000-000000000000"
                  }
               ]
            }
         },
         "type":"launch_server"
      },
      "links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/",
            "rel":"self"
         }
      ],
      "scalingPolicies":[
         {
            "args":{
               "cron":"23 * * * *"
            },
            "change":1,
            "cooldown":0,
            "id":"9fa63149-c93d-4116-8069-74d68f48fadc",
            "links":[
               {
                  "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/policies/9fa63149-c93d-4116-8069-74d68f48fadc/",
                  "rel":"self"
               }
            ],
            "name":"scale up by 1",
            "type":"schedule"
         }
      ],
      "scalingPolicies_links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/829409/groups/48692442-2dbe-4311-955e-bc29f02ae311/policies/",
            "rel":"policies"
         }
      ],
      "state":{
         "active":[

         ],
         "activeCapacity":0,
         "desiredCapacity":0,
         "name":"testscalinggroup",
         "paused":false,
         "pendingCapacity":0
      }
   }
}

Show scaling group configuration#

GET /v1.0/{tenantId}/groups/{groupId}/config

This operation shows the configuration for a scaling group.

thows the configuration for a specified scaling group, including group settings, launch configuration settings, and policy settings. The configuration is returned in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "groupConfiguration":{
      "cooldown":60,
      "maxEntities":0,
      "metadata":{

      },
      "minEntities":0,
      "name":"smallest possible group"
   }
}

Update scaling group configuration#

PUT /v1.0/{tenantId}/groups/{groupId}/config

This operation updates the configuration for the scaling group.

This operation updates the configuration of an existing scaling group. To change the configuration, specify the new configuration in the request body in JSON format. Configuration elements include the minimum number of entities, the maximum number of entities, the global cooldown time, and other metadata. If the update is successful, no response body is returned.

This table shows the possible response codes for this operation:

{
   "name":"workers",
   "cooldown":60,
   "minEntities":5,
   "maxEntities":100,
   "metadata":{
      "firstkey":"this is a string",
      "secondkey":"1"
   }
}

Show scaling group details#

GET /v1.0/{tenantId}/groups/{groupId}

This operation retrieves configuration details for a specified scaling group.

Details include the launch configuration and the scaling policies for the specified scaling group configuration.

The details appear in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "group":{
      "groupConfiguration":{
         "cooldown":60,
         "maxEntities":0,
         "metadata":{

         },
         "minEntities":0,
         "name":"smallest possible launch config group"
      },
      "state":{
         "active":[

         ],
         "activeCapacity":0,
         "desiredCapacity":0,
         "paused":false,
         "pendingCapacity":0,
         "name":"smallest possible launch config group"
      },
      "id":"605e13f6-1452-4588-b5da-ac6bb468c5bf",
      "launchConfiguration":{
         "args":{
            "server":{

            }
         },
         "type":"launch_server"
      },
      "links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/",
            "rel":"self"
         }
      ],
      "scalingPolicies":[
         {
            "changePercent":-5.5,
            "cooldown":1800,
            "id":"eb0fe1bf-3428-4f34-afd9-a5ac36f60511",
            "links":[
               {
                  "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/eb0fe1bf-3428-4f34-afd9-a5ac36f60511/",
                  "rel":"self"
               }
            ],
            "name":"scale down by 5.5 percent",
            "type":"webhook"
         }
      ]
   }
}

Show scaling group details including webhooks#

GET /v1.0/{tenantId}/groups/{groupId}

This operation retrieves configuration details for a specified scaling group and its associated webhooks.

Details include the launch configuration, the scaling policies, and the policies' webhooks for the specified scaling group configuration.

The details appear in the response body in JSON format.

This table shows the possible response codes for this operation:

{
  "group": {
    "groupConfiguration": {
      "cooldown": 60,
      "maxEntities": 0,
      "metadata": {},
      "minEntities": 0,
      "name": "smallest possible launch config group"
    },
    "state": {
      "active": [],
      "activeCapacity": 0,
      "desiredCapacity": 0,
      "paused": false,
      "pendingCapacity": 0
    },
    "id": "605e13f6-1452-4588-b5da-ac6bb468c5bf",
    "launchConfiguration": {
      "args": {
        "server": {}
      },
      "type": "launch_server"
    },
    "links": [
      {
        "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/",
        "rel": "self"
      }
    ],
    "scalingPolicies": [
      {
        "changePercent": -5.5,
        "cooldown": 1800,
        "id": "eb0fe1bf-3428-4f34-afd9-a5ac36f60511",
        "links": [
          {
            "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/eb0fe1bf-3428-4f34-afd9-a5ac36f60511/",
                "rel": "self"
            }
        ],
        "name": "scale down by 5.5 percent",
        "type": "webhook",
        "webhooks": [
          {
            "id":"05f7d9d9-b9d0-40ac-8d3b-610197775c7f",
            "name": "automatically generated",
            "metadata": {},
            "links": [
              {
                "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/eb0fe1bf-3428-4f34-afd9-a5ac36f60511/webhooks/05f7d9d9-b9d0-40ac-8d3b-610197775c7f/",
                "rel": "self"
              },
              {
                "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/execute/1/392be67bacfd1adf54e4f9fbc2b40873b9c7c3128315647f46d94c4b5c56b4d6/",
                "rel": "capability"
              }
            ]
          }
        ],
        "webhooks_links": [
          {
            "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/eb0fe1bf-3428-4f34-afd9-a5ac36f60511/webhooks/",
            "rel": "webhooks"
          }
        ]
      }
    ],
    "scalingPolicies_links": [
      {
        "href": "https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/",
        "rel": "policies"
      }
    ]
  }
}

Delete scaling group#

DELETE /v1.0/{tenantId}/groups/{groupId}

This operation deletes a specified scaling group.

The scaling group must be empty before it can be deleted. An empty group contains no entities. If deletion is successful, no response body is returned. If the group contains pending or active entities, deletion fails and a 409 error message is returned. If there are pending or active servers in the scaling group, pass force=true to force delete the group. Passing force=true immediately deletes all active servers in the group. Pending servers are deleted when they build and become active.

This table shows the possible response codes for this operation:

Delete server from scaling group#

DELETE /v1.0/{tenantId}/groups/{groupId}/servers/{serverId}

This operation deletes and replaces a specified server in a scaling group. If the group launch configuration specifies a draining_timeout value, then the load balancer node associated with this server is put in DRAINING mode for the specified number of seconds before the server is deleted.

You can delete and replace a server in a scaling group with a new server in that scaling group. By default, the specified server is deleted and replaced. The replacement server has the current launch configuration settings and a different IP address.

This table shows the possible response codes for this operation:

Get scaling group state#

GET /v1.0/{tenantId}/groups/{groupId}/state

This operation retrieves the current state of a scaling group.

The GroupState object consists of the following properties:

• paused. If paused=TRUE, the group does not scale up or down. All scheduled or API-generated policy operations are suspended, and convergence is not triggered. When the group is paused, any POST requests to converge or execute policy operations return a 403 GroupPausedError response. If paused=FALSE, all group scaling and convergence operations resume and scheduled or API-generated policy exectuions are allowed.
• pendingCapacity. Integer. Specifies the number of servers that are in a "building" state.
• name. Specifies the name of the group.
• active. Specifies an array of active servers in the group. This array includes the server Id, as well as other data.
• activeCapacity. Integer. Specifies the number of active servers in the group.
• desiredCapacity. Integer. Specifies the number of servers that are desired in the scaling group.
• status. String. Indicates the scaling group status. If status=ACTIVE, the scaling group is healthy and actively scaling up and down on request. If status=ERROR, the scaling group cannot complete scaling operation requests successfully, typically due to an unrecoverable error that requires user attention.
• errors. List of objects. If status=ERROR then this field contains a list of JSON objects with each object containing a message property that describes the error in human readable format.

This operation retrieves the current state of the specified scaling group. It describes the state of the group in terms of its current set of active entities, the number of pending entities, and the desired number of entities. The description is returned in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "group":{
      "paused":false,
      "pendingCapacity":0,
      "name":"testscalinggroup198547",
      "active":[],
      "activeCapacity":0,
      "desiredCapacity":0
      "status": "ACTIVE"
   }
}

{
   "group":{
     "paused":false,
     "pendingCapacity":0,
     "name":"testscalinggroup198547",
     "active":[],
     "activeCapacity":0,
     "desiredCapacity":0
     "status": "ERROR"
     "errors": [
       {"message": "Cloud load balancer 85621 is being deleted"}
    ]
  }
}

Pause group#

POST /v1.0/{tenantId}/groups/groupId/pause

This operation pauses the specified scaling group. When a group is paused, no policy or convergence operations are allowed. Any convergence operations in progress are stopped. Group configuration updates like min/max/cooldown and launch configurations updates like imageRef can run when a group is paused. You can resume a paused group by submitting a resume request.

This operation does not take any data and does not return any data. If it succeeds, a 204 response code is returned.

This table shows the possible response codes for this operation:

Resume group#

POST /v1.0/{tenantId}/groups/groupId/resume

This operation resumes the specified scaling group. When a group is resumed, policy executions and convergence operations are allowed. The group state contains "paused": false. You can pause a group by submitting a pause request.

This operation does not take any data and does not return any data. If it succeeds, a 204 response code is returned.

This table shows the possible response codes for this operation:

Trigger convergence#

POST /v1.0/{tenantId}/groups/groupId/converge

This operation triggers convergence for a specific scaling group. Convergence implies that Autoscale attempts to continuously converge to the desired state of the scaling group, instead of manipulating servers only once. When the convergence process starts, it will continue until the desired number of servers are in the ACTIVE state.

This operation does not take any data and does not return any data. If it succeeds, a 204 response code is returned.

This table shows the possible response codes for this operation:

Show launch configuration#

GET /v1.0/{tenantId}/groups/{groupId}/launch

This operation retrieveslaunch configuration details for a specified scaling group.

The details include from which image to create a server, which cloud load balancers to join the server to, which networks to add the server to, and other metadata.

The details appear in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "launchConfiguration":{
      "type":"launch_server",
      "args":{
         "server":{
            "flavorRef":"performance1-4",
            "name":"webhead",
            "imageRef":"0d589460-f177-4b0f-81c1-8ab8903ac7d8",
            "OS-DCF:diskConfig":"AUTO",
            "metadata":{
               "mykey":"myvalue"
            },
            "personality":[

            ],
            "networks":[
               {
                  "uuid":"11111111-1111-1111-1111-111111111111"
               }
            ]
         },
         "loadBalancers":[
             { "loadBalancerId": "35635",
               "port": 80
             }
         ],
         "draining_timeout": 30
      }
   }
}

Update launch configuration#

PUT /v1.0/{tenantId}/groups/{groupId}/launch

This operation updates an existing launch configuration for the specified scaling group.

To change the launch configuration, specify the new configuration in the request body in JSON format. Configuration elements include from which image to create a server, which load balancers to join the server to, which networks to add the server to, and other metadata. If the update is successful, no response body is returned.

This table shows the possible response codes for this operation:

{
   "type":"launch_server",
   "args":{
      "server":{
         "flavorRef":"performance1-4",
         "name":"webhead",
         "imageRef":"0d589460-f177-4b0f-81c1-8ab8903ac7d8",
         "OS-DCF:diskConfig":"AUTO",
         "metadata":{
            "mykey":"myvalue"
         },
         "personality":[

         ],
         "networks":[
            {
               "uuid":"11111111-1111-1111-1111-111111111111"
            }
         ]
      },
      "loadBalancers":[
         {
            "loadBalancerId":2200,
            "port":8081
         }
      ],
     "draining_timeout": 30
   }
}

List policies#

GET /v1.0/{tenantId}/groups/{groupId}/policies

This operation lists scaling policies that are available to a specified scaling group.

Each policy is described in terms of an ID, name, type, adjustment, cooldown time, and links. These descriptions are returned in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "policies":[
      {
         "args":{
            "cron":"23 * * * *"
         },
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"5f26e16c-5fa7-4d4f-8e78-257ea711389f",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/5f26e16c-5fa7-4d4f-8e78-257ea711389f/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent at 11pm",
         "type":"schedule"
      },
      {
         "args":{
            "at":"2013-12-05T03:12:00Z"
         },
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"9f7c5801-6b25-4f5a-af07-4bb752e23d53",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/9f7c5801-6b25-4f5a-af07-4bb752e23d53/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent on the 5th",
         "type":"schedule"
      },
      {
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"eb0fe1bf-3428-4f34-afd9-a5ac36f60511",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/eb0fe1bf-3428-4f34-afd9-a5ac36f60511/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent",
         "type":"webhook"
      },
      {
         "cooldown":1800,
         "desiredCapacity":5,
         "id":"2f45092a-fde7-4461-a67a-3519e0366cd6",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/2f45092a-fde7-4461-a67a-3519e0366cd6/",
               "rel":"self"
            }
         ],
         "name":"set group to 5 servers",
         "type":"webhook"
      },
      {
         "change":1,
         "cooldown":1800,
         "id":"e36e6a43-2a7a-433c-918c-39fa45b75d12",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/e36e6a43-2a7a-433c-918c-39fa45b75d12/",
               "rel":"self"
            }
         ],
         "name":"scale up by one server",
         "type":"webhook"
      }
   ],
   "policies_links":[

   ]
}

Create scaling policy#

POST /v1.0/{tenantId}/groups/{groupId}/policies

This operation creates one or more scaling policies for a specified scaling group.

To create a policy, specify it in the request body in JSON format. Each description must include a name, type, adjustment, and cooldown time.

Use the JSON response to obtain information about the newly-created policy or policies:

• The response header points to the List Policies endpoint.
• The response body provides an array of scaling policies.

The examples that are provided below show several methods for creating a scaling policy:

• A request to create a policy based on desired capacity.
• A request to create a policy based on incremental change.
• A request to create a policy based on change percentage.
• A request to create a policy based on change percentage scheduled daily, at a specific time of day.
• A request to create a policy based on change percentage scheduled once, for a specific date and time.
• A request to create multiple policies, followed by the matching response.

This table shows the possible response codes for this operation:

[
   {
      "name":"set group to 5 servers",
      "desiredCapacity":5,
      "cooldown":1800,
      "type":"webhook"
   }
]

[
   {
      "name":"scale up by one server",
      "change":1,
      "cooldown":1800,
      "type":"webhook"
   }
]

[
   {
      "name":"scale down by 5.5 percent",
      "changePercent":-5.5,
      "cooldown":1800,
      "type":"webhook"
   }
]

[
   {
      "name":"scale down by 5.5 percent at 11pm",
      "changePercent":-5.5,
      "cooldown":1800,
      "type":"schedule",
      "args":{
         "cron":"23 * * * *"
      }
   }
]

[
  {
    "name": "scale down by 5.5 percent on the 5th",
    "changePercent": -5.5,
    "cooldown": 1800,
    "type": "schedule",
    "args": {
      "at": "2013-12-05T03:12:00Z"
    }
  }
]

[
   {
      "change":1,
      "cooldown":1800,
      "name":"scale up by one server",
      "type":"webhook"
   },
   {
      "changePercent":-5.5,
      "cooldown":1800,
      "name":"scale down by 5.5 percent",
      "type":"webhook"
   },
   {
      "cooldown":1800,
      "desiredCapacity":5,
      "name":"set group to 5 servers",
      "type":"webhook"
   },
   {
      "args":{
         "cron":"23 * * * *"
      },
      "changePercent":-5.5,
      "cooldown":1800,
      "name":"scale down by 5.5 percent at 11pm",
      "type":"schedule"
   },
   {
      "args":{
         "at":"2013-12-05T03:12:00Z"
      },
      "changePercent":-5.5,
      "cooldown":1800,
      "name":"scale down by 5.5 percent on the 5th",
      "type":"schedule"
   }
]

{
   "policies":[
      {
         "args":{
            "at":"2013-12-05T03:12:00Z"
         },
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"9f7c5801-6b25-4f5a-af07-4bb752e23d53",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/9f7c5801-6b25-4f5a-af07-4bb752e23d53/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent on the 5th",
         "type":"schedule"
      },
      {
         "cooldown":1800,
         "desiredCapacity":5,
         "id":"b0555a35-b2cb-4f0e-8743-d59e1621b980",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/b0555a35-b2cb-4f0e-8743-d59e1621b980/",
               "rel":"self"
            }
         ],
         "name":"set group to 5 servers",
         "type":"webhook"
      },
      {
         "args":{
            "cron":"23 * * * *"
         },
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"30707675-8e7c-4ea5-9358-c21648afcf29",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/30707675-8e7c-4ea5-9358-c21648afcf29/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent at 11pm",
         "type":"schedule"
      },
      {
         "change":1,
         "cooldown":1800,
         "id":"1f3bdd08-7aae-4009-a3b7-49aa47fc0876",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/1f3bdd08-7aae-4009-a3b7-49aa47fc0876/",
               "rel":"self"
            }
         ],
         "name":"scale up by one server",
         "type":"webhook"
      },
      {
         "changePercent":-5.5,
         "cooldown":1800,
         "id":"5afac18c-41e5-49d6-aba8-dec17c0d8ed7",
         "links":[
            {
               "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/5afac18c-41e5-49d6-aba8-dec17c0d8ed7/",
               "rel":"self"
            }
         ],
         "name":"scale down by 5.5 percent",
         "type":"webhook"
      }
   ]
}

Show policy details#

GET /v1.0/{tenantId}/groups/{groupId}/policies/{policyId}

This operation retrieves scaling policy details.

Details include an ID, name, type, adjustment, cool-down time, and links.

The details appear in the response body in JSON format.

This table shows the possible response codes for this operation:

{
   "policy":{
      "args":{
         "cron":"23 * * * *"
      },
      "changePercent":-5.5,
      "cooldown":1800,
      "id":"5f26e16c-5fa7-4d4f-8e78-257ea711389f",
      "links":[
         {
            "href":"https://dfw.autoscale.api.rackspacecloud.com/v1.0/676873/groups/605e13f6-1452-4588-b5da-ac6bb468c5bf/policies/5f26e16c-5fa7-4d4f-8e78-257ea711389f/",
            "rel":"self"
         }
      ],
      "name":"scale down by 5.5 percent at 11pm",
      "type":"schedule"
   }
}

Update scaling policy#

PUT /v1.0/{tenantId}/groups/{groupId}/policies/{policyId}

This operation updates an existing scaling policy for the specified tenant.

To update the policy, specify the name, type, adjustment, and cooldown time for the policy in the request body in JSON format. If the change succeeds, no response body is returned.

This table shows the possible response codes for this operation: