1. Oracle Java Cloud Service REST APIREST API for Oracle Java Cloud Service
  2. Use Cases
  3. Scaling the Coherence Data Tier of a Service Instance

Scaling the Coherence Data Tier of a Service Instance

When you scale the Coherence data tier, it means you are adding Managed Servers to or removing Managed Servers from the storage-enabled WebLogic Server cluster of an Oracle Java Cloud Service instance, as described in the following procedure.

Note:

  • This topic is applicable only to Oracle Cloud Machine.

  • The term scaling unit used in the REST API means the same as capacity unit.

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

This section applies only to Oracle Java Cloud Service instances that have Oracle Coherence enabled. During a scaling operation on the Coherence data tier, a specific number of capacity units is added or removed based on the capacity unit count requested and the current capacity unit count for the service instance. The number of VMs and Managed Servers to add or remove is predetermined by the capacity unit definition you declared for the service instance during initial provisioning. For example, if a capacity unit definition manages 3 VMs and 1 Managed Server per VM, a scaling operation either adds or removes 3 VMs and 3 Managed Servers for each capacity unit added or removed. You cannot change the definition of your capacity unit when you scale the Coherence data tier.

The application tier of an Oracle Java Cloud Service instance is scaled independently of the Coherence data tier. See Scaling a Service Instance to scale out or scale in the Managed Servers on the application tier.

To scale the Coherence data tier of an Oracle Java Cloud Service instance:

  1. Before scaling, review the Managed Servers that are currently defined by viewing details of the service instance. 
    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/Example1Instance

    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 a Service Instance.

    The following shows an example of the response body in JSON format. In this example, there is one Managed Server in the Coherence data tier cluster Example1_DGCluster, managed by the capacity unit identified by the Id 18. There is one count of the capacity unit as shown by scalingUnitCount. 

    {
    "service_name" : "Example1Instance",
    "version" : "12cR3",
    "wlsVersion" : "12.1.3.0.xxxxxx",
    "status" : "Running",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description" : "Example, Inc product distribution",
    "identity_domain" : "ExampleIdentityDomain",
    "creation_time": "Mon Sep 19 22:9:23 UTC 2016",
    "last_modified_time": "Mon Sep 19 22:9:21 UTC 2016",
    "created_by":"username",
    "service_uri" : "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/Example1Instance",
    "domain_name" : "Example1_domain",
    "domain_mode" : "PRODUCTION",
    "cluster_name" : "Example1_cluster",
    "num_nodes" : 4,
    "level" : "PAAS",
    "subscription_type" : "MONTHLY",
    "edition" : "SUITE",
    "shape" : "oc3",
    "otd_provisioned" : "yes",
    "otd_shape" : "oc3",
    "otd_storage_size": 40960,
    "service_components": [
    {
      "type": "JDK",
      "version": "1.7.0_xxx"
    },
    {
      "type": "WLS",
      "version": "12.1.3.0.xxxxxx"
    },
    {
      "type": "OTD_JDK",
      "version": "1.7.0_xxx"
    },
    {
      "type": "OTD",
      "version": "11.1.1.9.x"
    }
    ],
    "options": [{
      "type": "datagrid",
      "clusters": [{
        "clusterName": "Example1_DGCluster",
        "scalingUnitCount": 1,
        "scalingUnitName": "BASIC",
        "shape": "oc3",
        "vmCount": 1,
        "jvmCount": 1,
        "heapSize": "4608M",
        "maxScalingUnit": 30,
        "heapIncrements": "4608M",
        "primaryIncrements": "1536M",
        "totalHeap": "4608M",
        "totalPrimary": "1536M",
        "maxHeap": "138240M",
        "maxPrimary": "46080M",
        "scalingUnitInstances": [{
          "servers": [
            {"name": "Example1_server_3_DG"}
          ],
          "scalingUnitInstanceId": 18,
          "status": "Ready"
        }]
      }]
    }],
    "creation_job_id": "295",
    "deletion_job_id": 0,
    "db_info" : "myDBService:1521\/PDB1.exampleidentitydomain.oraclecloud.internal",
    "db_service_name": "myDBService",
    "num_ip_reservations" : 4,
    "wls_admin_url": "https:\/\/192.0.2.0:7002\/console",
    "fmw_control_url": "https:\/\/192.0.2.0:7002\/em",
    "otd_admin_url": "https:\/\/192.0.1.23:8989",
    "sample_app_url": "https:\/\/192.0.1.23\/sample-app\/",
    "content_url" : "http:\/\/192.0.1.23",
    "secure_content_url": "https:\/\/192.0.1.23",
    "wls_deployment_channel_port": 9001,
    "psm_plugin_version": "16.3.5-x-xxx",
    "compute_site_name": "US000_Z00",
    "db_associations": [
    {
        "db_service_name": "myDBService",
        "db_infra": true,
        "db_connect_string": "myDBService:1521\/PDB1.exampleidentitydomain.oraclecloud.internal",
        "pdb_service_name": "PDB1",
        "db_version": "12.1.0.2"
    }]
}
  2. Create a JSON document, scaledgcluster.json , that defines the total number of capacity units you want in the domain.

    In the example shown in the previous step, there is 1 capacity unit, managing 1 VM and 1 Managed Server per VM. If you wish to increase the number of capacity units in the domain by 1, you would define a count of 2 in the JSON document, 2 being the total number of capacity units you want.

    The following shows an example of a request document for a count of 2 capacity units: 

    {
  "scalingUnitCount" : "2"
}

    For information about the REST resource attribute, see Scale a Coherence Data Tier.

  3. Scale out the Coherence data tier of the service instance, passing the JSON document created in step 2. 
    curl -i -X PUT -u username:userPassword1! -d @scaledgcluster.json -H "X-ID-TENANT-NAME:ExampleIdentityDomain" -H "Content-Type:application/vnd.com.oracle.oracloud.datagrid.Service+json" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/Example1Instance/clusters/Example1_DGCluster

    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 define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    • -d option to identify the request document, in JSON format, on the local machine (scaledgcluster.json).

    • -H to identify the content type as application/vnd.com.oracle.oracloud.datagrid.Service+json.

    For more information, see Scale a Coherence Data Tier.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Tues, 20 Sep 2016 23:9:23 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/scale/job/574
Content-Length: 0
Content-Type: application/vnd.com.oracle.oracloud.datagrid.Service+json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/Example1Instance/clusters/Example1_DGCluster
  4. Check the status of the scale request using the resource URI returned in the Location header. 
    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/status/scale/job/574

    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 the Status of a Service Instance Lifecycle Operation.

    The following shows an example of the response document when you view the status of the request.

    The example scales out the cluster by adding one capacity unit consisting of 1 storage-enabled Managed Server.

    {
    "service_name": "Example1Instance",
    "version": "12cR3",
    "wlsVersion": "12.1.3.0.xxxxxx",
    "status": "Running",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description" : "Example, Inc product distribution",
    "identity_domain": "ExampleIdentityDomain",
    "creation_time": "Mon Sep 19 22:9:23 UTC 2016",
    "last_modified_time": "Mon Sep 19 22:9:21 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/Example1Instance",
    "message": [
      "Successfully scaled out cluster [Example1_DGCluster]",
      "Successfully scaled out cluster [Example1_DGCluster]",
      "    Successfully created capacity unit(s)...",
      "    Starting capacity unit...",
      "    Successfully started capacity unit...",
      "    Starting to transfer keys to the datagrid VMs",
      "    Finished transferring keys to datagrid VMs",
      "    Successfully transferred keys to [example1instance-wls-4]",
      "    Checking managed servers...",
      "    Successfully checked managed servers...",
      "    Performing Service Reachability Check (SRC) of Datagrid Managed Servers.",
      "    Successfully completed Service Reachability Check (SRC) of Datagrid Managed Servers.",
      "    Successfully created capacity unit(s)...",
      "    Successfully created capacity unit(s)...",
      "        Configuration check for Host [example1instance-wls-4] containing WebLogic Managed Server(s) [[Example1_server_4_DG]] completed...",
      "        Service Reachabilty Check (SRC) of WebLogic Administration Server completed...",
      "        Service Reachabilty Check (SRC) of WebLogic Managed Server(s) [Example1_server_1, Example1_server_2, Example1_server_3_DG, Example1_server_4_DG] completed..."
    ]
}
  5. When the operation completes and the service instance is running, review the list of Managed Servers to confirm the new Managed Server has been added to the Coherence data tier 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/Example1Instance/servers

    For more information, see View All Managed Servers.

    The following is an example of the response body in JSON format, showing Example1_server_4_DG has been added to the list of storage-enabled Managed Servers.

    Note: By default, the name of a storage-enabled Managed Server is generated from the first eight characters of the domain name, using the following format: first8charsOfDomainName_server_n_DG, where n is a number that is incremented by 1 for each additional Managed Server to ensure each name is unique. 

    {
    "servers": [
    {
      "clusterName":"Example1_cluster",
      "name":"Example1_server_1",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":true,
      "hostname":"12.345.678.999",
      "status":"Ready",
      "reservedIp":"",
      "storageAllocated":73728,
      "creationDate":"19 Sep, 2016 22:09:23 PM"
    },
    {
      "clusterName":"Example1_cluster",
      "name":"Example1_server_2",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"example1instance-wls-2",
      "status":"Ready",
      "reservedIp":"",
      "storageAllocated":53248,
      "creationDate":"19 Sep, 2016 22:09:28 PM"
    },
    {
      "clusterName":"Example1_DGCluster",
      "name":"Example1_server_3_DG",
      "shape":"oc3",
      "nodeType":"DG",
      "isAdmin":false,
      "hostname":"example1instance-wls-3",
      "status":"Ready",
      "reservedIp":"",
      "jobId":"538",
      "storageAllocated":43600,
      "creationDate":"19 Sep, 2016 22:42:59 PM"
    },
    {
      "clusterName":"Example1_DGCluster",
      "name":"Example1_server_4_DG",
      "shape":"oc3",
      "nodeType":"DG",
      "isAdmin":false,
      "hostname":"example1instance-wls-4",
      "status":"Ready",
      "reservedIp":"",
      "jobId":"575",
      "storageAllocated":43600,
      "creationDate":"Sep 20, 20165 23:09:23 PM",
      "createdBy":"username"
    }
    ],
    "serverInProgress":[]
}
  6. Modify the JSON file to specify a ScalingUnitCount of 1 (this will remove one capacity unit from the existing Coherence data tier cluster). Then scale in the Coherence data tier of the service instance by passing the modified JSON document. 
    curl -i -X PUT -u username:userPassword1! -d @scaledgcluster.json -H "X-ID-TENANT-NAME:ExampleIdentityDomain" -H "Content-Type:application/vnd.com.oracle.oracloud.datagrid.Service+json" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/Example1Instance/clusters/Example1_DGCluster

    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 define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    • -d option to identify the request document, in JSON format, on the local machine (scaledgcluster.json).

    • -H to identify the content type as application/vnd.com.oracle.oracloud.datagrid.Service+json.

    For more information, see Scale a Coherence Data Tier.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Tues, 20 Sep 2016 23:29:23 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/scale/job/584
Content-Length: 0
Content-Type: application/vnd.com.oracle.oracloud.datagrid.Service+json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/Example1Instance/clusters/Example1_DGCluster
  7. Check the status of the scale request using the resource URI returned in the Location header. 
    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/status/scale/job/584

    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 the Status of a Service Instance Lifecycle Operation.

    The following shows an example of the response document when you view the status of the request.

    {
    "service_name": "Example1Instance",
    "version": "12cR3",
    "wlsVersion": "12.1.3.0.xxxxxx",
    "status": "Running",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description" : "Example, Inc product distribution",
    "identity_domain": "ExampleIdentityDomain",
    "creation_time": "Mon Sep 19 22:9:23 UTC 2016",
    "last_modified_time": "Mon Sep 19 22:9:21 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/Example1Instance",
    "message": [
      "Successfully scaled in cluster [1].",
      "    Deleting capacity unit(s) containing [1] virtual machines...",
      "    Started shutting down and removing managed servers from Admin.",
      "    Started shutting down and removing managed servers from Admin.",
      "    Completed removing managed servers from Admin.",
      "    Stopping and removing resources for capacity unit(s) containing [1] virtual machines...",
      "    Successfully deleted capacity unit(s) and [1] virtual machines",
      "Successfully scaled in cluster [Example1_DGCluster]."
    ]
}
  8. When the operation completes and the service instance is running, review the list of Managed Servers to confirm one storage-enabled 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/Example1Instance/servers

    The following shows an example of the response body in JSON format. In the example, there is only one storage-enabled Managed Server currently defined.

    {
    "servers": [
    {
      "clusterName":"Example1_cluster",
      "name":"Example1_server_1",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":true,
      "hostname":"12.345.678.999",
      "status":"Ready",
      "reservedIp":"",
      "storageAllocated":73728,
      "creationDate":"19 Sep, 2016 22:09:23 PM"
    },
    {
      "clusterName":"Example1_cluster",
      "name":"Example1_server_2",
      "shape":"oc3",
      "nodeType":"WLS",
      "isAdmin":false,
      "hostname":"example1instance-wls-2",
      "status":"Ready",
      "reservedIp":"",
      "storageAllocated":53248,
      "creationDate":"19 Sep, 2016 22:09:28 PM"
    },
    {
      "clusterName":"Example1_DGCluster",
      "name":"Example1_server_3_DG",
      "shape":"oc3",
      "nodeType":"DG",
      "isAdmin":false,
      "hostname":"example1instance-wls-3",
      "status":"Ready",
      "reservedIp":"",
      "jobId":"538",
      "storageAllocated":43600,
      "creationDate":"19 Sep, 2016 22:42:59 PM"
    }
    ],
    "serverInProgress":[]
}