1. Oracle Java Cloud Service REST APIREST API for Oracle Java Cloud Service
  2. Use Cases
  3. Scaling a Service Instance (old path)

Scaling a Service Instance (old path)

You can use the REST API to scale an Oracle Java Cloud Service instance on-demand, as described in the following procedures.

Note:

  • This topic is applicable only to Oracle Cloud Machine.

  • The cURL command examples use the URL structure https://rest_server_url/resource-path, where rest_server_url is the REST server to contact for your identity domain. See Send Requests.

Specifically, you can scale the following Oracle Java Cloud Service resources:

  • Cluster: Add or remove nodes, as described below in Scaling a Cluster

  • Administration Server or Managed Server node: Change the compute shape or add additional storage (you cannot remove storage), as described below in Scaling a Node

  • Coherence data tier: Add or remove capacity units, which is not described in this use case; see instead Scaling the Coherence Data Tier of a Service Instance

You can monitor the health of your Oracle Java Cloud Service instance to determine when to scale it, as described in Monitoring a Service Instance.

Consider the following before scaling:

  • Scaling is not supported by Oracle Java Cloud Service - Virtual Image instances. For Oracle Java Cloud Service instances based on WebLogic Server Standard Edition, scaling a node is supported; however, scaling a cluster is not supported.

  • Scaling down a node might be blocked when scaling down a service instance that has a large memory shape and a very high value set for the initial Java heap size for a Managed Server JVM. See the ignoreManagedServerHeapError request parameter in Scale a Node before you scale down such a service instance.

  • When scaling out the cluster on a service instance that uses IP reservations, you must use the query parameter ?ipReservation=ip_reservation_name to assign a reserved IP address to the new node.

  • (Not available on Oracle Cloud Machine) If you are scaling out a service instance provisioned in an account where regions are not supported and your instance uses an Oracle Exadata database, 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 one or more IP reservations. You must obtain IP reservations for the Managed Servers you are going to add; you will not be able to scale out the instance without IP reservations. The number of IP reservations you need corresponds to the number of Managed Server nodes you want to add to the cluster.

Scaling a Cluster

To scale a cluster:

  1. Before scaling a cluster, review the Managed Servers that are currently defined.

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (GET).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    For more information, see View All Managed Servers.

    The following shows an example of the response body in JSON format. In this example, there is one Managed Server.

    {
    "servers":[
    {
        "clusterName":"ExampleI_cluster",
        "name":"ExampleI_server_1",
        "shape":"oc3",
        "nodeType":"WLS",
        "isAdmin":true,
        "hostname":"123.456.789.123",
        "status":"Ready",
        "storageAllocated":74752,
        "creationDate":"Jun 7, 2016 9:22:43 PM"
    }
    ],
    "serverInProgress":[]
}

  2. Scale out the service instance to add another Managed Server to the existing cluster, ExampleI_cluster. 

    curl -i -X POST -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers/ExampleI_cluster

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (POST).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    Optionally, you can specify a new cluster name and set the createClusterIfMissing query parameter to true. This will cause a new cluster to be created during the scale-out operation, and the new node to be added to the new cluster.

    When scaling out the cluster on a service instance that uses IP reservations, you must use the query parameter ipReservation=ip_reservation_name in the request to assign a reserved IP address to the new node. For example: 

    curl -i -X POST -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers/ExampleI_cluster?ipReservation=ipres02

    For more information about scaling out, see Scale Out a Cluster.

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

    {
    "status": "New",
    "details": {
        "message": "JAAS-SCALING-037: Scale out Job (ID: 866230) for service [ExampleInstance] in cluster [ExampleI_cluster] submitted",
        "jobId": "866230"
    }
}

  3. Check the status of the scaling operation using the job ID returned in the response in step 2. For more information, see View the Status of a Server Operation by Job ID. 

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers/history/job/866230

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (GET).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response body. The status is RUNNING, which means the scale out operation is still in progress. The status will change to SUCCEED upon a successful scale out. 

    {
    "canonicalUri":null,
    "actLog":
    {
        "activityLogId":484143,
        "serviceId":25421,
        "operation":
        {
            "operationId":25421,
            "operationType":"SCALE_OUT"
        },
        "status":"RUNNING",
        "startDate":"Jul 27, 2016 9:17:03 PM",
        "endDate":null,
        "identityDomain":"ExampleIdentityDomain",
        "serviceName":"ExampleInstance",
        "serviceType":"jaas",
        "hostName":"exampleinstance-wls-2",
        "serverName":null,
        "serverType":"WLS",
        "jobId":866230,
        "summaryMessage":"ExampleI_server_2",
        "authDomain":"ExampleIdentityDomain",
        "authUser":"username",
        "initiatedBy":"USER",
        "messages":[
        {
            "activityMessageId":776201,
            "activityDate":"Jul 27, 2016 9:17:03 PM",
            "stepName":"NEW",
            "message":"Activity Submitted"
        },
        {
            "activityMessageId":776202,
            "activityDate":"Jul 27, 2016 9:17:08 PM",
            "stepName":"RUNNING",
            "message":"Activity Started"
        },
        {
            "activityMessageId":776203,
            "activityDate":"Jul 27, 2016 9:17:12 PM",
            "stepName":"RUNNING",
            "message":"Scaling job for service [ExampleInstance] in cluster [ExampleI_cluster] with factor [1] is prepared."
        },
        ...
        ...
        {
            "activityMessageId":776227,
            "activityDate":"Jul 27, 2016 9:27:40 PM",
            "stepName":"RUNNING",
            "message":"Orchestration is in ready state, new VM is up for server [ExampleI_server_2]"
        },
        {
            "activityMessageId":776226,
            "activityDate":"Jul 27, 2016 9:27:40 PM",
            "stepName":"RUNNING",
            "message":"Started the required compute resources for WebLogic Server managed server [ExampleI_server_2]..."
        },
        {
            "activityMessageId":776228,
            "activityDate":"Jul 27, 2016 9:27:40 PM",
            "stepName":"RUNNING",
            "message":"Completed submitting child job for checking managed server configuration "
        }
        ],
        "resourceType":"VM",
        "resourceId":22719,
        "resourceName":"exampleinstance-wls-2",
        "payload":null
    },
    "messages":[{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{},{}]
}

  4. After the scaling operation is completed, review the list of Managed Servers to confirm the new Managed Server has been added to the cluster.

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers

    The following shows an example of the response body in JSON format. Notice that ExampleI_server_2 is added to the list.

    Note: By default, the name of the Managed Server is generated from the first eight characters of the domain name ("domainName"), using the following format: first8charsOfDomainName_server_n, where n starts with 1 and is incremented by 1 for each additional Managed Server to ensure each name is unique. 

    {
    "servers":[
    {
        "clusterName":"ExampleI_cluster",
        "name":"ExampleI_server_1",
        "shape":"oc3",
        "nodeType":"WLS",
        "isAdmin":true,
        "hostname":"123.456.789.123",
        "status":"Ready",
        "storageAllocated":74752,
        "creationDate":"Jun 7, 2016 9:22:43 PM"
    },
    {
        "clusterName":"ExampleI_cluster",
        "name":"ExampleI_server_2",
        "shape":"oc3",
        "nodeType":"WLS",
        "isAdmin":false,
        "hostname":"exampleinstance-wls-2",
        "status":"Ready",
        "reservedIp":"",
        "jobId":"866230",
        "storageAllocated":54272,
        "creationDate":"Jul 27, 2016 9:19:21 PM"
    }
    ],
    "serverInProgress":[]
}

    If you scaled out a service instance that uses IP reservations, the IP reservation name and address are also returned for each Managed Server in the cluster. For example:

    {
   "servers":[
   {
      "clusterName":"ExampleI_cluster",
      "name":"ExampleI_server_1",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":true,
      "hostname":"123.45.6.78",
      "status":"Ready",
      "reservedIpName":"ipres01",
      "reservedIpAddress":"10.222.333.17",
      "storageAllocated":47000,
      "creationDate":"May 11, 2016 3:58:40 PM"
   },
   {
      "clusterName":"ExampleI_cluster"",
      "name":"ExampleI_server_2",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"exampleinstance-wls-2",
      "status":"Ready",
      "reservedIpName":"ipres02",
      "reservedIpAddress":"10.222.343.121",
      "storageAllocated":27000,
      "creationDate":"May 11, 2016 3:58:43 PM"
   }
   ],
   "serverInProgress:[]
}

  5. Scale in the service instance by removing the Managed Server that was added in Step 2, ExampleI_server_2. 

    curl -i -X DELETE -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers/ExampleI_server_2

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (DELETE).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    See Scale In a Cluster for more information about scaling in.

    If you are scaling in a service instance that uses IP reservations, when the Managed Server node is removed, the IP reservation associated with the node is released but not deleted.

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

    {
   "status": "New",
   "details": {
      "message": "JAAS-SCALING-044: Scaling in Job (ID: 20) server name [ExampleI_server_2] submitted for service [ExampleInstance]",
      "jobId": "20"
   }
}

  6. After the scaling operation is completed, review the list of Managed Servers to confirm the Managed Server has been removed.

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers

    The following shows an example of the response body in JSON format. Notice ExampleI_server_2 has been removed. 

    {
    "servers":[
    {
        "clusterName":"ExampleI_cluster",
        "name":"ExampleI_server_1",
        "shape":"oc3",
        "nodeType":"WLS",
        "isAdmin":true,
        "hostname":"123.456.789.123",
        "status":"Ready",
        "storageAllocated":74752,
        "creationDate":"Jun 7, 2016 9:22:43 PM"
    }
    ],
    "serverInProgress":[]
}

Scaling a Node

To scale a node:

  1. Before scaling a node, review the Managed Servers that are currently defined.

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (GET).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    For more information, see View All Managed Servers.

    The following shows an example of the response body in JSON format. In this example, there are three Managed Servers currently defined.

    {
   "servers":[
   {
      "clusterName":"ExampleI_cluster",
      "name":"ExampleI_server_1",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":true,
      "hostname":"123.45.6.78",
      "status":"Ready",
      "storageAllocated":47000,
      "creationDate":"Jun 3, 2014 8:19:08 AM"
   },
   {
      "clusterName":"ExampleI_cluster"",
      "name":"ExampleI_server_2",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"exampleinstance-wls-2",
      "status":"Ready",
      "storageAllocated":27000,
      "creationDate":"Jun 3, 2014 8:19:30 AM"
   },
   {
      "clusterName":"ExampleI_cluster",
      "name":"ExampleI_server_3",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"exampleinstance-wls-3",
      "status":"Ready",
      "jobId":"17",
      "storageAllocated":27000,
      "creationDate":"Jun 3, 2014 8:19:30 AM"
   }],
   "serverInProgress":[]
}

  2. In the output returned from step 1, note that ExampleI_server_1 has the following compute shape and storage allocation:

    • Compute shape: OC3

    • Storage: 47000 MBs

    You will scale up the Managed Server, ExampleI_server_1, so that it can handle more load, as follows:

    • Compute shape: OC4

    • Storage: Add 1 gigabyte (GB) of additional storage to the backup storage volume

      Note: You can add additional storage to the backup storage volume on the Administration Server node only. In this example, ExampleI_server_1 hosts the Administration Server.

  3. First, you need to create a JSON document, scale.json, that defines the details of a scale up operation. 

    {
    "additionalStorage" : "1",
    "scalingVolume" : "backup",
    "shape" : "oc4"
}

    For more information about the request attributes, see Scale a Node.

  4. Scale up the Managed Server, ExampleI_server_1, passing the JSON document defined in step 3. 

    curl -i -X PUT -u username:userPassword1! -d @scale.json -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/ExampleI_server_1

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (PUT).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to identify the content type as application/json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    For more information, see Scale a Node.

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

    {
   "status": "New",
   "details": {
      "message": "scaleup.job.submitted",
      "jobId": "22"
   }
}

  5. Check the status of the scaling operation using the job ID returned in the response in step 3. For more information, see View the Status of a Server Operation by Job ID. 

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers/history/job/22

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (GET).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

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

    {
   "actLog":
   {
      "activityLogId":2021,
      "serviceId":109,
      "operation":{
         "operationId":109,
         "operationType":"SCALE_UP"
      },
      "status":"RUNNING",
      "startDate":"Jul 30, 2015 8:48:04 PM",
      "endDate":null,
      "identityDomain":"ExampleIdentityDomain",
      "serviceName":"ExampleInstance",
      "hostName":null,
      "serverName":null,
      "serverType":null,
      "jobId":12301,
      "summaryMessage":"SCALE_UP",
      "messages":[
      {
         "activityMessageId":2350,
         "activityDate":"Jul 30, 2015 8:48:04 PM",
         "stepName":"NEW",
         "message":"Activity Submitted"
      },
      {
         "activityMessageId":2351,
         "activityDate":"Jul 30, 2015 8:48:13 PM",
         "stepName":"RUNNING",
         "message":"Activity Started"
      },
      {
         "activityMessageId":2352,
         "activityDate":"Jul 30, 2015 8:48:31 PM",
         "stepName":"RUNNING",
         "message":"Stopping service member [\ExampleI_server_1] of service [ExampleInstance]..."
       }]
   },
   "messages":[{},{},{}]
}

  6. After the scale up operation is completed, review the list of Managed Severs to confirm ExampleI_server_1 has been scaled up. 

    curl -i -X GET -u username:userPassword1! -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance/servers

    Specify the following options on the cURL command line:

    • -i option to include the HTTP header in the output. This option is optional.

    • -X option to indicate the type of request (GET).

    • -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.

    • -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response body in JSON format. In this example, ExampleI_server_1 has been scaled up. 

    {
   "servers":[
   {
      "clusterName":"ExampleI_cluster",
      "name":"ExampleI_server_1",
      "shape":"oc4",
      "nodeType":"WLS",
      "isAdmin":true,
      "hostname":"123.45.6.78",
      "status":"Ready",
      "storageAllocated":48024,
      "creationDate":"Jun 3, 2014 8:19:08 AM"
   },
   {
      "clusterName":"ExampleI_cluster"",
      "name":"ExampleI_server_2",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"exampleinstance-wls-2",
      "status":"Ready",
      "storageAllocated":27000,
      "creationDate":"Jun 3, 2014 8:19:30 AM"
   },
   {
      "clusterName":"ExampleI_cluster"",
      "name":"ExampleI_server_3",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"exampleinstance-wls-3",
      "status":"Ready",
      "storageAllocated":27000,
      "creationDate":"Jun 3, 2014 8:19:30 AM"
   }],
   "serverInProgress":[]
}

  7. Repeat steps 4 through 6 to scale up the other nodes in the cluster and ensure that they are all equivalent.