1. REST API for Oracle Java Cloud Service
  2. Tasks
  3. Automatic Scaling

Create an Auto Scaling Policy

post

/paas/api/v1.1/instancemgmt/{identityDomainId}/services/JaaS/instances/{serviceId}/autoscaling/policies

This endpoint is not applicable to service instances created on Oracle Cloud Infrastructure.

Creates and enables the automatic (auto) scaling policy for an Oracle Java Cloud Service instance.

The policy defines rules and conditions for when to automatically scale the service instance. Only two rules (operations) are supported at this time: scale out or scale in the cluster. A maximum and minimum cluster size can be defined.

A rule triggers an alarm when certain conditions for a virtual machine (VM) metric are met. CPU Utilization is the only supported metric for Oracle Java Cloud Service instances created prior to release 17.2.3. For service instances created in release 17.2.3 and beyond, supported metrics are CPU Utilization, Memory Utilization, and Memory.

At least one rule (operation) must be defined to enable auto scaling for a service instance. If you define both rules (operations), make sure the conditions do not conflict each other.

See About Automatic Scaling in Administering Oracle Java Cloud Service.

Consider the following when enabling auto scaling:

  • Like scaling on-demand, a backup of the service instance is automatically initiated before a scaling operation is performed. Be sure to plan your Oracle Cloud storage accordingly before you enable an auto scaling policy.
  • Auto scaling is not supported on a service instance that is associated with an Oracle Exadata database.
  • Before creating a scaling rule for a BYOL instance (service instance that was created with isBYOL set to true), verify that you have the required Oracle WebLogic Server licenses for the maximum cluster size that you intend to specify in the rule. For the on-premises to Oracle Cloud processor-conversion ratios, see Oracle PaaS and IaaS Universal Credits - Service Descriptions.

Request

Supported Media Types
Path Parameters
Header Parameters
Body ()
The request body defines the auto scaling policy details for the service instance.
Root Schema : autoscalingpolicy-request
Type: object
Show Source
Nested Schema : policies
Type: array
Groups details about the auto scaling policy.
Show Source
Nested Schema : policies-request
Type: object
Show Source
  • alarm
    Groups the conditions for a rule to trigger an alarm.
  • The number of minutes after a scaling activity is completed before any further scaling activities can start. A valid value is a positive integer in the range of 30 to 300.

    If the alarm is still active after the cool down period, the scaling activity is repeated. The process continues until the alarm is no longer active, or the maximum or minimum cluster size is reached.

  • Maximum cluster size supported by the service instance. Required and valid only for a ScaleOut rule.
  • Minimum cluster size supported by the service instance. Required and valid only for a ScaleIn rule.
  • The scaling operation to perform when the alarm is triggered. At least one scaling operation must be defined in the policy. Only scale out and scale in are supported at this time. Valid values: scaleOut, scaleIn
Nested Schema : alarm
Type: object
Groups the conditions for a rule to trigger an alarm.
Show Source
  • Whether auto scaling is to be performed when an alarm rule is breached on all VM instances or on any of the VM instances. Valid values:ALL, ANY
  • The arithmetic operation to use when comparing the specified statistic and threshold values. Valid values: GreaterThanOrEqualToThreshold (for scale out), LessThanOrEqualToThreshold (for scale in)
  • Name of the metric set in the alarm. Supported values are:
    • CPUUtilization - The unit of measurement is percent.
    • MemoryUtilization - The unit of measurement is percent. Oracle Java Cloud Service instances created prior to release 17.2.3 do not support this metric.
    • Memory - The unit of measurement is GB. Oracle Java Cloud Service instances created prior to release 17.2.3 do not support this metric.

    If you are defining both the scale out and scale in operations in a policy, the same metric must be specified for each operation.

  • Unit of measurement for the alarm's associated metric. Valid values: percent, GB
  • The consecutive number of times data is compared for the given metric. A valid value is a positive integer in the range of 1 to 24.
  • The interval in minutes when data is compared for the given metric. A valid value is a positive integer in the range of 5 to 60.
  • The statistic to apply to the alarm's associated metric. Valid values: AVG, MIN, MAX
  • The value against which the given statistic is compared. A valid value can be a positive integer or float, in the range of 1 to 100 (for a percent value), and between 1 to 240 (for a GB value).
Back to Top

Response

Supported Media Types

202 Response

Accepted.

When done, policy details are returned.

Body ()
Root Schema : autoscalingpolicy-response
Type: object
Show Source
Nested Schema : policies
Type: array
Groups details about the auto scaling policy.
Show Source
Nested Schema : policy-details
Type: object
Show Source
Nested Schema : alarm
Type: object
Groups the conditions for a rule to trigger an alarm.
Show Source

400 Response

Validation failed. See the response for errors from one or more sources. Make the corrections and try again.
Body ()
Root Schema : validationfailed-response
Type: object
Show Source
Nested Schema : errors
Type: array
Groups the error details.
Show Source
Nested Schema : errordetails-response
Type: object
Show Source
Back to Top

Examples

The following example shows how to add an auto scaling policy to an Oracle Java Cloud Service instance, by submitting a POST request on the REST resource using cURL.

Note:

  • The command in this example uses the URL structure https://rest_server_url/resource-path, where rest_server_url is the REST server to contact for your identity domain (or Cloud Account). See Send Requests.

  • In the resource path, the service type ../JaaS/.. is case-sensitive.

cURL Command

curl -i -X POST -u username:password -d @addpolicy.json -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/JaaS/instances/ExampleInstance/autoscaling/policies

Example of Request Body

The following shows an example of the request body in JSON format.

{
    "name": "JCSPolicy",
    "description": "JCS1 Auto Scaling Policy",
    "policies": [
    {
        "operation": "scaleOut",
        "alarm": {
            "metricName": "CPUUtilization",
            "metricUnit": "percent",
            "statistic": "AVG",
            "comparisonOperator": "GreaterThanOrEqualToThreshold",
            "threshold": 80,
            "sampleCount": 3,
            "sampleFrequency": 10,
            "breachedOnInstance": "ALL"
        },
        "coolDownPeriod": 30,
        "maxClusterSize": 4
    },
    {
        "operation": "scaleIn",
        "alarm": {
            "metricName": "CPUUtilization",
            "metricUnit": "percent",
            "statistic": "AVG",
            "comparisonOperator": "LessThanOrEqualToThreshold",
            "threshold": 40,
            "sampleCount": 3,
            "sampleFrequency": "10",
            "breachedOnInstance": "ANY"
        },       
        "coolDownPeriod": 30,
        "minClusterSize": 2
    }
    ]
}

In the example:

  • Automatically scale out up to "maxClusterSize"="4" when "AVG" "CPUUtilization" is "GreaterThanOrEqualToThreshold" "80" "percent" for "3" consecutive periods of "10" minutes on "ALL" VM instances, and wait for "30" minutes of cool down

  • Automatically scale in to "minClusterSize"="2" when "AVG" "CPUUtilization" is "LessThanOrEqualToThreshold" "40" "percent" for "3" consecutive periods of "10" minutes on "ANY" VM instance, and wait for "30" minutes of cool down

The following shows an example using a memory-based metric:

{
    "name": "JCS2Policy",
    "description": "JCS2 Auto Scaling Policy",
    "policies": [
    {
        "operation": "scaleOut",
        "alarm": {
            "metricName": "Memory",
            "metricUnit": "GB",
            "statistic": "AVG",
            "comparisonOperator": "GreaterThanOrEqualToThreshold",
            "threshold": 5.2,
            "sampleCount": 1,
            "sampleFrequency": 5,
            "breachedOnInstance": "ANY"
        },
        "coolDownPeriod": 30,
        "maxClusterSize": 2
    },
    {
        "operation": "scaleIn",
        "alarm": {
            "metricName": "Memory",
            "metricUnit": "GB",
            "statistic": "AVG",
            "comparisonOperator": "LessThanOrEqualToThreshold",
            "threshold": 4.9,
            "sampleCount": 1,
            "sampleFrequency": "5",
            "breachedOnInstance": "ANY"
        },       
        "coolDownPeriod": 30,
        "minClusterSize": 1
    }
    ]
}

Example of Response Header

The following shows an example of the response header. 

HTTP/1.1 202 Accepted
Date: Thu, 19 May 2016 00:53:16 GMT
Content-Length: 0
Content-Type: application/json

Example of Response Body

The following is an example of the response returned in JSON format.

{
    "name": "JCSPolicy",
    "description": "JCS1 Auto Scaling Policy",
    "policies": [
    {
        "operation": "scaleOut",
        "alarm": {
            "metricName": "CPUUtilization",
            "metricUnit": "percent",
            "statistic": "AVG",
            "comparisonOperator": "GreaterThanOrEqualToThreshold",
            "threshold": "80",
            "sampleCount": "3",
            "sampleFrequency": "10",
            "breachedOnInstance": "ALL"
        },
        "coolDownPeriod": "30",
        "maxClusterSize": "4"
    },
    {
        "operation": "scaleIn",
        "alarm": {
            "metricName": "CPUUtilization",
            "metricUnit": "percent",
            "statistic": "AVG",
            "comparisonOperator": "LessThanOrEqualToThreshold",
            "threshold": "40",
            "sampleCount": "3",
            "sampleFrequency": "10",
            "breachedOnInstance": "ANY"
        },
        "coolDownPeriod": "30",
        "minClusterSize": "2"
    }
    ],
    "version": 1,
    "status": "Active",
    "startTime": "2016-05-19T07:28:54.422+0000"
}

Example of Response Body (validation failed)

The following shows an example of the response returned in JSON format when there are validation errors in the policy.

{
    "status": "Bad Request",
    "errors": [
    {
        "detail": "[statistic] is invalid, valid values are [AVG,MIN,MAX].",
        "source": "statistic"
    },
    {
        "detail": "[threshold] is invalid, it should be positive integer in the range of [1-100].",
        "source": "threshold"
    }
    ]
}
Back to Top