Managing Machine Images

A machine image is a hard disk snapshot used to launch a virtual machine instance. The machine image archive must be a single raw disk image (including partition table and kernel) stored at the root of a tar archive and compressed with gzip. All machine images must be based on the Oracle Public Cloud Machine templates. A machine image template can be created only by a Oracle Cloud Administrator. For more information about building machine images and templates, see Using Oracle Compute Cloud Service.

Topics:

Add Machine Image

This API enables you to add a private machine image to the system.

Method

POST

To add a machine image to the system, two POST requests are required:

POST request to create a machine image object—This request creates a new machine image object, and returns the URI of this object in the response body.
POST request to upload machine image file—This request uses the URI returned from the first step, and uploads the corresponding machine image on the system. The machine image file (in tar.gzip format) is passed in the HTTP request with the following headers:
- Accept:application/oracle-compute-v3+json
- Accept-Encoding:gzip;q=1.0,identity;q=0.5
- Content-Type:application/x-tar
- Content-Length:<length of the machine image file>
- Content-Range:bytes <filesize in the format {0–[filesize in bytes—1]/filesize}>

Note:

Chunked encoding is not supported.

REST Resource

/machineimage/

URI

https://api_endpoint/machineimage/

Request Body Parameters

Parameter	Description
name	A unique hierarchical name for the machine image. For example, `/mytenant/public/mymachineimage`.
no_upload	Indicates if the image file is available in the system. This must always be set to `False`.
attributes	(Optional) User-defined parameters that can be passed to an instance of this machine image when it is launched. These parameters are passed as JSON objects. Syntax (key/value pairs): '{ "key1": "value1", "key2": "value2" }' For example, you can specify the location of a database server and login details, which are then passed to the machine image during launch. For more information on attributes, see Orchestration Templates in Using Oracle Compute Cloud Service.
quota	(Optional) The quota against which this image will be created.

Example: Add Machine Image

Part 1 : Create Machine Image Object

Request URI

POST https://api.oc.example.com/machineimage/

Request Body

{
   "name": "/oracle/public/TestImage3", 
   "sizes": {"total": "3684711429"}, 
   "no_upload": false,  
   "attributes": {"type": "linux"}
}

Response Body

{
 "account": "/oracle/public", 
 "name": "/oracle/public/TestImage3", 
 "sizes": {"uploaded": null, "total": 360, "decompressed": null}, 
 "signature": "", 
 "no_upload": false, 
 "uri": "http://api.oc.example.com/machineimage/oracle/public/TestImage3", 
 "quota": "/oracle/public/64b1345d-b729-4cbc-a2dc-44a164f2e4a6", 
 "state": "available", 
 "signed_by": null, 
 "file": "http://api.oc.example.com:80/machineimage/oracle/public/TestImage3", 
 "attributes": {}, 
 "checksums": {}, 
 "error_reason": "", 
 "audited": null
}

Part 2: Upload Machine Image Object

Note:

Specifying the machine image file contents differs depending on the tool or language being used to interact with the API. Refer to the documentation for the tool or language you are using for details on how to specify the file contents.

Request URI

POST http://api.oc.example.com:80/machineimage/oracle/public/TestImage3

Request Headers

Accept:application/oracle-compute-v3+json
Accept-Encoding:gzip;q=1.0,identity;q=0.5
Content-Type:application/x-tar
Content-Length:3684711429
Content-Range:bytes bytes 0-3684711428/3684711439

Example: Add Machine Image using cURL

Note:

For more information on cURL, see Invoking REST API Calls Using cURL.

Authentication

$ curl -c /tmp/cookie -X POST -H "Content-Type: text/plain" -d '{"result": null, "password": "abc123", "uri": null, "user": "/mytenant/myuser"}' http://api.oc.example.com/authenticate/

First POST

$curl -v -b /tmp/cookie -X POST -H "Content-Type: application/oracle-compute-v3+json" -d '
{"name": "/oracle/public/TestImage3", "sizes": {"total" : 376857280 }, "no_upload": false, 
"attributes": {"type": "linux"}}' http://api.oc.example.com/machineimage/

Second POST

$ curl -v -b /tmp/cookie -X POST -H "Expect: " -H "Accept-Encoding: gzip;q=1.0, identity; q=0.5" -H 
"Accept: application/oracle-compute-v3+json" -H "Content-Range: bytes 0-376857279/376857280"
-H "Content-Type: application/x-tar" --data-binary "@MACHINE_IMAGE.tar.gz" 
http://api.oc.example.com/machineimage/oracle/public/TestImage3

Delete Machine Image

This API enables you to delete a machine image.

You can delete only those private machine images that you have created.

Method

DELETE

REST Resource

/machineimage/name

URI

https://api_endpoint/machineimage/name

URI Parameter

Parameter	Description
name	A unique hierarchical name for the machine image. For example, `/mytenant/public/mymachineimage`

Example URI

https://api.oc.example.com/machineimage/mytenant/public/webserver-20130912

Retrieve Machine Image Details

You can view machine image details by using the REST API.

Topics:

Discover Machine Images

This API enables you to discover a list of machine images present in a specific container.

Note:

The discover API calls display the names of the objects in the specified container, not the details about the objects. To list the names of the objects, you must set the Accept header to application/oracle-compute-v3+directory+json. For all other purposes, you must set the Accept header to application/oracle-compute-v3+json.

Method

GET

REST Resource

/machineimage/container/

URI

https://api_endpoint/machineimage/container/

URI Parameter

Parameter	Description
container	Hierarchical name-space for machine images

Example URI

https://api.oc.example.com/machineimage/mytenant/

Example Response Body

{"result": ["/mytenant/public/oraclelinux-x64", "/mytenant/public/OL6.6_20GB"]}

Get Machine Image

This API enables you to retrieve details of a specified machine image.

Method

GET

REST Resource

/machineimage/name

URI

https://api_endpoint/machineimage/name

URI Parameter

Parameter	Description
name	A unique hierarchical name for the machine image. For example, `/mytenant/public/mymachineimage`

Example URI

https://api.oc.example.com/machineimage/oracle/public/linux6_16.1.2_64

Example Response Body

{
"account": null, 
"name": "/oracle/public/linux6_16.1.2_64", 
"sizes": {"uploaded": 1572050349, "total": 1572050349, "decompressed": 11811160064}, 
"signature": null, 
"no_upload": false, 
"uri": "https://api/machineimage/oracle/public/linux6_16.1.2_64", 
"quota": null, 
"state": "available", 
"signed_by": null, 
"file": "https://api:444/machineimage/oracle/public/linux6_16.1.2_64", 
"attributes": {}, 
"checksums": null, 
"error_reason": null, 
"audited": null
}

List Machine Images

This API enables you to retrieve details of all machine images in a container.

Method

GET

REST Resource

/machineimage/container/

URI

https://api_endpoint/machineimage/container/?quota=quotaValue

URI Parameters

Parameter	Description
container	Hierarchical name-space for machine images
quota=quotaValue	(Optional) Quota associated with the image

Example URI

https://api.oc.example.com/mytenant

Example Response Body

{
"result": [
{
   "account": "/mytenant/cloud_storage", 
   "name": "/mytenant/public/oraclelinux-x64", 
   "sizes": {
    "uploaded": 1853334188, 
    "total": 1853334188, 
    "decompressed": 22020096000
   }, 
   "uri": "http://api.oc.example.com/machineimage/mytenant/public/oraclelinux-x64", 
   "quota": null, 
   "no_upload": true, 
   "state": "available", 
   "signed_by": null, 
   "file": "http://api.oc.example.com/machineimage/mytenant/public/oraclelinux-x64", 
   "signature": "", 
   "checksums": {}, 
   "attributes": {}, 
   "error_reason": "", 
   "audited": null
},
{
  "account": "/mytenant/cloud_storage",
  "name": "/mytenant/public/OL6.6_20GB",
  "sizes": {
    "uploaded": 1545137187,
    "total": 1545137187,
    "decompressed": 21474836480
  },
  "signature": "",
  "no_upload": true,
  "uri": "https://api.oc.example.com/machineimage/mytenant/public/OL6.6_20GB",
  "quota": "/mytenant/4123456f-e94g-39e1-ac96-ef23a930692e",
  "state": "available",
  "signed_by": null,
  "file": "https://api.oc.com/machineimage/mytenant/public/OL6.6_20GB",
  "attributes": {},
  "checksums": {},
  "error_reason": "",
  "audited": null
}
]
}