Creating an instance in Oracle Public Cloud via REST API's - a usable example

April 13, 2017 | 5 minute read
Text Size 100%:

Introduction

This post will walk a user through creating a storage volume, and an instance with that volume attached in the Oracle Public Cloud(OPC) via REST API's.

While this article will use curl to demonstrate the calls, these steps can be replicated with any REST client of your choosing.

Prerequisites

In order to execute this process on your own, you must have:

  • An Oracle Public Cloud domain with enough free resources to work in
  • An account in your domain with the appropriate role to be allowed to use the REST API's (Compute_Operations role)
  • A public ssh key setup in your domain

Assumptions

The following examples assume:

  • Your OPC identity domain is named mytestdomain
  • Your OPC user is john.doe@example.com
  • Your publish ssh key name is jdoe_pubkey
  • Your OPC identity domain REST endpoint is https://api-z999.compute.us0.oraclecloud.com

In order to successfully execute the examples in the post on your own, you will need to replace these example values with your own, valid values.

Creation steps

Find your REST endpoint

You can find your REST endpoint by looking at the service details of your Oracle Compute Cloud domain.

One way to do this is to log in to your OPC domain. From the main dashboard, click on compute.

You should see a value for REST Endpoint similar to this example:

restendpoint-clean

Get an authentication cookie

To utilize OPC REST services, you must first obtain a valid authentication cookie.

Request:
curl -i -X POST -H "Content-Type: application/oracle-compute-v3+json" -d '{"user":"/Compute-mytestdomain/john.doe@example.com","password":"Password123"}' https://api-z999.compute.us0.oraclecloud.com/authenticate/
Response (unimportant content removed):
HTTP/1.1 204 No Content
Set-Cookie: nimbula=eyJpZGVudGl0eSI6ICJ7XCJyZWFsbVwiOiBcImNvbXB1dGUtdXM2LXoyNVwiLCBcInZhbHVlXCI6IFwie1xcXCJjdXN0b21lclxcXCI6IFxcXCJDb21wdXRlLWF0ZWFtYXRncG9jM1xcXCIsIFxcXCJyZWFsbVxcXCI6IFxcXCJjb21wdXRlLXVzNi16MjVcXFwiLCBcXFwiZW50aXR5X3R5cGVcXFwiOiBcXFwidXNlclxcXCIsIFxcXCJzZXNzaW9uX2V4cGlyZXNcXFwiOiAxNDkyMDk1OTg5Ljc0OTQyNCwgXFxcImV4cGlyZXNcXFwiOiAxNDkyMDg2OTg5Ljc0OTQ4NiwgXFxcInVzZXJcXFwiOiBcXFwiL0NvbXB1dGUtYXRlYW1hdGdwb2MzL21pY2hhZWwuc2hhbmxleUBvcmFjbGUuY29tXFxcIiwgXFxcImdyb3Vwc1xcXCI6IFtcXFwiL0NvbXB1dGUtYXRlYW1hdGdwb2MzL0NvbXB1dGUuQ29tcHV0ZV9PcGVyYXRpb25zXFxcIiwgXFxcIi9Db21wdXR............b21wdXRlLkNvbXB1dGVfTW9uaXRvclxcXCIsIFxcXCIvQ29tcHV0ZS1hdGVhbWF0Z3BvYzMvQ29tcHV0ZS5Db21wdXRlX01vbml0b3JcXFwiLCBcXFwiL0NvbXB1dGUtYXRlYW1hdGdwb2MzL0NvbXB1dGUuQ29tcHV0ZV9PcGVyYXRpb25zXFxcIl19XCIsIFwic2lnbmF0dXJlXCI6IFwicTl5TitnejI2NThFVkdnVWx0b1FJYUxVb0RQTHF2Y0JYakdjNDVuRVJocyt1ODRHcktMdklkZUl4eFZBK3RPcG9vVFl3QVNBSE8zWVRnajR0TzVVZm1VdDcyeHFmMnRxZWtqNk85TmJIT1Z2bzZEZkcvVUE5NkY3WGxRT3FMTHZCRVBWR2l0bWZMS0pUM2U4NmRRUjlkK05PK1NQNjNYd29jRE8vbDE1OVhRZFcwOHZXcm5tbGNlTU1ObXd2elZ6eFFRNmtQRExoRkthM282MVBZWE55dXNiaFdBT0E5M2N5RzlVbzlmdksrNjU1RXBJdmpHekgzREcrNHEyamV5Tm5qbk51VExvdC9TalJnclVLN3lCSGU1cEhHOFlUMENJY24ydHlLUXNBbGVtaXRoR1QzTkVrU0VVZ3........................==; Path=/; Max-Age=1800
Content-Language: en

The value of the nimbula cookie is your authorization cookie, and needs to be included with subsequent REST calls.

There are multiple ways to accomplish this. For purposes of this post, we will use an environment variable called COMPUTE_COOKIE.

In a shell, set COMPUTE_COOKIE to equal the value of the nimbula cookie.

export COMPUTE_COOKIE="eyJpZG....==; Path=/; Max-Age=1800"

Subsequent rest calls will now use the $COMPUTE_COOKIE environment variable.

Create a storage volume

Creating a storage volume requires passing in JSON data to the REST service.

This can be done in a separate file that curl will read, or directly on the command line.

As REST calls get more complex, using a separate file is easier to read. One example of passing JSON on the command line will be shown here, but further calls will only use a separate file.

Using a separate file for JSON data

Create a file called storagebody.json with the following content:

{
  "size": "10G",
  "properties": ["/oracle/public/storage/default"],
  "name": "/Compute-mytestdomain/john.doe@example.com/testVolume"
}

REST call to create storage using storagebody.json:

curl -i -X POST -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" -d "@storagebody.json" https://api-z999.compute.us0.oraclecloud.com/storage/volume/
Response (unimportant content removed):
HTTP/1.1 201 Created
{"managed": true, "snapshot_id": null, "snapshot_account": null,....}

The -d "@storagebody.json" argument tells curl to read the storagebody.json file we created, and pass it to the REST service.

After executing the command, look in your compute console under storage and you should have a 10gb volume called testVolume.

firststorage-clean

Command line only

REST call to create storage with command line only:

curl -i -X POST -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" -d '{"size": "10G", "properties": ["/oracle/public/storage/default"], "name": "/Compute-mytestdomain/john.doe@example.com/testVolume2"}' https://api-z999.compute.us0.oraclecloud.com/storage/volume/

After executing the command, look in your compute console under storage and you should have another 10gb volume called testVolume2.

secondstorage-clean

Create an instance with a launch plan

A launch plan creates a non-persistent instance in OPC.

This should not be used if want to control instances with orchestrations.

First, create a file called launchplan_instance.json with the following content:

{
  "instances": [{
    "imagelist": "/oracle/public/OL_6.8_UEKR3_x86_64",
    "label": "testInstance",
    "name": "/Compute-mytestdomain/john.doe@example.com/testInstance",
    "hostname": "testInstance",
    "shape": "oc2m",
    "networking": {
      "eth0": {
        "nat": "ippool:/oracle/public/ippool"
      }
    },
    "storage_attachments": [{
        "index": 1,
        "volume": "/Compute-mytestdomain/john.doe@example.com/testVolume"
      }
    ],
    "sshkeys": [
      "/Compute-mytestdomain/john.doe@example.com/jdoe_pubkey"
    ]
  }]
}

This launchplan defines an instance that will use the testVolume storage volume we created previously. Be sure to update the sshkey to point to your own key, or you will get an error.

Execute the REST call to launch the instance:

curl -i -X POST -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" -d "@launchplan_instance.json" https://api-z999.compute.us0.oraclecloud.com/launchplan/
Response (unimportant content removed):
HTTP/1.1 201 Created
{"relationships": [], "instances": [{"domain":....}

Since this is not an orchestration, you may need to wait a few moments to the instance to appear in your compute console. Note that a launch plan will automatically start the instance up.

Check the instances tab of your compute console, and after a few minutes you should see something like:

testinstance-clean

Create an instance with an orchestration:

Orchestrations provide a mechanism to create many OPC resource types, including instances. An orchestration can accomplish more tasks than a launch plan, and give a repeatable process persisted in your OPC domain.

First create a file called orchestration_instance.json with the following content:

{
  "description": "Example Instance Creation",
  "name": "/Compute-mytestdomain/john.doe@example.com/example_instance",
  "oplans": [{
    "label": "create_instances",
    "obj_type": "launchplan",
    "objects": [{
        "instances": [{
          "imagelist": "/oracle/public/OL_6.8_UEKR3_x86_64",
          "label": "testInstance2",
          "name": "/Compute-mytestdomain/john.doe@example.com/testInstance2",
          "hostname": "testInstance2",
          "shape": "oc2m",
          "networking": {
            "eth0": {
              "nat": "ippool:/oracle/public/ippool"
            }
          },
          "storage_attachments": [{
            "index": 1,
            "volume": "/Compute-mytestdomain/john.doe@example.com/testVolume2"
          }],
          "sshkeys": [
            "/Compute-mytestdomain/john.doe@example.com/jdoe_pubkey"
          ]
        }]
      }
    ]
  }]
}

Execute the REST call to add the orchestration. Note - this does not start the instance. This only loads the orchestration into your OPC domain.

curl -i -X POST -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" -d "@orchestration_instance.json" https://api-z999.compute.us0.oraclecloud.com/orchestration/
Response (unimportant content removed):
HTTP/1.1 201 Created
{"relationships": [], "status": "stopped", "account":....}

Check the orchestration tab of your service console and you should see something like:

neworchstopped-clean

Note the name of the orchestration you just created. It is defined in your json file, and is /Compute-mytestdomain/john.doe@example.com/example_instance

Now start the orchestration you just created with the following command (note this is a PUT, not a POST like previous calls):

curl -i -X PUT -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" https://api-z999.compute.us0.oraclecloud.com/orchestration/Compute-mytestdomain/john.doe@example.com/example_instance?action=start
Response (unimportant content removed):
HTTP/1.1 201 Created
{"relationships": [], "status": "starting", "account":....}

This is telling the orchestration named /Compute-mytestdomain/john.doe@example.com/example_instance to start.

Check the orchestrations tab of your service console, and you should now see your orchestration in the starting state:

orchstarting-clean

After a few moments, you should see testInstance2 appear on the instances tab of your service console.

Michael Shanley


Previous Post

Loading Data from Oracle Field Service Cloud into Oracle Analytics Cloud using ODI and REST - Part III

Dayne Carley | 21 min read

Next Post


Content & Experience Cloud CaaS REST API: reading

Dolf Dijkstra | 14 min read