1. Oracle Java Cloud Service REST APIREST API for Oracle Java Cloud Service
  2. Use Cases
  3. Stopping and Starting a Service Instance and Individual VMs

Stopping and Starting a Service Instance and Individual VMs

You can control the lifecycle state of a service instance and individual virtual machines (VMs) using the REST API.

Note:

  • The cURL commands and request parameters used in this use case are 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.

You can:

  • Stop and start an Oracle Java Cloud Service instance and all of its VMs

  • Restart the Administration Server and its associated VM

  • Stop, start, or restart the local load balancer and its associated VM

  • Stop, start, or restart a Managed Server and its associated VM

Stopping and Starting a Service Instance

To stop and start a service instance, perform the steps described in the following procedure. You cannot restart a service instance using a restart lifecycle state operation. To restart a service instance, issue a stop lifecycle state request followed by a start lifecycle state request.

To stop and start a service instance:

  1. Before stopping a service instance, ensure there are no in-process jobs that must be completed. Any in-process jobs will be terminated when you stop the service instance.

  2. To stop a service instance, first create a JSON document, stopinstance.json, that defines the details of the stop service instance lifecycle state request, as follows: 

    {  
    "lifecycleState"  : "stop",
    "lifecycleTimeout" : "30" 
}

    Optionally, you can specify a timeout value for the request, in minutes, using the lifecycleTimeout attribute. If not specified, it defaults to 60 minutes. For more information about the request attributes, see Stop and Start a Service Instance and Individual VMs.

  3. Stop the service instance and all of its VMs, passing the JSON document created in the previous step.

    curl -i -X POST -u username:userPassword1! -d @stopinstance.json -H "Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

    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.

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

    • -H to identify the content type as application/vnd.com.oracle.oracloud.provisioning.Service+json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Wed, 22 Jun 2016 20:22:01 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/control/job/810275
Content-Length: 0
Content-Type: application/json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

  4. Check the status of the lifecycle state request using the resource URI returned in the Location header. For more information, see View the Status of a Service Instance Lifecycle Operation. 

    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/control/job/810275

    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 the example, the operation is completed as indicated by the "Stopped" status of the service instance:

    {
    "service_name": "ExampleInstance",
    "version": "12cR3",
    "wlsVersion": "12.1.3.0.xxxxxx",
    "status": "Stopped",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description": "Example, Inc product distribution",
    "identity_domain": "ExampleIdentityDomain",
    "creation_time": "Mon Jun 6 19:37:41 UTC 2016",
    "last_modified_time": "Mon Jun 6 19:37:39 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/ExampleInstance",
    "message": [
      "Stopping service [ExampleInstance]...",
      "Stopped service [ExampleInstance].",
      "    Stopped all Compute resources..."
    ]
}

  5. To start a service instance, first create a JSON document, startinstance.json, that defines the details of the start service instance lifecycle state request, as follows: 

    { "lifecycleState"  : "start" }

    For more information about the request attributes, see Stop and Start a Service Instance and Individual VMs.

  6. Start the service instance and all of its VMs, passing in the JSON document created in the previous step.

    curl -i -X POST -u username:userPassword1! -d @startinstance.json -H "Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

    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.

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

    • -H to identify the content type as application/vnd.com.oracle.oracloud.provisioning.Service+json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Wed, 22 Jun 2016 22:53:23 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/control/job/810368
Content-Length: 0
Content-Type: application/json
Service-URI: https://rest_server_ur;/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

  7. Check the status of the lifecycle state request using the resource URI returned in the Location header. For more information, see View the Status of a Service Instance Lifecycle Operation. 

    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/control/job/810368

    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 the example, the operation is completed as indicated by the "Running" status of the service instance:

    {
    "service_name": "ExampleInstance",
    "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 Jun 6 19:37:41 UTC 2016",
    "last_modified_time": "Mon Jun 6 19:37:39 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/ExampleInstance",
    "message": [
      "Starting service [ExampleInstance]...",
      "Started service [ExampleInstance].",
      "    Started all Compute resources..."
    ]
}

Restarting the Administration Server

To restart the Administration Server, perform the steps described in the following procedure. You can only restart the Administration Server using a restart lifecycle state operation. You cannot use the stop or start lifecycle state operation to control the lifecycle state of the Administration Server.

To restart the Administration Server:

  1. Before restarting the Administration Server, ensure there are no in-process jobs running on its associated VM that must be completed. Any in-process jobs will be terminated when you stop the Administration Server.

  2. Create a JSON document, restartadminserver.json, that defines the details of the restart Administration Server lifecycle state request, as follows: 

    {  
    "lifecycleState"  : "restart",
    "serverName" : "ExampleI_server_1",
    "force" : true
}

    See View All Managed Servers to retrieve the name of the Administration Server.

    To control the lifecycle state of the Administration Server, the lifecycleState can only be set to restart. For serverName, you can specify the name of the Administration Server or a Managed Server that runs on the same VM as the Administration Server. You must set the force flag to true to ensure the lifecycle state operation proceeds if other Managed Servers are running on the same VM. For more information about the request attributes, see Stop and Start a Service Instance and Individual VMs.

  3. Restart the Administration Server and its associated VM, passing in the JSON document created in the previous step.

    curl -i -X POST -u username:userPassword1! -d @restartadminserver.json -H "Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

    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.

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

    • -H to identify the content type as application/vnd.com.oracle.oracloud.provisioning.Service+json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Wed, 22 Jun 2016 23:42:29 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/control/job/810398
Content-Length: 0
Content-Type: application/json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

  4. Check the status of the lifecycle state request using the resource URI returned in the Location header. For more information, see View the Status of a Service Instance Lifecycle Operation. 

    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/control/job/810398

    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 the example, the operation is not yet completed as indicated by the "Maintenance" status of the service instance. The status is "Running" when the operation is completed.

    {
    "service_name": "ExampleInstance",
    "version": "12cR3",
    "wlsVersion": "12.1.3.0.xxxxxx",
    "status": "Maintenance",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description": "Example, Inc product distribution",
    "identity_domain": "ExampleIdentityDomain",
    "creation_time": "Mon Jun 6 19:37:41 UTC 2016",
    "last_modified_time": "Mon Jun 6 19:37:39 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/ExampleInstance",
    "message": [
      "Restarting service member [ExampleI_server_1] of service [ExampleInstance]...",
      "    Stopping Virtual Machine wls\/vm-1..."
    ]
}

Restarting a Managed Server

To restart a Managed Server, perform the steps described in the following procedure. In addition to using the restart lifecycle state operation described in this procedure, you can use the stop or start lifecycle state operations to control the lifecycle state of a Managed Server, but only if that Managed Server does not reside on the same VM as the Administration Server. For more information, see Stop and Start a Service Instance and Individual VMs.

To restart a Managed Server:

  1. Before restarting the Managed Server, ensure there are no in-process jobs running on its associated VM that must be completed. Any in-process jobs will be terminated when you stop the Managed Server.

  2. Create a JSON document, restartserver.json, that defines the details of the restart Managed Server lifecycle state request, as follows: 

    {  
    "lifecycleState"  : "restart",
    "serverName" : "ExampleI_server_2",
    "force" : true
}

    See View All Managed Servers to retrieve the name of the Managed Server.

    Use serverName to specify the name of the Managed Server that you want to restart. Optionally, you can set the force flag to true to ensure the lifecycle state operation proceeds if other Managed Servers are running on the same VM. For more information about the request attributes, see Stop and Start a Service Instance and Individual VMs.

  3. Restart the Managed Server and its associated VM, passing in the JSON document created in the previous step.

    curl -i -X POST -u username:userPassword1! -d @restartserver.json -H "Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

    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.

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

    • -H to identify the content type as application/vnd.com.oracle.oracloud.provisioning.Service+json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Thu, 23 Jun 2016 00:04:41 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/control/job/811634
Content-Length: 0
Content-Type: application/json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

  4. Check the status of the lifecycle state request using the resource URI returned in the Location header. For more information, see View the Status of a Service Instance Lifecycle Operation. 

    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/control/job/811634

    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 the example, the operation is not yet completed as indicated by the "Maintenance" status of the service instance. The status is "Running" when the operation is completed.

    {
    "service_name": "ExampleInstance",
    "version": "12cR3",
    "wlsVersion": "12.1.3.0.xxxxxx",
    "status": "Maintenance",
    "error_status_desc": "",
    "compliance_status": "",
    "compliance_status_desc": "",
    "auto_update": "true",
    "description": "Example, Inc product distribution",
    "identity_domain": "ExampleIdentityDomain",
    "creation_time": "Mon Jun 6 19:37:41 UTC 2016",
    "last_modified_time": "Mon Jun 6 19:37:39 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/ExampleInstance",
    "message": [
      "Restarting service member [ExampleI_server_2] of service [ExampleInstance]...",
      "    Stopping Virtual Machine wls\/vm-2..."
    ]
}

Restarting the Local Load Balancer

To restart the local load balancer, perform the steps described in the following procedure. In addition to using the restart lifecycle state operation described in this procedure, you can use the stop or start lifecycle state operations to control the lifecycle state of the load balancer. For more information, see Stop and Start a Service Instance and Individual VMs.

To restart the local load balancer:

  1. Create a JSON document, restartlb.json, that defines the request details, as follows: 

    {  
    "lifecycleState"  : "restart",
    "lbAdminHostName" : "ExampleInstance-lb-1"
}

    By default the host name of the local load balancer is serviceinstancename-lb-1, where serviceinstancename is the name of your Oracle Java Cloud Service instance.

  2. Restart the local load balancer and its associated VM, passing in the JSON document created in the previous step.

    curl -i -X POST -u username:userPassword1! -d @restartlb.json -H "Content-Type:application/vnd.com.oracle.oracloud.provisioning.Service+json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

    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.

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

    • -H to identify the content type as application/vnd.com.oracle.oracloud.provisioning.Service+json and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

    The following shows an example of the response header.

    HTTP/1.1 202 Accepted
Date: Thu, 23 Jun 2016 20:29:08 GMT
Location: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/status/control/job/812640
Content-Length: 0
Content-Type: application/json
Service-URI: https://rest_server_url/paas/service/jcs/api/v1.1/instances/ExampleIdentityDomain/ExampleInstance

  3. Check the status of the lifecycle state request using the resource URI returned in the Location header. For more information, see View the Status of a Service Instance Lifecycle Operation. 

    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/control/job/812640

    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 the example, the operation is completed as indicated by the "Running" status of the service instance:

    {
    "service_name": "ExampleInstance",
    "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 Jun 6 19:37:41 UTC 2016",
    "last_modified_time": "Mon Jun 6 19:37:39 UTC 2016",
    "created_by": "username",
    "service_uri": "https:\/\/rest_server_url\/paas\/service\/jcs\/api\/v1.1\/instances\/ExampleIdentityDomain\/ExampleInstance",
    "message": [
      "Restarting service member [ExampleInstance-lb-1] of service [ExampleInstance]...",
      "Restarted service member [ExampleInstance-lb-1] of service [ExampleInstance].",
      "    Stopped service member [ExampleInstance-lb-1] of service [ExampleInstance].",
      "        Stopped Virtual Machine lb\/vm-1...",
      "    Started service member [ExampleInstance-lb-1] of service [ExampleInstance].",
      "        Started Virtual Machine lb\/vm-1..."
    ]
}