Create an Auto Scaling Policy
/paas/api/v1.1/instancemgmt/{identityDomainId}/services/JaaS/instances/{serviceId}/autoscaling/policies
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 totrue
), 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
- application/json
-
identityDomainId: string
Identity domain ID for the Oracle Java Cloud Service account.
-
serviceId: string
Name of the Oracle Java Cloud Service instance.
-
Authorization: string
Base64 encoded user name and password separated by a colon or OAuth access token obtained from Oracle Identity Cloud Service. See Authenticate.
-
X-ID-TENANT-NAME: string
Identity domain ID for the Oracle Java Cloud Service account.
object
-
description(optional):
string
Description of the auto scaling policy.
-
name(optional):
string
Name of the auto scaling policy. If no name is specified, the default name is the service instance name.
-
policies:
array policies
Groups details about the auto scaling policy.
object
-
alarm:
object alarm
Groups the conditions for a rule to trigger an alarm.
-
coolDownPeriod:
integer
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.
-
maxClusterSize:
integer
Maximum cluster size supported by the service instance. Required and valid only for a
ScaleOut
rule. -
minClusterSize:
integer
Minimum cluster size supported by the service instance. Required and valid only for a
ScaleIn
rule. -
operation:
string
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
object
-
breachedOnInstance:
string
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
-
comparisonOperator:
string
The arithmetic operation to use when comparing the specified
statistic
andthreshold
values. Valid values:GreaterThanOrEqualToThreshold
(for scale out),LessThanOrEqualToThreshold
(for scale in) -
metricName:
string
Name of the metric set in the alarm. Supported values are:
CPUUtilization
- The unit of measurement ispercent
.MemoryUtilization
- The unit of measurement ispercent
. Oracle Java Cloud Service instances created prior to release 17.2.3 do not support this metric.Memory
- The unit of measurement isGB
. 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.
-
metricUnit:
string
Unit of measurement for the alarm's associated metric. Valid values:
percent
,GB
-
sampleCount:
integer
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.
-
sampleFrequency:
integer
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.
-
statistic:
string
The statistic to apply to the alarm's associated metric. Valid values:
AVG
,MIN
,MAX
-
threshold:
number
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 apercent
value), and between 1 to 240 (for aGB
value).
Response
- application/json
202 Response
When done, policy details are returned.
object
-
description(optional):
string
Description of the auto scaling policy.
-
message(optional):
string
For example:
Rule is Active
-
name(optional):
string
Name of the auto scaling policy. The default name is the service instance name.
-
policies(optional):
array policies
Groups details about the auto scaling policy.
-
startTime(optional):
string
Date and time the auto scaling policy was created or updated.
-
status(optional):
string
State of the auto scaling policy.
-
version(optional):
string
Version of the auto scaling policy.
object
-
alarm(optional):
object alarm
Groups the conditions for a rule to trigger an alarm.
-
coolDownPeriod(optional):
integer
The number of minutes after a scaling activity is completed before any further scaling activities can start.
-
maxClusterSize(optional):
integer
Maximum cluster size supported by the service instance when scaling out.
-
minClusterSize(optional):
integer
Minimum cluster size supported by the service instance when scaling in.
-
operation(optional):
string
The scaling operation to perform when the alarm is triggered. For example:
scaleOut
,scaleIn
object
-
breachedOnInstance(optional):
string
Whether auto scaling is to be performed when an alarm rule is breached on all VM instances or on any of the VM instances. For example:
ALL
,ANY
-
comparisonOperator(optional):
string
Arithmetic operation to use when comparing the specified
statistic
andthreshold
values. For example:GreaterThanOrEqualToThreshold
,LessThanOrEqualToThreshold
-
metricName(optional):
string
Name of the metric set in the alarm. For example:
CPUUtilization
-
metricUnit(optional):
string
Unit of measurement for the alarm's associated metric. For example:
percent
-
sampleCount(optional):
integer
The consecutive number of times data is compared for the given metric.
-
sampleFrequency(optional):
integer
The interval in minutes when data is compared for the given metric.
-
statistic(optional):
string
The statistic to apply to the alarm's associated metric. For example:
AVG
,MIN
,MAX
-
threshold(optional):
number
The value against which the given
statistic
is compared.
400 Response
object
-
errors(optional):
array errors
Groups the error details.
-
status(optional):
string
Description of the operation status. For example:
Bad Request
object
-
detail(optional):
string
Error detail.
-
source(optional):
string
Name of the alarm attribute that is causing the error. For example:
threshold
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
, whererest_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" } ] }