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

Scale Out a Service Instance

post

/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/servers

Scales out an Oracle Java Cloud Service instance. You can:
  • 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
Scaling is not supported by Oracle Java Cloud Service - Virtual Image instances (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

Supported Media Types
Path Parameters
Header Parameters
Body ()
The request body defines the details of the scale out request.
Root Schema : scaleout-postrequestm
Type: object
Show Source
  • 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.
Nested Schema : components
Type: object
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.
Show Source
Nested Schema : OTD
Type: object
Properties for the Oracle Traffic Director (OTD) component.
Show Source
  • ipReservations
    A single IP reservation name for the load balancer node you are adding.
  • Number of user-managed load balancer nodes to add to the OTD component.

    Valid values are 0 and 1.

    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 use clusters array.

Nested Schema : WLS
Type: object
Properties for the Oracle WebLogic Server (WLS) component.
Show Source
  • 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 to true.

  • 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.

  • Flag that specifies whether to add the new node to a new cluster. Set the value to true to create a new cluster, and use clusterName 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
    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.

  • Number of servers to add to the WLS application cluster. Valid values are 0 and 1. This might change in the future.

    managedServerCount must be 0 (zero) if you want to use clusters array.

Nested Schema : ipReservations
Type: array
A single IP reservation name for the load balancer node you are adding.
Show Source
Nested Schema : clusters
Type: array
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.

Show Source
  • clusters-scalearray
    Properties for the WLS application or caching (data grid) cluster. Only one cluster can be scaled out in a single request.

    managedServerCount and otdServerCount must be 0 (zero) if you want to use clusters array.

Nested Schema : ipReservations
Type: array
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.

Show Source
Nested Schema : clusters-scalearray
Type: object
Properties for the WLS application or caching (data grid) cluster. Only one cluster can be scaled out in a single request.

managedServerCount and otdServerCount must be 0 (zero) if you want to use clusters array.

Show Source
  • 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 to true.
    • 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.

  • Number of servers to add.

    • For APPLICATION_CLUSTER - Valid values are 0 and 1 when scaling out. This might change in the future.
    • For CACHING_CLUSTER - Use a number from 1 to 32 only. The serverCount limit is based on the VM (cluster size) limit of four and the serversPerNode 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 a serverCount of one when scaling out, the actual number that will be added is four.

  • 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.

  • 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 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.

Back to Top

Response

Supported Media Types

202 Response

Accepted. The Location header returns a URI that can be used to view the job status. See View the Status of an Operation by Job Id.
Body ()
Root Schema : accepted-responsem
Type: object
The response body contains information about the operation. It can include an issues array for warning messages.
Show Source
Nested Schema : details
Type: object
Groups details of the operation.
Show Source
Nested Schema : issues
Type: array
Groups strings of warning messages, if any.
Show Source

400 Response

Bad Request. Returned if the request payload contains bad or missing details.

See Status Codes for information about other possible HTTP status codes.

Body ()
Root Schema : badrequest-responsem
Type: object
The response body contains information about the request. It can include an issues array for validation error messages.
Show Source
Nested Schema : details
Type: object
Groups details of the request.
Show Source
Nested Schema : issues
Type: array
Groups strings of validation error messages, if any.
Show Source
Back to Top

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.]"
        ]
    }
}
Back to Top