Scale Out a Service Instance
/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/servers
- Add one node to an existing WLS application cluster
- Add a new WLS application cluster
- Add a secondary OTD node (if Oracle Traffic Director is provisioned as the user-managed load balancer)
- Add one or more nodes to an existing WLS caching (data grid) cluster
- Add a WLS caching (data grid) cluster, only if a caching cluster was not created in the initial provisioning of the service instance
BASIC
service level).Scaling a cluster is not supported by Oracle Java Cloud Service instances based on WebLogic Server Standard Edition.
Before scaling out 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 OCPUs of the new node. For the processor conversion ratios and license requirements, refer to the document titled Oracle PaaS and IaaS Universal Credits Service Descriptions that is available from Frequently Asked Questions: Oracle BYOL to PaaS.
If you are scaling out a service instance that uses IP reservations (application cluster nodes only), make sure you use only reserved IPs that are created in the same region. See IP Reservations REST Endpoints for information about how to find unused IP reservations and, if needed, create new IP reservations.
On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer: Before scaling out a service instance that uses an Oracle Database Exadata Cloud Service deployment in an account where regions are not supported, you must obtain IP reservations for the Managed Servers you are going to add; you will not be able to scale out the cluster without IP reservations. See the My Oracle Support document titled How to Request Authorized IPs for Provisioning a Java Cloud Service with Database Exadata Cloud Service (MOS Note 2163568.1) to submit a request for IP reservations.
On Oracle Cloud Infrastructure and Oracle Cloud Infrastructure Classic: Many of the administration and lifecycle operations that you run for an Oracle Java Cloud Service instance affect the billing for the infrastructure resources that are used by the instance. See Effect of Lifecycle and Administration Operations on Billing.
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
-
components:
object components
Groups properties for the Oracle WebLogic Server component (
WLS
) or the Oracle Traffice Director (OTD
) component. Only one component type can be scaled at a time.
object
WLS
) or the Oracle Traffice Director (OTD
) component. Only one component type can be scaled at a time.-
OTD(optional):
object OTD
Properties for the Oracle Traffic Director (OTD) component.
-
WLS(optional):
object WLS
Properties for the Oracle WebLogic Server (WLS) component.
object
-
ipReservations(optional):
array ipReservations
A single IP reservation name for the load balancer node you are adding.
-
otdServerCount:
integer
Number of user-managed load balancer nodes to add to the OTD component.
Valid values are
0
and1
.Note:
- OTD must already have been provisioned.
- A maximum of two OTD nodes is allowed. No nodes can be added when there are already two nodes.
otdServerCount
must be 0 (zero) if you want to useclusters
array.
object
-
clusterName(optional):
string
Name of the WLS application cluster to scale out. This attribute is ignored if
clusters
array is used.The cluster name can be an existing cluster name or a new name. To create a new cluster,
createClusterIfMissing
must be set totrue
. -
clusters(optional):
array clusters
Groups properties of the cluster to scale.
This attribute is optional for the WLS application cluster. You must, however, use the
clusters
array to scale out the existing caching (data grid) cluster. -
createClusterIfMissing(optional):
boolean
Flag that specifies whether to add the new node to a new cluster. Set the value to
true
to create a new cluster, and useclusterName
to specify a cluster name that does not already exist in the domain.Note: You cannot add a second caching (data grid) cluster if one already exists. You can have up to eight application clusters.
-
ipReservations(optional):
array ipReservations
This attribute is not applicable to Oracle Java Cloud Service instances on Oracle Cloud Infrastructure.
This attribute is only applicable when adding a Managed Server node to a WLS application cluster.
A single IP reservation name for the Managed Server node you are adding.
-
managedServerCount(optional):
integer
Number of servers to add to the WLS application cluster. Valid values are
0
and1
. This might change in the future.managedServerCount
must be 0 (zero) if you want to useclusters
array.
array
array
This attribute is optional for the WLS application cluster. You must, however, use the clusters
array to scale out the existing caching (data grid) cluster.
-
Array of:
object clusters-scalearray
Properties for the WLS application or caching (data grid) cluster. Only one cluster can be scaled out in a single request.
managedServerCount
andotdServerCount
must be 0 (zero) if you want to useclusters
array.
array
This attribute is only applicable when adding a Managed Server node to a WLS application cluster.
A single IP reservation name for the Managed Server node you are adding.
object
managedServerCount
and otdServerCount
must be 0 (zero) if you want to use clusters
array.
-
clusterName(optional):
string
Name of the existing WLS application or caching (data grid) cluster to scale out.
You can create a new cluster by specifying a cluster name that does not already exist in the domain. The node will then be added to the new cluster. Note the following when creating a new cluster:
createClusterIfMissing
must be set totrue
.- A service instance can have up to eight application clusters.
- You cannot add a second caching (data grid) cluster. You can create the caching (data grid) cluster only if a caching cluster was not configured in the initial provisioning of the service instance.
-
serverCount(optional):
integer
Number of servers to add.
- For
APPLICATION_CLUSTER
- Valid values are0
and1
when scaling out. This might change in the future. - For
CACHING_CLUSTER
- Use a number from 1 to 32 only. TheserverCount
limit is based on the VM (cluster size) limit of four and theserversPerNode
limit of eight.Note: The actual server number is rounded up to fill the number of nodes required to scale out the existing caching cluster or add a new one (only if a caching cluster does not already exist). For example, if
serversPerNode
was four when the service instance was created, and you specify aserverCount
of one when scaling out, the actual number that will be added is four.
- For
-
serversPerNode(optional):
integer
This attribute is required only if you are adding a cluster of type
CACHING_CLUSTER
to the service instance (when a caching cluster does not already exist).Number of JVMs to start on each VM (node) in the caching data grid cluster.
Use a number from 1 to 8 only. The default value is
1
. -
shape(optional):
string
This attribute can be specified only when you create a new cluster.
Desired compute shape for the cluster nodes.
A shape defines the number of Oracle Compute Units (OCPUs) and amount of memory (RAM).
On Oracle Cloud Infrastructure, VM.Standard and BM.Standard shapes, and VM.Standard.E3.Flex, VM.Standard.E4.Flex, and VM.Standard3.Flex shapes are supported.
You can specify the number of OCPUs for the flex shapes. The maximum number of OCPUs for VM.Standard.E3.Flex and VM.Standard.E4.Flex is 64 OCPUs, and the maximum number of OCPUs for VM.Standard3.Flex is 32 OCPUs. The amount of memory is calculated based on the number of OCPUs as n*16, where n is the number of OCPUs.
Available shapes vary depending on your Oracle Cloud account and the region in which you provision a service instance.
See Compute Shapes in the Oracle Cloud Infrastructure documentation.
On Oracle Cloud Infrastructure Classic, valid shapes include:
- oc3: 1 OCPU, 7.5 GB memory
- oc4: 2 OCPUs, 15 GB memory
- oc5: 4 OCPUs, 30 GB memory
- oc6: 8 OCPUs, 60 GB memory
- oc7: 16 OCPUs, 120 GB memory
- oc8: 24 OCPUs, 180 GB memory
- oc9: 32 OCPUs, 240 GB memory
- oc1m: 1 OCPU, 15 GB memory
- oc2m: 2 OCPUs, 30 GB memory
- oc3m: 4 OCPUs, 60 GB memory
- oc4m: 8 OCPUs, 120 GB memory
- oc5m: 16 OCPUs, 240 GB memory
- oc8m: 24 OCPUs, 360 GB memory
- oc9m: 32 OCPUs, 480 GB memory
Note: Some shapes might not be available in a region.
-
type(optional):
string
Type of cluster. Valid values include:
APPLICATION_CLUSTER
- Application cluster (default). This is the WebLogic cluster that will run the service applications, which are accessible via the user-managed load balancer resource (OTD) or the Oracle-managed load balancer.CACHING_CLUSTER
- Caching (data grid) cluster. This is the WebLogic cluster for Coherence storage.
Response
- application/json
202 Response
Location
header returns a URI that can be used to view the job status. See View the Status of an Operation by Job Id.object
issues
array for warning messages.-
details:
object details
Groups details of the operation.
object
-
issues(optional):
array issues
Groups strings of warning messages, if any.
-
jobId:
string
Job ID for the operation. Not available if the response status code is 400.
-
message:
string
System message that describes the operation.
400 Response
See Status Codes for information about other possible HTTP status codes.
object
issues
array for validation error messages.-
details(optional):
object details
Groups details of the request.
object
-
issues(optional):
array issues
Groups strings of validation error messages, if any.
-
message(optional):
string
System message that describes the request.
Examples
The following example shows how to scale out 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.
cURL Command
curl -i -X POST -u username:password -d @scaleout.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/servers
Example of Request Body
The following shows an example of the request body where the new server is added to a new application tier cluster.
{
"components": {
"WLS": {
"clusters": [
{
"clusterName": "ExampleCluster2",
"type": "APPLICATION_CLUSTER",
"serverCount": 1
}],
"createClusterIfMissing": true
}
}
}
The following shows an example of the request body where the new server is added to an existing application tier cluster.
{
"components": {
"WLS": {
"clusters": [
{
"clusterName": "ExampleCluster1",
"type": "APPLICATION_CLUSTER",
"serverCount": 1
}],
"createClusterIfMissing": false
}
}
}
The following shows an example of the request body where the existing Coherence caching cluster is scaled out.
{
"components": {
"WLS": {
"clusters": [
{
"clusterName": "ExampleDGCluster",
"type": "CACHING_CLUSTER",
"serverCount": 3
}],
"createClusterIfMissing": false
}
}
}
The following shows an example of the request body for scaling out the OTD component.
{
"components": {
"OTD": {
"otdServerCount": 1
}
}
}
The following shows an example of the request body where an IP reservation name is specified when scaling out the WLS component.
{
"components": {
"WLS": {
"ipReservations": ["ipres03"],
"clusters": [
{
"clusterName": "ExampleCluster1",
"type": "APPLICATION_CLUSTER",
"serverCount": 1
},
"createClusterIfMissing": false
}
}
}
The following shows an example of the request body where a Coherence caching cluster is added to an existing service instance (which was created without a datagrid cluster).
{
"components": {
"WLS": {
"clusters": [
{
"clusterName": "ExampleClusterDG",
"type": "CACHING_CLUSTER",
"serverCount": 3,
"serversPerNode": 1
}],
"createClusterIfMissing": true
}
}
}
Example of Response Header
The following shows an example of the response header. The Location
header returns the URI that can be used to view the job status. See View the Status of an Operation by Job Id.
HTTP/1.1 202 Accepted
Date: Sat, 24 Jun 2017 18:32:30 GMT
Transfer-Encoding: chunked
Location: https://rest_server_url/paas/api/v1.1/activitylog/ExampleIdentityDomain/job/171232
Content-Type: application/vnd.com.oracle.oracloud.provisioning.Service+json
Service-URI: https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance
Retry-After: 60
Example of Response Body
The following shows an example of a 202 response returned in JSON format.
{
"details":
{
"message":"Submitted job to scale out service [ExampleInstance] in domain [ExampleIdentityDomain].",
"jobId":"171232"
}
}
The following shows an example of a 400 response.
{
"details": {
"message": "PSM-LCM-03003 Unable to submit request to scale out the service [ExampleInstance]. Check additional validation errors for details.",
"issues": [
"[PSM-LSM-01101 The cluster [BadRequestCluster] specified in the request doesnt exist in service [{1}]. Add createIfNotExist option or specify an existing cluster.]"
]
}
}