Oracle® Public Cloud Machine

REST API Reference for Oracle Compute Cloud Service

Release 17.1.2

E68443-07

April 2017

Oracle Public Cloud Machine REST API Reference for Oracle Compute Cloud Service, Release 17.1.2

E68443-07

Copyright © 2016, 2017, Oracle and/or its affiliates. All rights reserved.

Primary Author: Nidhi Kakkar

Contributing Author: Jeremy Bar, Karen Wilson, Samuel Jackson, and Jon Richards

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Getting Started with Oracle Compute Cloud Service REST API

- Roles of API Users

- Oracle Compute Resource URIs

- Authenticating API Calls

2 Overview of Oracle Compute REST API

- About REST API Requests and Responses

- Supported HTTP Methods

- About Object Names

- REST API Request Headers

- HTTP Response Codes

- Invoking REST API Calls Using cURL

- Summary of REST APIs, Alphabetical by Resource Path

3 Authentication

- Authenticate User

4 Tenant Management

- Viewing Tenants

- Discover Tenants

- Get Tenant

- List Tenants

- Viewing Tenant Quotas

- Discover Quota

- Get Quota

- List Quota

5 User Management

- Managing Users

- Add User

- Delete User

- Update User

- Retrieve User Details

- Discover Users

- Get User

- List Users

6 Instance and Snapshot Management

- Managing Instances

- Delete Instance

- Restart Instance

- Shutdown Instance

- Update Instance

- Retrieve Instance Details

- Discover Instances

- Get Instance

- List Instances

- Managing Snapshots

- Add Snapshot

- Delete Snapshot Request

- Retrieve Snapshot Details

- Discover Snapshots

- Get Snapshot

- List Snapshots

- Managing SSH Keys

- Add Public SSH Key

- Delete SSH Key

- Update SSH Key

- Retrieve SSH Key Details

- Discover SSH Keys

- Get SSH Key

- List SSH Keys

- Managing Orchestrations

- Add Orchestration

- Delete Orchestration

- Start Orchestration

- Stop Orchestration

- Shutdown Orchestration

- Restart Orchestration

- Update Orchestration

- Retrieve Orchestration Details

- Discover Orchestrations

- Get Orchestration

- List Orchestrations

- Viewing Shapes

- Discover Shapes

- Get Shape

- List Shapes

- Connecting to an Instance VNC Console

- Get Instance VNC Key

- Get JNLP file to Access VNC

7 Template Management

- Managing Machine Images

- Add Machine Image

- Delete Machine Image

- Retrieve Machine Image Details

- Discover Machine Images

- Get Machine Image

- List Machine Images

- Managing Image Lists

- Add Image List

- Delete Image List

- Update Image List

- Retrieve Image List Details

- Discover Image Lists

- Get Image List

- List Image Lists

- Managing Image List Entries

- Add Image List Entry

- Delete Image List Entry

- Retrieve Image List Entry Details

- Get Image List Entry

- List Image List Entries

8 Site Information

- Accessing Site Information

- Get Site Information

9 Storage Management

- Managing Storage Volumes

- Add Storage Volume

- Delete Storage Volume

- Update Storage Volume

- Retrieve Storage Volume Details

- Discover Storage Volumes

- Get Storage Volume

- List Storage Volumes

- Managing Storage Attachments

- Add Storage Attachment

- Delete Storage Attachment

- Retrieve Storage Attachment Details

- Discover Storage Attachments

- Get Storage Attachment

- List Storage Attachments

- Viewing Storage Properties

- Discover Property Storage

- Get Property Storage

- List Property Storage

10 Network Management

- Viewing Service Networks

- Discover Service Networks

- Get Service Network

- List Service Networks

- Managing vEthernet

- Add vEthernet

- Delete vEthernet

- Update vEthernet

- Retrieve vEthernet Details

- Discover vEthernets

- List vEthernets

- Managing vNET

- Add vNET

- Delete vNET

- Update vNet

- Retrieve vNET Details

- Discover vNET

- Get vNET

- List vNET

- Viewing vNET Access

- Discover vNET Access

- List vNET Access

- Get vNET Access

- Managing vNET Reservations

- Add vNET Reservation

- Delete vNET Reservation

- Retrieve vNET Reservation Details

- Discover vNET Reservation

- Get vNET Reservation

- List vNET Reservations

- Viewing vCables

- Discover vCables

- Get vCable

- List vCables

Preface

This guide describes the Oracle Compute Cloud Service REST API for Oracle Public Cloud Machine, which you can use to develop applications and services, in the language of your choice, to interoperate with Oracle Compute Cloud Service.

Audience

This document is intended for tenant administrators and tenant users who use Oracle Compute Cloud Service for Oracle Public Cloud Machine, and who are familiar with the following:

- The UNIX command line

- Virtualization technologies

- Networking and disk storage concepts

- REST API concepts

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Related Documents

For more information, see the following documents in the Oracle Public Cloud Machine documentation set:

- Using Oracle Compute Cloud Service

- CLI Reference for Oracle Compute Cloud Service

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

monospace italics

Text in monospace italic indicates variables for which you supply a value.

...

Ellipses indicate that the sample output of a command is truncated for readability.

1 Getting Started with Oracle Compute Cloud Service REST API

Oracle Public Cloud Machine supports an optimized version of the Oracle Compute Cloud Service REST API , which enables you to manage the various Oracle Compute Cloud Service objects. This section gives an overview of the Oracle Compute Cloud Service REST API.

Topics:

- Roles of API Users

- Oracle Compute Resource URIs

- Authenticating API Calls

Roles of API Users

The following user roles are supported:

- Tenant administrator (/tenant_name/username)—Administrator for a given tenant. Can perform all the administrative functions for a tenant. Can create users with the /tenant_name/users role for their tenant. Default tenant admin user—/tenant_name/administrator.

- Tenant user (/tenant_name/username)—User of a tenant group. Can create and use virtual machines (VMs) and resources within the tenant.

For more information on user roles, see Getting Started with Using Oracle Compute Cloud Services in Using Oracle Compute Cloud Service.

Oracle Compute Resource URIs

To perform operations on Oracle Compute Cloud Service resources by using REST API calls, you must specify the fully qualified, unique URI of the resource. The fully qualified URI of a resource is in the following format:

https://api_endpoint/resource_base_path/resource_name

- api_endpoint is the REST endpoint URL that you receive from the Oracle Cloud Administrator. Examples in this guide use https://api.oc.example.com as the REST endpoint URL.

- resource_base_path is the base URI of the resource. For example, for SSH public keys, the base URI is /sshkey.

- resource_name is a unique identifier of the specific resource based on the following convention:
/domain/user/object_id

For example, the following is the fully qualified URI of the sshkey object named key1 for tenant /mytenant:

https://api.oc.example.com/sshkey/mytenant/public/key1

Authenticating API Calls

API calls to Oracle Compute Cloud Service require basic authentication by user name and password. You can request an authentication token, as described in Authenticate User. When the authentication request succeeds, the server returns a cookie that contains an authentication token that is valid for 5 minutes. The client must include this authentication token in the Cookie: request header, in all subsequent API calls.

For more information, see Authentication.

2 Overview of Oracle Compute REST API

This section is an overview about using Oracle Compute Cloud Service REST API commands to manage Oracle Compute sites on Oracle Public Cloud Machine.

Topics:

- About REST API Requests and Responses

- Supported HTTP Methods

- About Object Names

- REST API Request Headers

- HTTP Response Codes

- Invoking REST API Calls Using cURL

- Summary of REST APIs, Alphabetical by Resource Path

About REST API Requests and Responses

A REST API transaction consists of an API request and a corresponding API response.

An API request consists of the following parts:

- API request method—Specifies the operation that you would like to perform on the Oracle Compute object. See Supported REST API Methods.

- Resource URL—Specifies the fully qualified URI of the target Oracle Compute object on Oracle Public Cloud Machine. See About Object Names.

- Request headers—Specifies the REST API request headers. See REST API Request Headers.

- Request body—Specifies a list of customized parameters that are required to perform an operation on the Oracle Compute object.

An API response consists of the following parts:

- HTTP response code—Specifies if the REST API request was a success or a failure. See HTTP Response Codes.

- Response headers—Specifies the REST API response headers.

- Response body—Specifies the JavaScript Object Notation (JSON) encoded data returned in response to the REST API request.

Supported HTTP Methods

The following table describes the REST HTTP methods you can invoke for Oracle Public Cloud Machine objects.

Note:
Some methods are not supported for certain objects.

Method

Description

POST

Creates an object by using the JSON-formatted data in the request body

GET

Retrieves information about the object/s specified in the request URI

PUT

Updates the attributes of an object by using the JSON-formatted data in the request body

DELETE

Deletes the object specified in the request URI

About Object Names

Each Oracle Compute object for which you can perform REST API calls is identified uniquely by its URI. Objects such as an instance, a storage volume or an SSH key have a name based on its position in a hierarchy of containers.

For example, the object name /mytenant/public/8e7c16ad-1bc4-4743-a9ce-781be4e26f24 indicates that this instance 8e7c16ad-1bc4-4743-a9ce-781be4e26f24 is in the container public, and public is in the container mytenant.

REST API Request Headers

Ensure that the following headers are specified correctly in HTTP requests.

Request Header

Description

Accept:

With a few exceptions, the REST API returns JavaScript Object Notation (JSON) encoded data in its responses. The Accept: header must be set to indicate both JSON format and the API's version number. The supported API protocol version is v3.

- For GET calls that retrieve just the names (not details) of objects in a container, set this header to application/oracle-compute-v3+directory+json

- For all other purposes, set the header to application/oracle-compute-v3+json

Example:

Accept: application/oracle-compute-v3+json

Accept-Encoding:

Ensure that the HTTP client is set to supported encoding values.

Example:

Accept-Encoding: gzip;q=1.0, identity; q=0.5

Accept-Charset:

The API sends and receives only UTF-8 encoded data. Ensure that your HTTP client encodes and decodes character data, including JSON data.

Example:

Accept-Charset: UTF-8

Content-Type:

All the content in an HTTP request body must be encoded in JSON. The API protocol version is also specified in both request and response messages. The content types are:

- application/oracle-compute-v3+json

- multipart/oracle-compute-v3+form-data

- application/x-tar

The server specifies the expected version of the data in the response in the Content-Type: header.

If the server does not support the version specified by the client in the request, then it responds with HTTP status code 415 (Unsupported Media Type). If the server can't provide a response in any of the versions supported by the client, then it responds with status code 406 (Not Acceptable).

Example:

Content-Type: application/oracle-compute-v3+json

Cookie:

Include the Cookie: header with every request to the service. Set the value of the Set-Cookie header in the response received to the POST /authenticate/ call. See Authentication.

HTTP Response Codes

The following table lists the HTTP response codes and their meanings.

HTTP Response Code

Description

2XX

API Successful

Indicates that the request is successful.

201

Created

An add/update request is successful.

204

No Content.

Deletion request is successful with no response content.

4xx

APIClientError

A client side error, in line with 4xx errors in HTTP.

401

APIUnauthorizedError

The request requires user authentication or authorization.

403

APIForbiddenError

The request is formed properly, but the server cannot fulfill it. The issue is not related to authorization. Do not repeat the request.

404

APINotFoundError

The server has not found a match for the URI in the request. This state might be temporary so repeat the request.

405

APIMethodNotAllowedError

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. This exception occurs when the request includes a method that is not supported for the object.

406

APINotAcceptableError

The resource specified in the request generates response that has characteristics that are not allowed by the accept headers in the request.

409

APIConflictError

The request could not be completed because of a conflict with the state of the resource or the resource already exists. You can either delete the existing object to allow the request to create it, or you can create a new object with a unique identifier.

410

APIGoneError

The requested resource does not exist. This error occurs when an instance exists but is not running so a duplicate of this instance with the same identifier can not be created.

413

APIRequestTooLarge

The request attempts to upload an image that exceeds the maximum upload size. The default maximum upload size is 10 GB. To change this limit, edit the site.conf file to change the line:[services] [[api] [[[max_upload]]].

415

APIUnsupportedTypeError

The server cannot complete the request because the request contains a format that is not supported by the method for the resource. This error indicates an error in JSON formatting.

5xx

APIServerError

An internal error occurred, and the server cannot fulfill the request.

500

APIUncaughtExceptionError

The server encountered an unexpected condition that prevented it from fulfilling the request. The error includes a code. Use this code when you report the problem to My Oracle Support.

501

APINotImplementedError

The server does not support the functionality required to fulfill the request.

503

APIServiceUnavailable

The server is unable to handle the request due to temporary overloading or maintenance. This error is usually related to the load on the server and is temporary. Repeat the request.

502/504

APIGatewayError

The Oracle Compute service layer is not able to respond. This is usually related to a failover of the service and is temporary. Repeat the request.

507

APIInsufficientStorage

The server is unable to store the data needed to complete the request. This condition is temporary. Repeat the request.

Invoking REST API Calls Using cURL

You can interact with the REST API of Oracle Compute Cloud Service by sending HTTP requests to the appropriate resource URIs. Several tools are available for making REST API calls, including clients that are extensions or plug-ins for popular browsers. cURL is a command-line tool that you can use to construct and send HTTP requests. This topic illustrates how to use cURL to send REST API calls to Oracle Compute Cloud Service.

Prerequisites

- SSL-enabled version of cURL, or any other REST API client.
Most Linux installations include cURL. To download and install cURL, go to http://curl.haxx.se/download.html.

- The REST endpoint URL for your Oracle Compute Cloud Service . See Oracle Compute Resource URIs

- The resource URI to which you want to send the request and the parameters that you want to include in the request.
See Summary of REST APIs, Alphabetical by Resource Path. It lists all the available resources. For each resource, it also provides a link to the reference documentation for the supported parameters.

- The user name and password, for your Oracle Compute Cloud Service instance. See Getting Started with Using Oracle Compute Cloud Services in Using Oracle Compute Cloud Service.
If you don’t have this information, contact your Oracle Cloud Administrator, or Tenant Administrator.

Procedure

1. Get an authentication token from Oracle compute Cloud Service, as shown in the following cURL command example:
Enter the command on a single line. Line breaks are used in this example for readability.

curl -i -X POST
-H "Content-Type: application/oracle-compute-v3+json"
-d '{"user":"/mytenant/myuser","password":"ft7)Dvjo"}'
https://api.oc.example.com/authenticate/

2. In the response to the POST request, look for the Set-Cookie header, as shown in the following example.

Set-Cookie: nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": \"{\\
\"customer\\\": \\\"acme\\\", ....Bb2U5uoJ2nwU7g1fDBcII/US6e7yLYqWSdb/U
ItvUiLo7/SARyfG+RmqnuFcJDoczaNssUmLLBikq8IPNAxaSIvGZmzK7K4anTwXcAhVg==\"}
"}; Path=/; Max-Age=300

Note:

Note that the Set-Cookie header and value are in a single line. Line breaks are used in this example for readability.

3. Store the authentication cookie in an environment variable, as shown in the following example for a Linux host. The example shown here was shortened for readability. Your command must include the entire cookie value embedded between the single quotes.

export ORACLE_COMPUTE_COOKIE='nimbula={"identity": "{\"realm\": \"mytenant\", \"value\": ...cAhVg==\"}"}; Path=/; Max-Age=300'

4. Send the required HTTP request to Oracle Compute Cloud Service, as shown in the following examples:
EXAMPLE 1: Getting a list of the available shapes

Send the following GET request:

curl -X GET -H "Cookie: $ORACLE_COMPUTE_COOKIE" https://api.oc.example.com/shape/

ORACLE_COMPUTE_COOKIE is the name of the variable in which you stored the authentication cookie earlier.

This command returns details of all the available shapes, in JSON format, as shown in the following example:

Note:
This sample response is formatted for readability and truncated for brevity.

{
"result": [
{
"ram": 7680,
"cpus": 2.0,
"uri": "https://api.oc.example.com/shape/oc3",
"name": "oc3"
},
{
"ram": 15360,
"cpus": 4.0,
"uri": "https://api.oc.example.com/shape/oc4",
"name": "oc4"
},
{
"ram": 30720,
"cpus": 8.0,
"uri": "https://api.oc.example.com/shape/oc5",
"name": "oc5"
}
]
}

Summary of REST APIs, Alphabetical by Resource Path

This table lists the REST resources alphabetically by resource path and lists the supported methods for each resource.

REST Resource

Supported Methods

More Information

/authenticate/

POST

Authenticate User

/info/

GET

Get Site Information

/imagelist/

DELETE, GET, POST, PUT

Managing Image Lists

/imagelist/name/entry/

DELETE, GET, POST, PUT

Managing Image List Entries

/instance/

DELETE, GET, POST, PUT

Managing Instances

/machineimage/

DELETE, GET, POST, PUT

Managing Machine Images

/orchestration/

DELETE, GET, POST, PUT

Managing Orchestrations

/property/storage/

GET

Viewing Storage Properties

/quota/

GET

Viewing Tenant Quotas

/svcnet/

GET

Viewing Service Networks

/shape/

GET

Viewing Shapes

/snapshot/

DELETE, GET, POST, PUT

Managing Snapshots

/sshkey/

DELETE, GET, POST, PUT

Managing SSH Keys

/storage/attachment/

DELETE, GET, POST, PUT

Managing Storage Attachments

/storage/volume/

DELETE, GET, POST, PUT

Managing Storage Volumes

/tenant/

GET

Viewing Tenants

/user/

DELETE, GET, POST, PUT

Managing Users

/vcable/

GET

Viewing vCables

/vethernet/

DELETE, GET, POST, PUT

Managing vEthernet

/vnet/

DELETE, GET, POST, PUT

Managing vNET

/vnetaccess/

GET

Viewing vNET Access

/vnetreservation/

DELETE, GET, POST, PUT

Managing vNET Reservations

3 Authentication

All the API calls to Oracle Compute Cloud Service must be authenticated. API calls are authenticated using a token. You can request an authentication token from the Oracle Compute Cloud Service. Then include this token in the subsequent API calls. This section describes how to request the authentication token.

Topics:

- Authenticate User

Authenticate User

This API enables you to obtain an authentication token.

This API request returns an authentication token in the Set-Cookie response header. By default, the token expires after 5 minutes. A valid (that is, unexpired) authentication token must be included in every request to the service in the Cookie: request header. The client must check the expiration time and discard the cookie if the cookie has expired. Any requests that include an expired cookie will get an Unauthorized error.

Method

POST

REST Resource

/authenticate/

URI

https://api_endpoint/authenticate/

Request Body Parameters

Parameter

Description

user

User name

password

The password for the user

Example URI

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

Example Request Body

{"user": "/mytenant/admin", "password": "mytenant2psswd123" }

Example Response Headers

204 No Content
Used response headers:
x-oracle-compute-call-id: 15102801fb6b260ec3b522beb113021d200f3e
Set-Cookie: nimbula={"identity": "{\"realm\": \"apiexample\", \"value\":
\"{\\\"customer\\\": \\\"mytenant\\\", \\\"realm\\\": \\\"apiexample\\\",
\\\"entity_type\\\": \\\"user\\\", \\\"session_expires\\\": 1405250409.271111,
\\\"expires\\\": 1405241409.271148, \\\"user\\\": \\\"/mytenant/admin\\\",
\\\"groups\\\": [\\\"/mytenant/admin\\\", \\\"/mytenant\\\"]}\",
\"signature\": \"AE2vZOGt0XIIEstK0HL6IgJ7vrRxgo30qQrWhwepRbNbATuEMh2k...\"}"};
Path=/; Max-Age=10800
expires: Wed, 28 Oct 2015 08:01:04 GMT
vary: Accept
server: nginx
connection: keep-alive
cache-control: no-cache
date: Wed, 28 Oct 2015 08:01:04 GMT
content-type: application/oracle-compute-v3+json

4 Tenant Management

The tenant is a framework within which system objects such as users and machine images are created. The tenant can be an organization, a department within an organization, or an individual.

The Oracle Cloud Administrator grants designated tenant administrators and tenant users the authorization to use computing, networking, and storage resources of the Oracle Public Cloud Machine. The tenant provides the required capabilities to manage these resources.

Topics:

- Viewing Tenants

- Viewing Tenant Quotas

Viewing Tenants

The Tenant is the entity that uses Oracle Compute Cloud Service resources. Tenants must be registered by the Oracle Cloud Administrator before they can start using the service. For more information on how to obtain your tenant user information, see Using Oracle Compute Cloud Service.

Topics:

- Discover Tenants

- Get Tenant

- List Tenants

Discover Tenants

This API enables you to discover existing tenants 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

/tenant/container/

URI

https://api_endpoint/tenant/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for the tenant. For example, / .

Example URI

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

Example Response Body

{"result": ["/mytenant", "/oracle"]}

Get Tenant

This API enables you to retrieve information for a specific tenant.

Method

GET

REST Resource

/tenant/name

URI

https://api_endpoint/tenant/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for a tenant. For example, /mytenant.

Example URI

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

Example Response Body

{
"description": "my tenant",
"dnszone": "mytenant.public.host1.us.oracle.com.",
"public_pkey": "0x1413",
"uri": "https://api/tenant/mytenant",
"private_pkey": "0x1412",
"type": "14.1.15-20150709.213443-dev",
"email": "abd@oracle.com",
"name": "mytenant"
}

List Tenants

This API enables you to list details about tenants in a specific container.

Method

GET

REST Resource

/tenant/container

URI

https://api_endpoint/tenant/container

URI Parameter

Parameter

Description

container

Hierarchical namespace for the tenant. For example, /.

Example URI

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

Example Response Body

{
list:[
{
description": "Cloud administration tenant",
"public_pkey": null,
"uri": "https://api/tenant/cloud",
"private_pkey": null,
"type": null, "email": null,
"name": "cloud"
},
{
"description": "ics-c2 tenant admin",
"public_pkey": "0x140f",
"uri": "https://api/tenant/ics-c2",
"private_pkey": "0x140e",
"type": "14.1.15-20150709.213443-dev",
"email": "ics-c2@ics.com",
"name": "ics-c2"
},
{
"description": "my tenant",
"public_pkey": "0x1413",
"uri": "https://api/tenant/mytenant",
"private_pkey": "0x1412",
"type": "14.1.15-20150709.213443-dev",
"email": "abd@example.com",
"name": "mytenant"
}]
}

Viewing Tenant Quotas

Quota defines the resource usage limit set for a tenant. The Oracle Cloud Administrator determines the quota limits for the tenant.

Topics:

- Discover Quota

- Get Quota

- List Quota

Discover Quota

This API enables you retrieve tenant quotas in the specified container and sub containers.

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

/quota/container

URI

https://api_endpoint/quota/container

URI Parameter

Parameter

Description

container

Hierarchical namespace for a tenant. For example, /

Example URI

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

Example Response Body

{
"list":
[
"/default",
"/mytenant",
]
}

Get Quota

This API enables you to retrieve the quota information for a specific tenant.

Method

GET

REST Resource

/quota/name

URI

https://api_endpoint/quota/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for a tenant. For example, /mytenant.

Example URI

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

Example Response Body

"list": [
{
"usage": {
"machineimage": {
"number": 2,
"megabytes": 4247
},
"vnet": {
"vnetreservations": 3
},
"compute": {
"instances": 6,
"ram": 46080,
"instance_restrictions": {},
"cpus": 12.0
},
"nds": {
"megabytes": 181468
}
},
"uri": "http://api.oc.example.com./quota/mytenant",
"description": "Default quota for \"mytenant\"",
"name": "/mytenant",
"allowance": {
"machineimage": {
"number": 5,
"megabytes": 100000
},
"vnet": {
"vnetreservations": null
},
"compute": {
"instances": 10,
"ram": 50000,
"instance_restrictions": {},
"cpus": 20.0
},
"nds": {
"megabytes": 200000
}
}
}
]
}

List Quota

This API enables you to list details about the tenant quotas for a specific container.

Method

GET

REST Resource

/quota/container

URI

https://api_endpoint/quota/container

URI Parameters

Parameter

Description

container

(Optional) Hierarchical namespace for tenant. For example, /mytenant/

Example URI

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

Example Response Body

{
"list": [
{
"usage":
{
"machineimage": {"number": 0, "megabytes": 0},
"vnet": {"vnetreservations": 0},
"compute": { "instances": 0,"ram": 0, "instance_restrictions": {}, "cpus": 0.0 },
"nds": {"megabytes": 0 }
},
"uri": "https://api/quota/ics2",
"description": "Default quota for \"ics2\"",
"name": "/ics2",
"allowance":
{
"machineimage": {"number": null,"megabytes": null},
"vnet": {"vnetreservations": null},
"compute": {"instances": null,"ram": null, "instance_restrictions": {}, "cpus": null},
"nds": {"megabytes": null}
}
},
{
"usage":
{
"machineimage": {"number": 1,"megabytes": 1380 },
"vnet": {"vnetreservations": 0},
"compute": {"instances": 1,"ram": 8192,"instance_restrictions": {},"cpus": 2.0},
"nds": {"megabytes": 17180}
},
"uri": "https://api/quota/e2fmigration-s29",
"description": "\"Account Quota\"",
"name": "/e2fmigration-s29",
"allowance":
{
"machineimage": {"number": null,"megabytes": null},
"vnet": {"vnetreservations": null },
"compute": {"instances": null, "ram": 24576, "instance_restrictions": {},"cpus": 10.0},
"nds": {"megabytes": null}
}
},
{
"usage":
{
"machineimage": {"number": 0, "megabytes": 0},
"vnet": { "vnetreservations": 0},
"compute": {"instances": 0,"ram": 0,"instance_restrictions": {}, "cpus": 0.0 },
"nds": {"megabytes": 0}
},
"uri": "https://api/quota/ics1",
"description": "Default quota for \"ics1\"",
"name": "/ics1",
"allowance":
{
"machineimage": {"number": null, "megabytes": null },
"vnet": {"vnetreservations": null },
"compute": {"instances": null, "ram": null, "instance_restrictions": {},  "cpus": null },
"nds": { "megabytes": null }
}
}
}
]}

5 User Management

A user is an entity within the system that is able to make requests. Each user is associated with one tenant, and has an associated role. The user's role determines the actions that the user is allowed to take. Tenant administrators manage users within their tenancy. Users have the /tenant_name/users role by default. Only the Oracle Cloud Administrator can grant a user the /tenant_name/admin role.

Topics:

- Managing Users

Managing Users

User names are unique within a specific tenant, and tenant names are unique within the system as a whole.

Topics:

- Add User

- Delete User

- Update User

- Retrieve User Details

Add User

This API enables you to add new users.

Note:
Only a tenant administrator can add new users.

Method

POST

REST Resource

/user/

URI

https://api_endpoint/user/

Request Body Parameters

Parameter

Description

username

A unique hierarchical name for a user. For example, /mytenant/myuser.
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

fullname

Full name of the user

email

Valid email address

role

(Optional) The role of a user in the system.
This option is used by the cloud administrator. A tenant administrator can discard this option. Oracle Cloud Administrator uses the role option to add one of the following roles to a user:

- /cloud/admin for cloud administrators.

- /cloud/monitor for cloud monitors.

- /tenant_name/admin for tenant administrators.

- /tenant_name/users for tenant users

If this option is not specified, then the default role of /tenant_name/users is granted.

password

(Optional) User password.
The password for a user must meet the following requirements:

- Alphanumeric.

- At least 6 characters in length.

- At least 5 unique characters. For example, "azylaz" is not a valid password but "azylmz" is valid.

- Can contain underscore and dash.

- Must not contain a sequence of characters. For example, "abcde1" and "asdfgh" are not valid passwords.

- Must not contain a dictionary word.

Example URI

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

Example Request Body

{
"username": "/mytenant/myuser",
"blacklisted": false,
"uri": null,
"role": "",
"groups": [],
"fullname": "myuserfullname",
"password": "zaqwsx1234",
"email": "myuser@example.com"
}

Example Response Body

{
"username": "/mytenant/myuser",
"customer": "mytenant",
"blacklisted": false,
"uri": "https://api/user/mytenant/myuser",
"id": "f36f54ca-e8d2-4e56-93acae392c4f1",
"role": "/mytenant/users",
"groups": ["/mytenant/users"],
fullname": "myuserfullname",
"password": "",
"email": "myuser@example.com"
}

Delete User

This API enables you to delete an existing user.

Method

DELETE

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter

Description

name

Hierarchical name of the user to be deleted. For example, /mytenant/myuser, and /cloud/myuser

Example URI

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

Update User

This API enables you to update user information.

Note:

Tenant users can only update their password and email address.

Method

PUT

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for a user. For example, /mytenant/myuser and /cloud/myuser

Request Body Parameters

Parameter

Description

fullname

(Optional) Full name of the user

email

(Optional) Valid email address

role

(Optional) The role of a user in the system.
This option is used by the cloud administrator. A tenant administrator can discard this option. A cloud administrator uses the role option to add one of the following roles to a user:

- /cloud/admin for cloud administrators.

- /cloud/monitor for cloud monitors.

- /tenant_name/admin for tenant administrators.

- /tenant_name/users for tenant users

password

(Optional) User password.
The password for a user must meet the following requirements:

- Alphanumeric.

- At least 6 characters in length.

- At least 5 unique characters. For example, "azylaz" is not a valid password but "azylmz" is valid.

- Can contain underscore and dash.

- Must not contain a sequence of characters. For example, "abcde1" and "asdfgh" are not valid passwords.

- Must not contain a dictionary word.

blacklisted

(Optional) Specifies if the user is blacklisted

Example URI

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

Example Request Body

{
"username": "/mytenant/myuser",
"fullname": "myuserfullname",
"password": "",
"email": "new.email@example.com"
}

Example Response Body

{
"username": "/mytenant/myuser",
"customer": "mytenant",
"blacklisted": false,
"uri": "https://api/user/mytenant/myuser",
"id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1",
"role": "/mytenant/users",
"groups": ["/mytenant/users"],
"fullname": "myuserfullname",
"password": "",
"email": "new.email@example.com"
}

Retrieve User Details

You can retrieve the user details using REST APIs.

Topics:

- Discover Users

- Get User

- List Users

Discover Users

This API enables you to discover a list of users 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

/user/container

URI

https://api_endpoint/user/container

URI Parameters

Parameter

Description

container

Hierarchical name-space for users.

Example URI

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

Example Response Body

{"result": ["/mytenant/administrator", "/mytenant/user123"]}

Get User

This API enables you to retrieve information for a specific user.

Method

GET

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter

Description

name

Hierarchical name of the user. For example, /mytenant/myuser and /cloud/myuser

Example URI

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

Example Response Body

{
"username": "/mytenant/myuser",
"customer": "mytenant",
"blacklisted": false,
"uri": "https://api/user/mytenant/myuser",
"id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1",
"role": "/mytenant/users",
"groups": ["/mytenant/users"],
"fullname": "myuserfullname",
"password": "",
"email": "myuser@example.com"
}

List Users

This API enables you to list users in a specific container.

Note:
You can list only tenant users in your tenancy.

Method

GET

REST Resource

/user/name

URI

https://api_endpoint/user/container?role=roleValue

URI Parameters

Parameter

Description

container

Hierarchical name-space for the user.

role=roleValue

(Optional) The role of a user in the system.
You can filter the list output based on user role by specifying one of the following:

- /cloud/admin for cloud administrators

- /cloud/monitor for cloud monitors

- /tenant_name/admin for tenant administrators

- /tenant_name/users for tenant users.

Example URI

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

Example Response Body

{"result": [
{
"username": "/mytenant/administrator",
"customer": "mytenant", "blacklisted": false,
"uri": "https://api/user/mytenant/administrator",
"id": "1ccf2e90-39aa-4b73-bca8-da9fdf8c6441",
"role": "/mytenant/admin",
"groups": ["/mytenant/admin"],
"fullname": "Administrator", "password": "",
"email": "myuser@example.com"
},

{
"username": "/mytenant/myuser",
"customer": "mytenant",
"blacklisted": false,
"uri": "https://api/user/mytenant/myuser",
"id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1",
"role": "/mytenant/users",
"groups": ["/mytenant/users"],
"fullname": "myuserfullname",
"password": "",
"email": "myuser@example.com"
}
]}

6 Instance and Snapshot Management

This section describes the various operations that can be performed for managing instances and snapshots.

Topics:

- Managing Instances

- Managing Snapshots

- Managing SSH Keys

- Managing Orchestrations

- Viewing Shapes

- Connecting to an Instance VNC Console

Managing Instances

An instance is a logical representation of a virtual machine (VM). An instance defines the properties of a virtual machine and has a life cycle that surrounds and extends beyond the life cycle of a single virtual machine. You create virtual machine instances by starting orchestrations, but you can manage them individually thereafter by using CLI commands or API requests.

Note:
Life-cycle commands (such as start, stop, restart etc.) that change the state of an instance, return immediately with the state change proceeding on the server side. Instance state can be monitored by retrieving the instance details.

Topics:

- Delete Instance

- Restart Instance

- Shutdown Instance

- Update Instance

- Retrieve Instance Details

Delete Instance

This API request enables you to delete a specific instance. You can delete an instance only when it is in any of the following states:running, shut_down, or error.

Note:
When an instance is deleted, the associated orchestration transitions to the warning state. You need to stop and start this orchestration if you want to associate it with a new instance.

Method

DELETE

REST Resource

/instance/name

URI

https://api_endpoint/instance/name

URI Parameter

Parameters

Description

name

A unique hierarchical name of an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5.

Example URI

https://api.oc.example.com/instance/mytenant/admin/f653a677-b566-4f92-8e93-71d47b364119

Restart Instance

This API request enables you to restart a specific instance. You can restart an instance only when it is in one of the following states: shut_down, warning, or error.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name?action=RESTART

URI Parameters

Parameter

Description

name

A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Example URI

https://api.oc.example.com/instance/mytenant/public/test123/6fffcc31-5fc4-4d68-828e-5310229f8840?action=RESTART

Shutdown Instance

This API request enables you to shutdown an instance.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name?action=SHUTDOWN

URI Parameters

Parameter

Description

name

A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Example URI

https://api.oc.example.com/instance/mytenant/public/test123/6fffcc31-5fc4-4d68-828e-5310229f8840?action=SHUTDOWN

Update Instance

This API request enables you to update parameters for a specific instance.

Method

PUT

REST Resource

/instance/name/

URI

https://api_endpoint/instance/name

URI Parameters

Parameter

Description

name

A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5e.

Request Body Parameters

To update an instance, use the GET /instance/name API to fetch the existing list of instance parameters. You can use this list of instance parameters to make desired changes, and re-send it as part of the PUT /instance/name API request body.

Note:
You cannot modify all the parameters of the instance.

The following table lists the instance parameters that can be modified.

Parameter

Description

shape

(Optional) The name of the shape to be associated with the instance. You can update the shape only when the instance is in the shut_down state.

networking

(Optional) Mapping of device name to network specifiers for virtual NICs to be attached to this instance. You can update the instance when it is either in the running state or shut_down state.

nis

(Optional) Network Information Service (NIS) configuration. You can update the NIS configuration only when the instance is in the running state or shut_down state.

Note:
The nis parameter appears in two places in the instances definition. You must update the first occurrence.

tags

(Optional) Instances can be tagged with a list of user-friendly strings that identify a specific instance. You can add tags to the instance in any state.

For more information on Instance optional parameters, see section Orchestration Templates in Using Oracle Compute Cloud Service.

Example URI

http://api.oc.example.com/instance/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f

Example Request Body

{
"domain": "mytenant.public.host1.example.com.",
"placement_requirements": ["/system/compute/placement/default",
"/system/compute/allow_instances", "/system/infiniband/ready"],
"ip": "192.168.120.4",
"fingerprint": "",
"site": "",
"shape": "oc1",
"nis": {"domain": "mytenant-domain", "servers": [{"ip": "111.11.11.111","name": "mytenant.nis.server1"}]},
"imagelist": "/oracle/public/linux5_12.2.1.0.0_64",
"networking": {"eth1": {"vnet": "/oracle/public/IPoIB-virt-admin",
"dns": ["e47fdb.mytenant.public.host1.example.com."]}},
"storage_attachments": [],
"hostname": "e47fdb.mytenant.public.host1.example.com.",
"quota_reservation": "/mytenant/cb4f9ecf-5ac7-4496-b8c9-26c10be8207c",
"disk_attach": "",
"label": "test2",
"priority": "/oracle/public/default",
"state": "shut_down",
"virtio": false,
"vnc": "10.0.0.49:5900",
"tags": ["/mytenant/public/func_storage_12","78992f1753f37e2a687f743c0df14d38", "new tag"],
"start_time": "2015-12-28T22:46:48Z",
"quota": "/mytenant",
"last_shutdown_time": null,
"attributes":
{
"nis": {},
"network": {"nimbula_vcable-eth1": {"net_config": {"owner": {"type":
"svcnet", "name": "IPoIB-virt-admin-2"}, "ip": "192.168.120.4",
"netmask": "255.255.248.0", "type": "IPoIB", "membership": "limited"},
"vethernet_id": "-1", "options": {}, "vethernet":
"/oracle/public/IPoIB-virt-admin", "address": [null, "192.168.120.4"],
"model": "", "vethernet_type": "ipoib", "id":
"/mytenant/public/02855c15-c088-4f33-a120-dbe0c31388ae", "dhcp_options":[]}},
"nimbula_orchestration": "/mytenant/public/func_storage_12",
"dns": {"domain": "mytenant.public.host1.example.com.", "hostname":
"e47fdb.mytenant.public.host1.example.com.", "nimbula_vcable-eth1":
"e47fdb.mytenant.public.host1.example.com."},
"sshkeys": []
},
"error_reason": null,
"sshkeys": null,
"resolvers": null,
"account": "/mytenant/default",
"name":
"/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f",
"vcable_id": "/mytenant/public/02855c15-c088-4f33-a120-dbe0c31388ae",
"uri":
"http://api.oc.example.com/instance/mytenant/public/func_storage_12/2/c041981f-99a6-4af2-a31d-b3dce1fe719f",

"reverse_dns": true,
"entry": 1,
"boot_order": []
}

Retrieve Instance Details

You can retrieve instance details by using the REST API.

Topics:

- Discover Instances

- Get Instance

- List Instances

Discover Instances

This API request enables you to discover instances in the specific container and subcontainers.

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

/instance/container/

URI

https://api_endpoint/instance/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace containing instances

Example URI

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

Example Response Body

{"result":
[
"/mytenant/public/primary_webserver/",
"/mytenant/public/secondary_webserver/"
]
}

Get Instance

This API request enables you to retrieve information for a specific instance.

Method

GET

REST Resource

/instance/name

URI

https://api_endpoint/instance/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for an instance. For example, /mytenant/public/e6640ebc-6953-444f-848d-4a3bf6050ea5

Example URI

https://api.oc.example.com/instance/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119

Example Response Body

{
"list": [
{
"domain": "mytenant...",
"placement_requirements": [
"/system/compute/placement/default",
"/system/compute/allow_instances"
],
"ip": "10...",
"site": "",
"shape": "oc5",
"imagelist": "/oracle/public/oel_6.4_60GB",
"attributes": {
"network": {
"nimbula_vcable-eth0": {
"vethernet_id": "0",
"vethernet": "/oracle/public/default",
"address": [
"c6:b0:09:f4:bc:c0",
"0.0.0.0"
],
"model": "",
"vethernet_type": "vlan",
"id": "/mytenant/public/016e75e7-e911-42d1-bfe1-6a7f1b3f7908",
"dhcp_options": []
}
},
"dns": {
"domain": "mytenant...",
"hostname": "d06886.mytenant...",
"nimbula_vcable-eth0": "d06886.mytenant..."
},
"sshkeys": [
"ssh-rsa AAAAB3NzaC1yc2EAAA..."
]
},
"networking": {
"eth0": {
"model": "",
"dns": [
"d06886.mytenant..."
],
"seclists": [
"/mytenant/default/default",
"/mytenant/public/prod-ng"
],
"vethernet": "/oracle/public/default",
"nat": "ipreservation:/mytenant/public/prod-vm1"
}
},
"hostname": "d06886.mytenant...",
"quota_reservation": "/mytenant/ffc8e6d4-8f93-41f3-a062-bdbb042c3191",
"disk_attach": "",
"label": "Production instance 1",
"priority": "/oracle/public/default",
"state": "running",
"vnc": "10...",
"storage_attachments": [
{
"index": 1,
"storage_volume_name": "/mytenant/public/prod-vol1",
"name": "/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119/f1a67244-9abc-45d5-af69-8..."
}
],
"start_time": "2014-06-24T17:51:35Z",
"quota": "/mytenant",
"fingerprint": "19:c4:3f:2d:dc:76:b1:06:e8:88:bd:7f:a3:3b:3c:93",
"error_reason": "",
"sshkeys": [
"/mytenant/public/mytenant-prod-admin"
],
"tags": [
"prod2"
],
"resolvers": null,
"account": "mytenant/default",
"name": "/mytenant/public/dev1/f653a677-b566-4f92-8e93-71d47b364119",
"vcable_id": "/mytenant/public/016e75e7-e911-42d1-bfe1-6a7f1b3f7908",
"uri": "http://10....",
"reverse_dns": true,
"entry": 1,
"boot_order": []
}
]
}

List Instances

This API request enables you to retrieve instance information in a specific container or subcontainer.

Method

GET

REST Resource

/instance/container/

URI

https://api_endpoint/instance/container/?tags=tagValue&quota=quotaValue&vcable_id=vcable_idValue

URI Parameters

Parameters

Description

container

Hierarchical name-space for instances

tags=tagValue

(Optional) Instances can be tagged with a list of user-friendly strings that identify a specific instance

quota=quotaValue

(Optional) The name of a quota associated with an instance

vcable_id=vcable_idValue

(Optional) The unique identifier of a virtual cable (vCable) associated with an instance

Example URI

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

Example Response Body

{
"result":
[{
"domain": "mytenant.public.oc.example.com.",
"placement_requirements": ["/system/compute/placement/default",
"/system/compute/allow_instances",
"/system/infiniband/ready"],
"ip": "10.128.206.94",
"fingerprint": "08:8f:8f:f9:f4:3c:19:ee:11:3c:0a:1f:fd:ee:1d:e9",
"site": "",
"shape": "oc3",
"nis": {},
"imagelist": null,
"networking": {"eth0": {"seclists": [],
"vnetreservation": "/mytenant/public/instance1-wls-vm-1-instance1-wls-1-svcnet-1",
"options":
{
"hostname": "instance1-wls-1",
"network_route": [],
"dns": {"search_domains": "mytenant.public.oc.example.com", "servers": "192.168.126.1,192.168.126.2"}
},
"dns": [],
"address": []}, "eth4": {"seclists": [], "vnet": "/cloud/public/EoIB-OMS-c2", "dns": [], "address": []
............
}

Managing Snapshots

A snapshot is a copy of the machine image boot disk taken at a specific time from an instance that is in running or shutdown state. You can add this copy to image lists, and use it to create a new instance.
Instance modifications are not preserved when an instance is deleted as a result of stopping an orchestration. Deleting an instance also removes all customizations and changes made to the boot disk since its creation. To keep the customized virtual machine (VM), create a snapshot to preserve the machine image. Then use the snapshot to create new VMs with the same customizations.

Note:
Another way to preserve customizations is to shut down that instance to free CPU and memory resources. When the VM is restarted, its customizations remain in effect. For more information about shutting down VM, see Shutdown Instance.

Topics:

- Add Snapshot

- Delete Snapshot Request

- Retrieve Snapshot Details

Add Snapshot

This API enables you to add a snapshot.

Method

POST

REST Resource

/snapshot/

URI

https://api_endpoint/snapshot/

Request Body Parameters

Parameter

Description

instance

Instance for which snapshot must be taken

name

(Optional) Unique identifier of the Snapshot which replaces the identifier generated by the server.
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

quota

(Optional) Quota against which this snapshot will be stored

machineimage

(Optional) Unique identifier of the machine image. If you do not provide this option, then the unique identifier is generated by the server.

Example URI

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

Example Request Body

{
"instance": "/mytenant/administrator/a6fbb572-a584-486a-9314-56a24499028d",
"name": null,
"quota": null,
"machineimage": "/mytenant/administrator/snapshot1"
}

Delete Snapshot Request

This API enables you to delete a snapshot creation request. This deletes only the request; the machine image that was the result of the request is not removed.

The following restrictions apply for deleting a snapshot request:

- Requests in the active state cannot be deleted.

- Requests can only be deleted when they are in the error or complete state.

Method

DELETE

REST Resource

/snapshot/name

URI

https://api_endpoint/snapshot/name

URI Parameter

Parameter

Description

name

Snapshot unique identifier

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec

Retrieve Snapshot Details

You can retrieve the snapshot details by using the REST APIs.

Topics:

- Discover Snapshots

- Get Snapshot

- List Snapshots

Discover Snapshots

This API enables you to discover snapshots 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

/snapshot/container/

URI

https://api_endpoint/snapshot/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for snapshots

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/

Example Response Body

{"result":
[
"/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec",
"/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/df8caca5-8a27-4153-9c5f-7440080b40c8"
]
}

Get Snapshot

This API enables you to retrieve details for a specific snapshot.

Method

GET

REST Resource

/snapshot/name

URI

https://api_endpoint/snapshot/name

URI Parameter

Parameter

Description

name

Snapshot unique identifier

Example URI

https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec

Example Response Body

{
"instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
"account": "/mytenant/default",
"platform": "linux",
"name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec",
"client_owned": true,
"sizes": {},
"creation_time": "2015-08-20T06:54:58Z",
"uri": "https://10.32.80.5/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec",
"quota": null,
"delay": "",
"instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d",
"machineimage": "/mytenant/public/snapshot1",
"state": "complete",
"quota_reservation": null,
"user": "/mytenant/public",
"file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-4dbb2b4c-d315-47ba-b938-696f74826bec-snapshot.tar.gz",
"request_id": "4dbb2b4c-d315-47ba-b938-696f74826bec",
"error_reason": "",
"image_format": "raw"
}

List Snapshots

This API enables you to list information about snapshots in a specific container.

Method

GET

REST Resource

/snapshot/{container |name}

URI

https://api_endpoint/snapshot/container | name?quota=quotaValue&instance=instanceValue&machineimage=machineimageValue

URI Parameters

Note:
The output of this command is filtered based on the optional parameters (if specified).

Parameter

Description

container

Hierarchical namespace for snapshots

name

(Optional) Unique identifier of the Snapshot which replaces the identifier generated by the server

quota=quotaValue

(Optional) Quota against which this snapshot is stored

instance=instanceValue

(Optional) Instance for which the snapshot should to be taken

machineimage=macineimageValue

(Optional) Unique identifier of the machine image. If you do not provide this option, then the unique identifier is generated by the server.

Example URI

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

Example Response Body

{"result":[
{
"instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
"account": "/mytenant/default",
"platform": "linux",
"name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec",
"client_owned": true,
"sizes": {},
"creation_time": "2015-08-20T06:54:58Z",
"uri": "https://api.ic.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/4dbb2b4c-d315-47ba-b938-696f74826bec",
"quota": null,
"delay": "",
"instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d",
"machineimage": "/mytenant/public/snapshot1",
"state": "complete",
"quota_reservation": null,
"user": "/mytenant/public",
"file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-4dbb2b4c-d315-47ba-b938-696f74826bec-snapshot.tar.gz",
"request_id": "4dbb2b4c-d315-47ba-b938-696f74826bec",
"error_reason": "",
"image_format": "raw"
},
{
"instance_id": "a6fbb572-a584-486a-9314-56a24499028d",
"account": "/mytenant/default",
"platform": "linux",
"name": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/0b0ef87a-a7c8-46b3-8cdc-3315a203a431",
"client_owned": true,
"sizes": {},
"creation_time": "2015-08-20T06:54:58Z",
"uri": "https://api.oc.example.com/snapshot/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d/0b0ef87a-a7c8-46b3-8cdc-3315a203a431",
"quota": null,
"delay": "shutdown",
"instance": "/mytenant/public/a6fbb572-a584-486a-9314-56a24499028d",
"machineimage": "/mytenant/public/snapshot2",
"state": "active",
"quota_reservation": null,
"user": "/mytenant/public",
"file": "hdfs:///bimage/a6fbb572-a584-486a-9314-56a24499028d-0b0ef87a-a7c8-46b3-8cdc-3315a203a431-snapshot.tar.gz",
"request_id": "0b0ef87a-a7c8-46b3-8cdc-3315a203a431",
"error_reason": "",
"image_format": "raw"
}
]}

Managing SSH Keys

You can automate the login process to instances by using the SSH keys.

Topics:

- Add Public SSH Key

- Delete SSH Key

- Update SSH Key

- Retrieve SSH Key Details

Add Public SSH Key

This API enables you to import a new public SSH key and associate it to a user.

Method

POST

REST Resource

/sshkey

URI

https://api_endpoint/sshkey/

Request Body Parameters

Parameter

Description

name

Name of the SSH key.
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

key

SSH public key value

enabled

(Optional) Specifies if the SSH key is enabled or disabled.  The default value is True.

osuser

(Optional) Operating system user to which this key will be assigned.  If this option is not specified, no key is installed in the VM.

Example URI

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

Example Request Body

{
"osuser": "oracle",
"enabled": true,
"key": "ssh-rsa AA16hLNo4kWmYslf....leo@t410....",
"name": "/mytenant/public/oracle_key1"
}

Example Response Body

{
"osuser": "oracle",
"enabled": true,
"uri": "https://api/sshkey/mytenant/public/oracle_key1",
"key": "ssh-rsa AA16hLNo4kWmYslf....leo@t410....",
"name": "/mytenant/public/oracle_key1"
}

Delete SSH Key

This API enables you to delete a specific SSH key.

Method

DELETE

REST Resource

/sshkey/name

URI

https://api_endpoint/sshkey/name

URI Parameter

Parameter

Description

name

Name of the SSH key to be deleted

Example URI

https://api.oc.example.com/sshkey/mytenant/public/key1

Update SSH Key

This API enables you to update/overwrite the key, the enabled field, and the osuser field for a specific SSH key.

Method

PUT

REST Resource

/sshkey/name

URI

https://api_endpoint/sshkey/name

URI Parameter

Parameters

Description

name

Name of the SSH key

Request Body Parameters

Parameters

Description

key

(Optional) Name of the file that contains the value of the SSH public key

enabled

(Optional) Specifies if the key is enabled or disabled. The default value is True

osuser

(Optional) OS user to which this key will be assigned

Example URI

https://api.oc.example.com/sshkey/mytenant/public/myuser

Example Request Body

{
"osuser": "myuser"
"enabled": true,
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0ibAEmysI4o1zf...",
"name": "/mytenant/public/myuser"
}

Example Response Body

{
"osuser": "myuser"
"enabled": true,
"uri": "https://api.oc.example.com/sshkey/mytenant/public/myuser",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0ibAEmysI4o1zfb4dOJIyaN67pya8A...",
"name": "/mytenant/public/myuser"
}

Retrieve SSH Key Details

You can retrieve SSH Key details by using the REST API.

Topics:

- Discover SSH Keys

- Get SSH Key

- List SSH Keys

Discover SSH Keys

This API enables you to discover SSH keys in a specific container and subcontainer.

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

/sshkey/container/

URI

https://api_endpoint/sshkey/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for SSH key

Example URI

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

Example Response Data

{
"result": [
"/mytenant/public/adminkey",
"/mytenant/public/permkey",
"/mytenant/public/tempkey"
]
}

Get SSH Key

This API enables you to retrieve information for a specific SSH key..

Method

GET

REST Resource

/sshkey/name

URI

https://api_endpoint/sshkey/name

URI Parameter

Parameter

Description

name

Name of the SSH key, for which information is retrieved

Example URI

https://api.oc.example.com/sshkey/mytenant/public/oracle_key1

Example Response Data

{
"osuser": "oracle",
"enabled": true,
"uri": "https://api/sshkey/mytenant/public/oracle_key1",
"key": "ssh-rsa AAAAB3LNo4kWmYslf...leo@t410.....",
"name": "/mytenant/public/oracle_key1"
}

List SSH Keys

This API enables you to list SSH key information in a specific container and subcontainer.

Method

GET

REST Resource

/sshkey/container/

URI

https://api_endpoint/sshkey/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for the SSH key

Example URI

https://api.oc.example.com/sshkey/mytenant/public/myuser

Example Response Data

{
"osuser": "myuser",
"enabled": true,
"uri": "https://api.oc.example.com/sshkey/mytenant/public/myuser",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0ibAEmysI4o1zfb4dOJIyaN67pya8A...AWS",
"name": "/mytenant/public/myuser"
}

Managing Orchestrations

Orchestration automates the management of your system components for high availability, monitoring, and persistence.

Orchestration ties together the components that you create into a single, manageable collection. In addition, you can specify the dependencies to control the sequence in which the components are created. For example, you can coordinate the creation of network and storage resources with the creation of the instance and, if high availability is enabled, restart the instance automatically if it terminates unexpectedly. In Oracle Compute Cloud Service, all instances are created using orchestrations.

Note:
Life-cycle commands (such as start, stop, restart etc.) that change the status of an orchestration, return immediately with the status change proceeding on the server side. Orchestration status can be monitored by retrieving the orchestration details.

For more information about procedures related to orchestrations, see Orchestration Templates in Using Oracle Compute Cloud Service.

Topics:

- Add Orchestration

- Delete Orchestration

- Start Orchestration

- Stop Orchestration

- Shutdown Orchestration

- Restart Orchestration

- Update Orchestration

- Retrieve Orchestration Details

Add Orchestration

This API enables you to create a new orchestration from a JSON definition.

Method

POST

REST Resource

/orchestration/

URI

https://api_endpoint/orchestration/

Request Body Parameters

The JSON format of the orchestration is passed in the request body. For more information about the format and attributes of an orchestration JSON file, see section Orchestration Templates in Using Oracle Compute Cloud Service.

Example URI

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

Example Request Body

{
"relationships": [],
"account": null,
"description": "",
"schedule": {"start_time": null, "stop_time": null},
"uri": null,
"oplans":
[{
"ha_policy": null,
"obj_type": "launchplan",
"objects":
[{
"instances":
[{
"imagelist": "/oracle/public/linux6_12.2.1.0.0_64",
"networking":
{
"net1": {"vnet": "/mytenant/public/ipoib1"},
"net0": {"vnet": "/mytenant/public/eoib1"}
},
"shape": "oc3",
"label": "pv-mixed1"
}]
}],
"label": "pv-mixednet"
}],
"name": "/mytenant/public/pv-mixed1"
}

Example Response Body

{
"relationships": [],
"status": "stopped",
"account": "/mytenant/default",
"description": "",
"schedule": {"start_time": null, "stop_time": null},
"uri": "http ://api/orchestration/mytenant/public/pv-mixed1",
"oplans":
[{
"status": "stopped",
"info": {},
"obj_type": "launchplan",
"ha_policy": "",
"label": "pv-mixednet",
"objects":
[{
"instances":
[{
"imagelist": "/oracle/public/linux6_12.2.1.0.0_64",
"uri": null,
"networking":
{
"net1": {"vnet": "/mytenant/public/ipoib1"},
"net0": {"vnet": "/mytenant/public/eoib1"}
},
"shape": "oc3",
"label": "pv-mixed1"
}]
}],
"status_timestamp": null
}],
"info": {},
"status_timestamp": null,
"name": "/mytenant/public/pv-mixed1"
}

Delete Orchestration

This API enables you to delete an orchestration from the system. Only orchestrations with stopped status can be deleted.

Method

DELETE

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name

URI Parameter

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch

Example URI

https://api.oc.example.com/orchestration/mytenant/public/myorch

Start Orchestration

This API enables you to start a specific orchestration. Only orchestrations with stopped status can be started.

Starting an orchestration creates all the objects defined in the orchestration. The state of the orchestration changes as the start operation progresses. The start API request returns the response immediately, however the start operation continues on the server. The start operation is completed only when the orchestration reaches the ready status.

Method

PUT

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name?action=START

URI Parameter

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch

action

(Optional) Specifies the action that should be performed on the orchestration. For this API, the valid value of this parameter is START.

Example URI

https://api.oc.example.com/orchestration/mytenant/public/user1/test-vm?action=START

Example Response Body

{
"result":
[
{
"relationships": [],
"status": "starting",
"account": "/mytenant/default",
"description": "",
"schedule": {"start_time": "2015-10-23T09:58:52Z", "stop_time": null},
"uri": "https://api/orchestration/mytenant/public/mytenantdb",
"oplans":     [{ .....}]
"status_timestamp": "2015-10-23T10:01:02Z"}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-10-23T10:01:02Z",
"name": "/mytenant/public/db"
}
]
}

Stop Orchestration

This API enables you to stop a specific orchestration. Stopping an orchestration deletes all instances, releasing all resources allocated by the orchestration. This includes boot (root) disks and unreserved IP addresses. You can stop orchestrations in any one of the following statuses:ready, shutdown, warning, and error. The orchestration can be started again, thereby creating new instances and allocating new resources.

Method

PUT

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name?action=STOP

URI Parameters

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch

action

(Optional) Specifies the action which should be performed on the orchestration. The valid value of this parameter for this API is STOP.

Example URI

https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=STOP

Example Response Body

{
"account": "/mytenant/default",
"description": "",
"info": {
"errors": {},
"warnings": {}
},
"name": "/mytenant/public/dev-vm",
"oplans": [
{
"ha_policy": "",
"info": {
"errors": {},
"warnings": {}
},
"label": "sj-dev-vm",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
"imagelist": "/oracle/public/oel6",
"ip": "10.128.0.10",
"label": "sj-oel6-vm",
"name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e",
"networking": {
"eth0": {
"dns": [
"ccd371.mytenant.public.t1700-4186.example.com."
],
"seclists": [
"/mytenant/default/default"
],
"vethernet": "/oracle/public/default"
}
},
"shape": "small",
"start_time": "2015-11-23T21:15:32Z",
"state": "stopping",
"uri": null
}
]
}
],
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z"
}
],
"relationships": [],
"schedule": {
"start_time": "2015-11-23T21:15:27Z",
"stop_time": "2015-11-24T18:43:13Z"
},
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z",
"uri": "http://api/orchestration/mytenant/public/dev-vm"
}

Shutdown Orchestration

This API enables you to shut down a VM instance while preserving the resources used by the instance, such as IP addresses and boot disk contents. When the orchestration is restarted, it gets back the same boot disks and IP addresses. If you do not need to preserve these resources use stop orchestration. Orchestrations with a ready or warning state can be shut down.

Method

PUT

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name?action=SHUTDOWN

URI Parameters

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch.

action

(Optional) Specifies the action that should be performed on the orchestration. The valid value of this parameter for this API is SHUTDOWN.

Example URI

https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=SHUTDOWN

Example Response Body

{
"account": "/mytenant/default",
"description": "",
"info": {
"errors": {},
"warnings": {}
},
"name": "/mytenant/public/dev-vm",
"oplans": [
{
"ha_policy": "",
"info": {
"errors": {},
"warnings": {}
},
"label": "sj-dev-vm",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
"imagelist": "/oracle/public/oel6",
"ip": "10.128.0.10",
"label": "sj-oel6-vm",
"name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e",
"networking": {
"eth0": {
"dns": [
"ccd371.mytenant.public.t1700-4186.example.com."
],
"seclists": [
"/mytenant/default/default"
],
"vethernet": "/oracle/public/default"
}
},
"shape": "small",
"start_time": "2015-11-23T21:15:32Z",
"state": "shutting_down",
"uri": null
}
]
}
],
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z"
}
],
"relationships": [],
"schedule": {
"start_time": "2015-11-23T21:15:27Z",
"stop_time": "2015-11-24T18:43:13Z"
},
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z",
"uri": "http://api/orchestration/mytenant/public/dev-vm"
}

Restart Orchestration

This API enables you to restart an orchestration that was previously in the shut_down status. You can restart an orchestration with status warning, shut_down or error.

Method

PUT

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name?action=RESTART

URI Parameters

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch.

action

(Optional) Specifies the action to be performed on the orchestration. The valid value of this parameter for this API is RESTART.

Example URI

https://api.oc.example.com/orchestration/mytenant/public/dev-vm?action=RESTART

Example Response Body

{
"account": "/mytenant/default",
"description": "",
"info": {
"errors": {},
"warnings": {}
},
"name": "/mytenant/public/dev-vm",
"oplans": [
{
"ha_policy": "",
"info": {
"errors": {},
"warnings": {}
},
"label": "sj-dev-vm",
"obj_type": "launchplan",
"objects": [
{
"instances": [
{
"imagelist": "/oracle/public/oel6",
"ip": "10.128.0.10",
"label": "sj-oel6-vm",
"name": "/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e",
"networking": {
"eth0": {
"dns": [
"ccd371.mytenant.public.t1700-4186.example.com."
],
"seclists": [
"/mytenant/default/default"
],
"vethernet": "/oracle/public/default"
}
},
"shape": "small",
"start_time": "2015-11-23T21:15:32Z",
"state": "restarting",
"uri": null
}
]
}
],
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z"
}
],
"relationships": [],
"schedule": {
"start_time": "2015-11-23T21:15:27Z",
"stop_time": "2015-11-24T18:43:13Z"
},
"status": "ready",
"status_timestamp": "2015-11-23T21:18:11Z",
"uri": "http://api/orchestration/mytenant/public/dev-vm"
}

Update Orchestration

This API enables you to update information for a specific orchestration.

You can update any part of an orchestration aside from the name when it is in stopped status. When the orchestration is in ready status, you can update the ha_policy and label of an existing oplan in the orchestration. You can also add and remove oplans. Added oplans will be started, and removed oplans will be stopped.

Method

PUT

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name

URI Parameters

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch

Request Body Parameters

You can update the orchestration parameters in JSON format. For more information on the orchestration parameters, see section Orchestration Templates in Using Oracle Compute Cloud Service.

Example URI

https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms

Example Request Body

{
"relationships": [],
"status": "ready",
"account": "/mytenant/default",
"description": "",
"schedule":
{
"start_time": "2015-07-27T09:02:27Z",
"stop_time": null
},
"uri": "https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms",
"oplans":
[{
"status": "ready",
"info": {"errors": {}, "warnings": {}},
"obj_type": "launchplan",
"ha_policy": "active",
"label": "ac-control-vms",
"objects": [{"relationships": [{"instances": ["ac-control-vm1", "ac-control-vm2"], .........}],
"status_timestamp": "2015-09-17T22:54:14Z"
}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-09-17T22:54:14Z",
"name": "/mytenant/public/ac-control-vms"
}

Example Response Body

{
"relationships": [],
"status": "ready",
"account": "/mytenant/default",
"description": "",
"schedule":
{
"start_time": "2015-07-27T09:02:27Z",
"stop_time": null
},
"uri": "https://api.oc.example.com/orchestration/mytenant/public/ac-control-vms",
"oplans":
[{
"status": "ready",
"info": {"errors": {}, "warnings": {}},
"obj_type": "launchplan",
"ha_policy": "active",
"label": "ac-control-vms",
"objects": [{"relationships": [{"instances": ["ac-control-vm1", "ac-control-vm2"], .........}],
"status_timestamp": "2015-09-17T22:54:14Z"
}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-09-17T22:54:14Z",
"name": "/mytenant/public/ac-control-vms"
}

Retrieve Orchestration Details

You can retrieve the orchestration details by using the REST API.

Topics:

- Discover Orchestrations

- Get Orchestration

- List Orchestrations

Discover Orchestrations

This API enables you to discover orchestrations within a specific container or subcontainer.

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

/orchestration/container/

URI

https://api_endpoint/orchestration/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for the orchestrations

Example URI

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

Example Response Body

{
"result":
[
"/mytenant/public/el-control-vms",
"/mytenant/public/el-db-vms",
"/mytenant/public/scae09-sdi-sdivm-el1-4-storagevolume-app",
"/mytenant/public/scae09-sdi-sdivm-el1-5-storagevolume-ops",
"/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data",
"/mytenant/public/scae09-sdi-sdivm-el1-8-instance"
]
}

Get Orchestration

This API enables you to retrieve details of a specific orchestration.

Method

GET

REST Resource

/orchestration/name

URI

https://api_endpoint/orchestration/name

URI Parameter

Parameter

Description

name

A unique hierarchical name of an orchestration. For example, /mytenant/public/myorch

Example URI

https://api.oc.example.com/orchestration/mytenant/public/el-db-vms

Example Response Body

{
"relationships": [],
"status": "ready",
"account": "/mytenant/default",
"description": "",
"schedule": {"start_time": "2015-07-27T09:05:50Z", "stop_time": null},
"uri": "https://api/orchestration/mytenant/public/el-db-vms",
"oplans": [
{"status": "ready", "info": {"errors": {}, "warnings": {}}, "obj_type": "launchplan", "ha_policy": "active",.....}],
"status_timestamp": "2015-09-06T21:11:39Z"}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-09-06T21:11:39Z",
"name": "/mytenant/public/el-db-vms"
}

List Orchestrations

This API enables you to retrieve details about orchestrations in a specific container. The GET method can be used to validate the results of the POST, PUT, and DELETE operations.

Method

GET

REST Resource

/orchestration/container/

URI

https://api_endpoint/orchestration/container?status=statusValue

URI Parameter

Parameter

Description

container

Hierarchical namespace for orchestrations

status=statusValue

(Optional) Current status of the orchestration. The following status options are supported:

- ready

- scheduled

- warning

- error

- starting

- stopping

- updating

- shut_down

- shutting_down

- restarting

If this parameter is specified, then the list orchestration output is filtered for the given status.

Example URI

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

Example Response Body

{
"result":
[
{
"relationships": [],
"status": "ready",
"account": "/mytenant/default",
"description": "",
"schedule": {"start_time": "2015-10-23T09:58:52Z", "stop_time": null},
"uri": "https://api/orchestration/mytenant/public/mytenantdb",
"oplans":     [{ .....}]
"status_timestamp": "2015-10-23T10:01:02Z"}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-10-23T10:01:02Z",
"name": "/mytenant/public/db"
}

{
"relationships": [],
"status": "ready",
"account": "/mytenant/default",
"description": "",
"schedule": {"start_time": "2015-10-24T00:43:10Z", "stop_time": null},
"uri": "https://api/orchestration/mytenant/public/mytenantgrill", "oplans": [{.....}],
"status_timestamp": "2015-10-24T00:46:31Z"}],
"info": {"errors": {}, "warnings": {}},
"status_timestamp": "2015-10-24T00:46:31Z",
"name": "/mytenant/public/mytenantgrill"
}
]

Viewing Shapes

Shapes define the compute resources for an instance. You can view the shapes that are available to your tenant. Contact your Oracle Cloud Administrator if you need a shape with a different configuration.

Topics:

- Discover Shapes

- Get Shape

- List Shapes

Discover Shapes

This API enables you to determine what shapes you have access to 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

/shape/container

URI

https://api_endpoint/shape/container

URI Parameter

Parameter

Description

container

(Optional) Hierarchical namespace for shapes

Example URI

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

Example Response Body

{"result": [
"/large",
"/oc1",
"/oc1m",
"/oc2m",
"/oc3",
"/oc3m",
"/oc4",
"/oc4m",
"/oc5",
"/oc5m",
"/oc6",
"/oc7",
"/ot1",
"/small"]
}

Get Shape

This API enables you to retrieve information for a specific shape.

Method

GET

REST Resource

/shape/name

URI

https://api_endpoint/shape/name

URI Parameter

Parameter

Description

name

Name of the shape

Example URI

https://api.oc.example.com/shape/oc3

Example Response Body

{
"ram": 7680,
"cpus": 2.0,
"uri": "https://api.oc.example.com/shape/oc3",
"name": "oc3"
}

List Shapes

This API enables you to list information about shapes.

Method

GET

REST Resource

/shape/

URI

https://api_endpoint/shape/

Example URI

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

Example Response Body

{
"result": [
{
"ram": 7680,
"cpus": 2.0,
"uri": "https://api.oc.example.com/shape/oc3",
"name": "oc3"
},
{
"ram": 15360,
"cpus": 4.0,
"uri": "https://api.oc.example.com/shape/oc4",
"name": "oc4"
},
{
"ram": 30720,
"cpus": 8.0,
"uri": "https://api.oc.example.com/shape/oc5",
"name": "oc5"
}
]
}

Connecting to an Instance VNC Console

To gain access to a virtual machine's (VM) Virtual Network Computing (VNC) console, a SSH tunnel from the local machine through the API endpoint to the node hosting the VM has to be created. Once the SSH tunnel is created, a VNC client is then launched on the local machine and connects to a specific local port. Each VM's SSH connection has a specific user, port and SSH keys.
There are two methods of creating the SSH tunnel—downloading the VNC key information and manually setting up SSH port forwarding, or downloading a JNLP file that creates the SSH connection and starts a VNC client.

Topics:

- Get Instance VNC Key

- Get JNLP file to Access VNC

Get Instance VNC Key

This API enables you to get information for accessing the VNC for the instance, such as VNC/SSH IP address, SSH port, VNC port, SSH user, and SSH private key. This information is used to create an SSH tunnel, which enables a local VNC client to connect to the VM's console.

Method

GET

REST Resource

/instancevnckey/name

URI

https://api_endpoint/instancevnckey/name

URI Parameter

Parameter

Description

name

Name of the instance.

Example URI

https://api.oc.example.com/instancevnckey/mytenant/public/f83ba187-2412-46f7-be6c-3a42ae0bcc9a

Example Response Body

{

"vncip": "api.oc.example.com",
"vnckey": "-----BEGIN RSA PRIVATE KEY-----\jdlw3uhn...../Sj5BGY\n-----END RSA PRIVATE KEY-----",
"vnc_user": "84affefab5e244f28634a900c439c227",
"vncport": 5901,
"uri": "https://api/instancevnckey/mytenant/public/jaas/DocInstance/wls/vm-1/84affefa-b5e2-44f2-8634-a900c439c227",
"name": "/mytenant/public/jaas/DocInstance/wls/vm-1/84affefa-b5e2-44f2-8634-a900c439c227",
"vnc_sshd_port": 62301

}

From the response body JSON data, save the value of attribute vnckey to an SSH key file. Use this file as the key (identity) file when executing the SSH command to enable the local VNC client to connect to the VM’s console. Example:

$ ssh -L8888:localhost:5901 84affefab5e244f28634a900c439c227@api.oc.example.com -p 62301 -i keyfile

Get JNLP file to Access VNC

This API enables you to download the Java Network Launching Protocol (JNLP) file, also known as Java Web Start (JWS), from the node hosting the instance. You can use this JNLP file to access VNC.

Note:
If the VNC client jar is missing error message is displayed, contact your Oracle Cloud Administrator to upload the required JAR files for VNC access.

Note:
If the Application Blocked by Java Security error message is displayed, you must add the displayed address to the Exception Site List. For more information on editing the Exception Site List, see the following link:https://www.java.com/en/download/faq/exception_sitelist.xml

Method

GET

The Accept header in the API Request must be set to the value application/x-java-jnlp-file.

The Content-Type of the returned data (JNLP file) in the response body is set to application/x-java-jnlp-file

REST Resource

/instancevnc/instance_id

URI

https://api_endpoint/instancevnc/instance_id

URI Parameter

Parameter

Description

instance_id

Instance identifier for which the JNLP file will be downloaded

Example URI

https://api.oc.example.com/instancevnc/mytenant/public/d5baeacd-e97d-4933-b170-fcfad113bf1e

Sample Output

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="https://192.168.128.5:443">
<information>
<title>Oracle Compute VNC</title>
<vendor>Oracle America</vendor>
<offline-allowed/>
</information>
..............
..............
-----END RSA PRIVATE KEY-----</argument>
</application-desc>
</jnlp>

7 Template Management

Template management consists of managing three Oracle Compute objects: the machine image (machineimage), the image list (imagelist), and the image list entry (imagelistentry).

A machine image object is a copy of a virtual hard disk with an installed operating system that is used to launch a virtual machine (VM). An image list object is an ordered sequence of machine image objects, one of which may be selected as the default version. This allows users to continue using the same imagelist while upgrades are made to the latest version (that is, users can boot a different machine image if the imagelist gets a new default version). The image list entries are used to add and remove machine images from an image list.

Topics:

- Managing Machine Images

- Managing Image Lists

- Managing Image List Entries

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

- Delete Machine Image

- Retrieve Machine Image Details

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:

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

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

- Get Machine Image

- List Machine Images

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
}
]
}

Managing Image Lists

Machine images must be added to an image list to create a versioned instance template. When defining the launch plan for an orchestration to create an instance, an image list must be selected. You may also optionally select the version of the member machine image for launch. If no version is selected, then the default entry defined for the image list is launched. For example, you might want to set up an image list containing a selection of machine images of various Oracle Linux releases.

Topics:

- Add Image List

- Delete Image List

- Update Image List

- Retrieve Image List Details

Add Image List

This API enables you to add an image list.

Note:
You can add only private image lists to the system. To add public image lists, contact your Oracle Cloud Administrator.

Method

POST

REST Resource

/imagelist/

URI

https://api_endpoint/imagelist/

Request Body Parameters

Parameter

Description

name

A unique hierarchical name for the image list. For example, /mytenant/public/myimagelist .
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

description

A description of this image list

default

(Optional) This is the version of the image in the list that should be considered the default. The default is used on instance launch if a specific version has not been given.

Example URI

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

Example Request Body

{
"default": 1,
"description": "ol 6",
"name": "/mytenant/public/ol6"
}

Example Response Body

{
"default": 1,
"description": "ol 6",
"entries": [],
"uri": "https://api.oc.example.com/imagelist/mytenant/public/ol6",
"name": "/mytenant/public/ol6"
}

Delete Image List

This API enables you to delete a specific image list.

Note:
You can only delete private image lists in your tenancy.

Method

DELETE

REST Resource

/imagelist/name

URI

https://api_endpoint/imagelist/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the image list. For example, /mytenant/public/myimagelist.

Example URI

https://api.oc.example.com/imagelist/mytenant/public/oel59_20GB

Update Image List

This API enables you to update image list information.

Note:
You can update only private image lists that you have created.

Method

PUT

REST Resource

/imagelist/name

URI

https://api_endpoint/imagelist/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the image list. For example, /mytenant/public/myimagelist

Request Body Parameters

Parameter

Description

description

(Optional) A description of this image list.

default

(Optional) This is the version of the image in the list that should be considered the default. The default is used on instance launch if a specific version has not been given.

Example URI

https://api.oc.example.com/imagelist/mytenant/public/ol66_40GB

Example Request Body

{
"default": 2,
"description": "OL 6.6 40 GB",
"uri": "imagelist/mytenant/public/ol66_40GB",
"name": "/mytenant/public/ol66_40GB"
}

Example Response Body

{
"default": 2,
"description": "OL 6.6 40 GB",
"entries": [],
"uri": "https://api.oc.example.com/imagelist/mytenant/public/ol66_40GB",
"name": "/mytenant/public/ol66_40GB"
}

Retrieve Image List Details

You can retrieve image list details by using the REST API.

Topics:

- Discover Image Lists

- Get Image List

- List Image Lists

Discover Image Lists

This API enables you to discover image list names 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

/imagelist/container/

URI

https://api_endpoint/imagelist/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for image list.

Example URI

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

Example Response Body

{"result": ["/mytenant/public/oel59_20G", "/mytenant/public/ol66_40GB"]}

Get Image List

This API enables you to retrieve details of a specific image list.

Method

GET

REST Resource

/imagelist/name

URI

https://api_endpoint/imagelist/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the image list. For example, /mytenant/public/myimagelist

Example URI

http://api/imagelist/oracle/public/linux5_16.1.2_64

Example Response Body

{
"default": 1,
"description": "A default public image.",
"entries": [{"attributes": {},
"version": 1, "machineimages": ["/oracle/public/linux5_16.1.2_64"],
"uri": "https://api/imagelist/oracle/public/linux5_16.1.2_64/entry/1"}],
"uri": "https://api/imagelist/oracle/public/linux5_16.1.2_64",
"name": "/oracle/public/linux5_16.1.2_64"
}

List Image Lists

This API enables you to retrieve information of all image lists present in a specific container.

Method

GET

REST Resource

/imagelist/container/

URI

https://api_endpoint/imagelist/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for image list.

Example URI

https://api.oc.example.com/imagelist/oracle/public/

Example Response Body

{
{
"default": 1,
"description": "A default public image.",
"entries": [{"attributes": {}, "version": 1, "machineimages": ["/oracle/public/linux6_16.1.2_64"],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64/entry/1"}],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64",
"name": "/oracle/public/linux6_16.1.2_64"
},
{
"default": 1,
"description": "A default public image.",
"entries": [{"attributes": {}, "version": 1, "machineimages": ["/oracle/public/linux5_16.1.2_64"],
"uri": "https://api/imagelist/oracle/public/linux5_16.1.2_64/entry/1"}],
"uri": "https://api/imagelist/oracle/public/linux5_16.1.2_64",
"name": "/oracle/public/linux5_16.1.2_64"
}}

Managing Image List Entries

An image list entry connects machine images to image lists. This section specifies the operations associated with managing image list entries.

Topics:

- Add Image List Entry

- Delete Image List Entry

- Retrieve Image List Entry Details

Add Image List Entry

This API enables you to add an image list entry.

Note:
You can add only private machine image list entries to the system. To add public image list, contact your Oracle Cloud Administrator.

Method

POST

REST Resource

/imagelist/name/entry/

URI

https://api_endpoint/imagelist/name/entry/

URI Parameter

Parameter

Description

name

A unique hierarchical name for the image list entry. For example, /mytenant/public/myimagelistentry
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

Request Body Parameters

Parameter

Description

machineimages

List of machine images to be used for this image list

version

The version of the machine image in the specified image list

attributes

(Optional) Specified as a JSON object, these are user-defined parameters that can be passed to an instance of this machine image when it is launched.
For more information on attributes, see Orchestration Templates in Using Oracle Compute Cloud Service .

Example URI

https://api.oc.example.com/imagelist/mytenant/public/ol/entry/

Example Request Body

{
"attributes": {"type": "Oracle Linux 6.6"},
"version": 2,
"machineimages": ["/mytenant/public/ol66_40GB"],
}

Example Response Body

{
"list": [
{
"attributes": {"type": "Oracle Linux 6.6"},
"imagelist": {
"default": 1,
"description": null,
"entries": null,
"uri": "imagelist/mytenant/public/ol66_40GB",
"name": "/mytenant/public/ol66_40GB"
},
"version": 2,
"machineimages": ["/mytenant/public/ol66_40GB"],
"uri": "https://api.oc.example.com/imagelist/mytenant/public/ol66_40GB/entry/2"
}
]
}

Delete Image List Entry

This API enables you to delete an image list entry.

Note:
You can delete only those image list entries created in your tenancy.

Method

DELETE

REST Resource

/imagelist/name/entry/version

URI

https://api_endpoint/imagelist/name/entry/version

URI Parameters

Parameter

Description

name

A unique hierarchical name for the image list entry. For example, /mytenant/public/myimagelistentry

version

The version of the machine image in the specified image list.

Example URI

https://api.oc.example.com/imagelist/mytenant/public/ol66_40GB/entry/1

Retrieve Image List Entry Details

You can retrieve details of image list entry by using the REST API.

Topics:

- Get Image List Entry

- List Image List Entries

Get Image List Entry

This API enables you to retrieve information for a specific image list entry.

Method

GET

REST Resource

/imagelist/name

URI

https://api_endpoint/imagelist/name?version=versionValue

URI Parameters

Parameter

Description

name

A unique hierarchical name for the image list entry. For example, /mytenant/public/my-imagelist-1

version=versionValue

(Optional) The version of the machine image in the image list.

Example URI

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

Example Response Body

{
"default": 1,
"description": "A default public image.",
"entries": [
{
"attributes": {},
"version": 1,
"machineimages": ["/oracle/public/linux6_16.1.2_64"],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64/entry/1"
}
],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64 ",
"name": "/oracle/public/linux6_16.1.2_64"
}

List Image List Entries

This API enables you to list details of image list entries.

Method

GET

REST Resource

/imagelist/name

URI

https://api_endpoint/imagelist/name

URI Parameter

Parameter

Description

name

Unique hierarchical name for the image list entry. For example, /mytenant/public/myimagelistentry

Example URI

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

Example Response Body

{
default": 1,
"description": "A default public image.",
"entries":
[{
"attributes": {},
"version": 1,
"machineimages": ["/oracle/public/linux6_16.1.2_64"],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64/entry/1"
}],
"uri": "https://api/imagelist/oracle/public/linux6_16.1.2_64",
"name": "/oracle/public/linux6_16.1.2_64"
}

8 Site Information

You may want to access site information in order to report any site related problem/issue to the cloud administrator. The following site wide information is available to all users.

Topics:

- Accessing Site Information

Accessing Site Information

This section specifies the operation that you can use to retrieve information about the installed site. Some of this information may be required for licensing and support requests. The fingerprint of the site is usually required for licensing, and provides a unique identifier for the installed site.

Topics:

- Get Site Information

Get Site Information

This API enables you to retrieve information for an installed site.

Method

GET

REST Resource

/info/

URI

https://api_endpoint/info/

Example URI

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

Example Response Body

{
"result":
[{
"fingerprint": "BB:40:6A:1B:77:E2:A5:65:7E:B6:C7:4B:BB:ED:42:98:63:A3:D6:0C",
"idpname": "test",
"uri": "https://api.oc.example.com/info/",
"version": "14.1.14-20150120.095609-master",
"name": "test"
}]
}

9 Storage Management

Oracle Compute Cloud Service assigns a block of storage to an instance. The block of storage is a chunk of disk space on virtual disks. Oracle Compute manages virtual disks independently of the instances that use them. When an instance terminates, another instance can replace it and use the virtual disk space allocated to it. This section specifies the operations that can be performed to manage storage components.

Topics:

- Managing Storage Volumes

- Managing Storage Attachments

- Viewing Storage Properties

Managing Storage Volumes

Storage volumes are pieces of storage of specific size created in the storage pool. You can attach them to an instance, either in an orchestration or after the instance has been launched.

Topics:

- Add Storage Volume

- Delete Storage Volume

- Update Storage Volume

- Retrieve Storage Volume Details

Add Storage Volume

This API enables you to add a storage volume.

Method

POST

Note:
You can add only private volumes within your tenancy.

REST Resource

/storage/volume/

URI

https://api_endpoint/storage/volume/

Request Body Parameters

Parameter

Description

name

Name of this storage volume.
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

size

The size of this storage volume measured in the number of bytes or multiples of bytes. The allowed range is from 1 GB to 2 TB, in increments of 1 GB.
Use one of the following abbreviations as the unit of measurement:

- B or b (bytes)

- K or k (kilobytes)

- M or m (megabytes)

- G or g (gigabytes)

- T or t (terabytes).

For example, to create a volume of size 10 gigabytes, you can specify 10G, or 10240M, or 10485760K, and so on.

properties

A list of the storage properties that are associated with this storage volume.
The following storage properties are supported:

- /oracle/public/storage/default—Default storage property for internal storage appliance.

- /oracle/public/storage/latency—Storage property for placing volumes on external storage appliance.

- /oracle/public/storage/throughput—Storage property for placing volumes on external storage appliance.

For information on setting up storage volumes on external storage appliances, see section Managing Storage Volumes in Using Oracle Compute Cloud Service.

description

(Optional) Description of the storage volume

source_storagevolume_name

(Optional) Name of the existing storage volume, from where the data will be copied when this volume is created

imagelist

(Optional) Name of the image list to use as source for this storage volume when created. This option must be paired with imagelist_entry in order to reference a specific machine image.

imagelist_entry

(Optional) Specific the image list entry version to extract

tags

(Optional) A list of user-friendly strings which will tag the storage volume. Tags should be specified in the following syntax: "tags": ["tag1", "tag2"]

quota

(Optional) The quota against which this volume will be created.  If the quota is not specified, then the default quota of the tenancy (to which the user belongs) is used.

Example URI

https://api.oc.example.com/storage/volume/

Example Request Body

{
"size": "10G",
"properties": [
"/oracle/public/storage/default"
],
"name": "/mytenant/public/vol1"
}

Example Response Body

{
"status": "Initializing",
"account": "/mytenant/default",
"writecache": false,
"managed": true,
"description": null,
"tags": [],
"bootable": false,
"hypervisor": null,
"quota": null,
"uri": "https://api.oc.example.com/storage/volume/mytenant/public/vol1",
"status_detail": "The storage volume is currently being initialized.",
"imagelist_entry": -1,
"storage_pool": "/mytenant/public/mypool",
"machineimage_name": null,
"status_timestamp": "2015-06-01T11:15:57Z",
"shared": false,
"imagelist": null,
"size": "10737418240",
"properties": ["/oracle/public/storage/default"],
"name": "/mytenant/public/vol1"
}

Delete Storage Volume

This API enables you to delete a specific storage volume.

Method

DELETE

Note:
You can delete only private volumes within your tenancy.

REST Resource

/storage/volume/name

URI

https://api_endpoint/storage/volume/name

URI Parameter

Parameter

Description

name

Name of the storage volume

Example URI

https://api.oc.example.com/storage/volume/mytenant/public/vol1

Update Storage Volume

This API enables you to update a specific storage volume.

Method

PUT

REST Resource

/storage/volume/name

URI

https://api_endpoint/storage/volume/name

URI Parameter

Parameter

Description

name

Name of this storage volume

Request Body Parameter

Parameter

Description

description

(Optional) Description of this storage volume

tags

(Optional) A list of user-friendly strings that will tag the storage volume. During an update, the list of tags specified becomes the new list. To preserve existing tags, the existing set must first be retrieved and any changes should be made to that list, and then that list must be specified for the update.

Example URI

https://api.oc.example.com/storage/volume/mytenant/public/vol1

Example Request Body

{
"description": "Updated Storage Volume",
"tags": ["Accounting Department Block Storage"],
}

Example Response Body

{
"status": "Online",
"account": "/mytenant/default",
"writecache": false,
"managed": true,
"description": "Updated Storage Volume",
"tags": ["Accounting Department Block Storage"],
"bootable": false,
"hypervisor": null,
"quota": null,
"uri": "https://api.oc.example.com/storage/volume/mytenant/public/vol1",
"status_detail": "The storage volume is online.",
"imagelist_entry": -1,
"storage_pool": "/mytenant/public/mypool",
"machineimage_name": null,
"status_timestamp": "2015-06-01T11:16:04Z",
"shared": false,
"imagelist": null,
"size": "10737418240",
"properties": ["/oracle/public/storage/default"],
"name": "/mytenant/public/vol1"
}

Retrieve Storage Volume Details

You can retrieve storage volume details by using the REST API.

Topics:

- Discover Storage Volumes

- Get Storage Volume

- List Storage Volumes

Discover Storage Volumes

This API enables you to discover storage volumes 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

/storage/volume/container

URI

https://api_endpoint/storage/volume/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for storage volume.

Example URI

https://api.oc.example.com/storage/volume/mytenant/public/

Example Response Body

{
"result": [
"/mytenant/public/vol1"
]
}

Get Storage Volume

This API enables you to retrieve information for a specific storage volume.

Method

GET

REST Resource

/storage/volume/name

URI

https://api_endpoint/storage/volume/name

URI Parameter

Parameter

Description

name

Name of the storage volume

Example URI

https://api.oc.example.com/storage/volume/mytenant/public/vol1

Example Response Body

{
"status": "Online",
"account": "/mytenant/default",
"writecache": false,
"managed": true,
"description": null,
"tags": [],
"bootable": false,
"hypervisor": null,
"quota": null,
"uri": "https://api.oc.example.com/storage/volume/mytenant/public/vol1",
"status_detail": "The storage volume is online.",
"imagelist_entry": -1,
"storage_pool": "/mytenant/public/mypool",
"machineimage_name": null,
"status_timestamp": "2015-06-01T11:16:04Z",
"shared": false,
"imagelist": null,
"size": "10737418240",
"properties": ["/oracle/public/storage/default"],
"name": "/mytenant/public/vol1"
}

List Storage Volumes

This API enables you to list storage volumes.

Method

GET

REST Resource

/storage/volume/container

URI

https://api_endpoint/storage/volume/container?tags=tagsValue&quota=quotaValue&name=nameValue

URI Parameter

Note:
The output of this command is filtered based on the optional parameters (if specified).

Parameter

Description

container

Hierarchical namespace for the storage volume

tags=tagsValue

(Optional) A list of user-friendly strings which tag the storage volume

quota=quotaValue

(Optional) The quota against which this volume is created

name=nameValue

(Optional) Name of storage volume

Example URI

https://api.oc.example.com/storage/volume/mytenant/public/

Example Response Body

{"result": [
{
"status": "Online",
"account": "/mytenant/default",
"writecache": false,
"managed": true,
"description": null,
"tags": [],
"bootable": false,
"hypervisor": null,
"quota": null,
"uri": "https://api.oc.example.com/storage/volume/mytenant/public/vol1",
"status_detail": "The storage volume is online.",
"imagelist_entry": -1,
"storage_pool": "/mytenant/public/mypool",
"machineimage_name": null,
"status_timestamp": "2015-06-01T11:16:04Z",
"shared": false,
"imagelist": null,
"size": "10737418240",
"properties": ["/oracle/public/storage/default"],
"name": "/mytenant/public/vol1"
}
]
}

Managing Storage Attachments

A storage attachment is an association between a storage volume and an instance. You can attach a storage volume to an instance either at launch time (by using a launch plan in an orchestration) or after an instance is running (by using UI, CLI and API). Each volume may only be attached to one instance at a time. To detach a storage volume from an instance, delete the associated storage attachment object.

Note:
The storage attachment must exist within the tenant name-space of the instance owner.

Topics:

- Add Storage Attachment

- Delete Storage Attachment

- Retrieve Storage Attachment Details

Add Storage Attachment

This API enables you to add a storage attachment.

Method

POST

REST Resource

/storage/attachment/

URI

https://api_endpoint/storage/attachment/

Request Body Parameters

Parameter

Description

index

Index number for the volume. The allowed range is 1 to 10. The index determines the device name by which this volume is exposed to the instance (for example, /dev/sdal1). The index to device mapping is as follows:

- 1—/dev/xvdb

- 2—/dev/xvdc, and so on

instance_name

Name of the instance to which the volume should be attached

storage_volume_name

Name of the storage volume to which the instance should be attached

Example URI

https://api.oc.example.com/storage/attachment/

Example Request Body

{
"instance_name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
"storage_volume_name": "/mytenant/public/example-sdi-sdivm-el1-6-storagevolume-data",
"index": 3
}

Example Response Body

{
"index": 3,
"account": null,
"storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data",
"hypervisor": null,
"uri": "https://api.oc.example.com/storage/attachment/mytenant/public/example-sdi-sdivm-el1-8-instance/\
1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64",
"instance_name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
"state": "shut_down",
"readonly": false,
"name": "/mytenant/public/example-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
}

Delete Storage Attachment

This API enables you to delete a specific storage attachment.

If the instance is in the running state, then you must first unmount the storage volume in the instance. Log in to the instance, identify the storage volume, and unmount the storage volume using the command umount path-to-disk-mount-point.

Method

DELETE

REST Resource

/storage/attachment/name

URI

https://api_endpoint/storage/attachment/name

URI Parameter

Parameter

Description

name

System generated name of the storage attachment to be deleted.

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f6

Retrieve Storage Attachment Details

You can retrieve storage attachment details by using the REST API.

Topics:

- Discover Storage Attachments

- Get Storage Attachment

- List Storage Attachments

Discover Storage Attachments

This API enables you to discover storage attachments 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

/storage/attachment/container/

URI

https://api_endpoint/storage/attachment/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace containing the storage attachments

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public

Example Response Body

{"/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/"},

Get Storage Attachment

This API enables you to retrieve information for a specific storage attachment.

Method

GET

REST Resource

/storage/attachment/name

URI

https://api_endpoint/storage/attachment/name

URI Parameter

Parameter

Description

name

System generated name of the storage attachment

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64

Example Response Body

{
"index": 3,
"account": null,
"storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data",
"hypervisor": null,
"uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64",
"instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
"state": "shut_down",
"readonly": false,
"name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
}

List Storage Attachments

This API enables you to retrieve details of storage attachments in a specific container.

Method

GET

REST Resource

/storage/attachment/container/

URI

https://api_endpoint/storage/attachment/container?name=nameValue&instance_name=instance_nameValue&storage_volume_name=storage_volume_name&state=stateValue

URI Parameter

Parameter

Description

container

Hierarchical namespace containing the storage attachments

name

(Optional) Name of the attachment, automatically generated by the server

instance_name

(Optional) Name of the instance to which the volume is attached

storage_volume_name

(Optional) Name of the storage volume to which the instance is attached

state

(Optional) Attachment state. The following values are supported:

- attaching
The storage attachment is in the process of attaching to the instance.

- attached
The storage attachment is attached to the instance.

- detaching
The storage attachment is in the process of detaching to the instance.

- unavailable
The storage attachment is unavailable.

- error
The storage attachment is in error state.

Example URI

https://api.oc.example.com/storage/attachment/mytenant/public

Example Response Body

{
"index": 3,
"account": null,
"storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-6-storagevolume-data",
"hypervisor": null, "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64",
"instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
"state": "shut_down",
"readonly": false,
"name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8a6551a2-af25-4616-98e8-50db17da8f64"
},

{
"index": 1,
"account": null,
"storage_volume_name": "/mytenant/public/scae09-sdi-sdivm-el1-5-storagevolume-ops",
"hypervisor": null, "uri": "https://api.oc.example.com/storage/attachment/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8d772e9e-182f-4df8-a9d9-ce58ebe68442",
"instance_name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc",
"state": "shut_down",
"readonly": false,
"name": "/mytenant/public/scae09-sdi-sdivm-el1-8-instance/1a9ce3a1-ddba-44f7-9cc5-04c77f6523bc/8d772e9e-182f-4df8-a9d9-ce58ebe68442"
}

Viewing Storage Properties

Storage properties are used to describe the characteristics of storage pools and determine the volume placement within a pool when a volume is created.

Topics:

- Discover Property Storage

- Get Property Storage

- List Property Storage

Discover Property Storage

This API enables you to discover storage property objects 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

/property/storage/container

URI

https://api_endpoint/property/storage/container

URI Parameter

Parameter

Description

container

Hierarchical namespace containing property objects

Example URI

https://api/property/storage/oracle/public/storage/protocol/

Example Response Body

Data:
{"result": ["/oracle/public/storage/protocol/iscsi", "/oracle/public/storage/protocol/nfs"]}

Get Property Storage

This API enables you to retrieve a specific storage property.

Method

GET

REST Resource

/property/storage/name

URI

https://api_endpoint/property/storage/name

URI Parameter

Parameter

Description

name

Name of the storage property

Example URI

https://api/property/storage/oracle/public/storage/protocol/iscsi

Example Response Body

{
"description": "Storage property for protocol: iscsi",
"uri": "https://api/property/storage/oracle/public/storage/protocol/iscsi",
"name": "/oracle/public/storage/protocol/iscsi"
}

List Property Storage

This API enables you to retrieve a list of storage properties in a specific container.

Method

GET

REST Resource

/property/storage/container

URI

https://api_endpoint/property/storage/container

URI Parameter

Parameter

Description

container

Hierarchical name-space containing property objects.

Example URI

https://api/property/storage/oracle/public/storage/

Example Response Body

{"result":
[
{
"description": "Default storageproperty for all StoragePools and StorageVolumes",
"uri": "https://api/property/storage/oracle/public/storage/default",
"name": "/oracle/public/storage/default"
},
{
"description": "Storage property for protocol: iscsi",
"uri": "https://api/property/storage/oracle/public/storage/protocol/iscsi",
"name": "/oracle/public/storage/protocol/iscsi"
},
{
"description": "Storage property for protocol: nfs",
"uri": "https://api/property/storage/oracle/public/storage/protocol/nfs",
"name": "/oracle/public/storage/protocol/nfs"
}
]
}

10 Network Management

The Oracle Public Cloud Machine includes compute nodes, a storage appliance, switches, and other components that require connectivity to your network. The network connections allow clients and administrators to use the compute resources remotely, by accessing the IaaS, and PaaS user interfaces and APIs, as well as virtual machines running on compute nodes.
The following three types of networks are supported:

- Infrastructure service networks: Infrastructure service networks are service networks that are created during the installation process while configuring the Oracle Public Cloud Machine. This network type is managed by Oracle Cloud Administrator. Oracle Cloud Administrator can provide access to specific tenants, like for ZFSSA or OMS access.

- Service networks: Service networks provide shared services across multiple tenants. The shared services include access to storage, networks, and other engineered systems. The service networks are further classified as public networks (EoIB) and private networks (IPoIB). This network type is created and shared by Oracle Cloud Administrators, and used by tenant administrators and tenant users.

- Tenant networks: Networks that are assigned exclusively for a specific tenant. Only the instances in that tenant can use this network. The tenant networks are further classified as public networks (EoIB) and private (IPoIB) networks.
EoIB networks are created by Oracle Cloud Administrators, and used by tenant administrators and tenant users. IPoIB networks are fully managed by tenant administrators and tenant users.

Topics:

- Viewing Service Networks

- Managing vEthernet

- Managing vNET

- Viewing vNET Access

- Managing vNET Reservations

- Viewing vCables

Viewing Service Networks

Service networks (servicenets) are created in the system to provide shared services across multiple tenants. The shared services include access to storage, networks, and other engineered systems. An example of an external service provider is an Oracle ZFS storage appliance that provides storage shared across tenants. A dedicated InfiniBand partition is allocated for a servicenet, and no two servicenets share the partition.

The networks can be of type EoIB or IPoIB. The Oracle Cloud Administrator creates and manages these servicenets. In order to view a service network, a tenant must be granted access to the servicenet's underlying vNet by the Oracle Cloud Administrator. This is done with the use of vNet access.

- IPoIB Service Networks: The IPoIB servicenet is used for communication between service consumers and service providers. The servicenet is constructed over InfiniBand inside the system, between engineered Systems, or external ZFS appliance interconnected using InfiniBand.

- EoIB Service Networks: The EoIB servicenet is used for communication with a service provider or service consumer located outside the system over Ethernet through NM2 Gateways.

Topics:

- Discover Service Networks

- Get Service Network

- List Service Networks

Discover Service Networks

This API enables you to discover a list of service networks defined within a 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

/svcnet/container/

URI

https://api_endpoint/svcnet/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for service networks.

Example URI

https://api.oc.example.com/svcnet/cloud/public/

Example Response Body

{
"result": [
"/cloud/public/EoIB-OMS",
"/cloud/public/EoIB-management",
"/cloud/public/IPoIB-default",
"/cloud/public/IPoIB-instance-storage",
"/cloud/public/IPoIB-ldap-internal",
"/cloud/public/IPoIB-load-balancer",
"/cloud/public/IPoIB-management",
"/cloud/public/IPoIB-storage",
"/cloud/public/servicenet1",
"/cloud/public/svcnet-ipoib"
]
}

Get Service Network

This API enables you to retrieve information for a specific service network.

Method

GET

REST Resource

/svcnet/name

URI

https://api_endpoint/svcnet/name

URI Parameter

Parameter

Description

name

Name of the service network. For example /oracle/public/mysvcnet

Example URI

https://api.oc.example.com/svcnet/cloud/public/IPoIB-default

Example Response Body

{
"pkey": "0x7fff",
"infranet": true,
"description": "Infrastructure service network: cloud/public/IPoIB-default",
"uri": "https://api.oc.example.com/svcnet/cloud/public/IPoIB-default",
"foreign_partition": true,
"num_provider_nodes": 0,
"type": "ipoib",
"ibrt_name": "0x7fff",
"name": "/cloud/public/IPoIB-default"
}

List Service Networks

This API enables you to retrieve information for all the service networks within a specific container.

Method

GET

REST Resource

/svcnet/container/

URI

https://api_endpoint/svcnet/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for service networks

Example URI

https://api.oc.example.com/svcnet/oracle/public/

Example Response Body

{
"result":
[{
"pkey": "0x1402",
"infranet": true,
"description": "Infrastructure service network: oracle/public/IPoIB-virt-admin",
"uri": "https://api.oc.example.com/svcnet/oracle/public/IPoIB-virt-admin",
"foreign_partition": false,
"num_provider_nodes": 1,
"type": "ipoib",
"ibrt_name": "IPoIB-virt-admin-c2",
"name": "/oracle/public/IPoIB-virt-admin"
}]
}

Managing vEthernet

A virtual Ethernet (vEthernet) is an IaaS object representing an OSI Layer 2 network, defined by a VLAN ID, switch pair name and e-port. vEthernets serve the purpose to isolate networks for instances run by different departments or business units (tenants).

Topics:

- Add vEthernet

- Delete vEthernet

- Update vEthernet

- Retrieve vEthernet Details

Add vEthernet

This API enables you to add a virtual Ethernet to the network.

Note:
You can only add IPoIB vEthernets.

Method

POST

REST Resource

/vethernet/

URI

https://api_endpoint/vethernet/

Request Body Parameters

Parameter

Description

name

An unique hierarchical name for Ethernet. For example, /mytenant/public/EoIB

description

A description for a vEthernet

type

Type of vEthernet (supported types: ipoib).

id

Unique identifier for this vEthernet (vLAN ID for eoib/vlan type). Set this parameter to 0 for vEthernet type ipoib.

svcnet

(Optional) Service network to use for this vEthernet

Example URI

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

Example Request Body

{
"description": "mytenant public net",
"name": "/mytenant/public/IPoIB",
"type": "ipoib",
"id": 0
}

Delete vEthernet

This API enables you to delete virtual Ethernet

Note:
You can only delete IPoIB vEthernets.

Method

DELETE

REST Resource

/vethernet/name

URI

https://api_endpoint/vethernet/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the vEthernet. For example, /mytenant/public/myvethernet

Example URI

https://api.oc.example.com/vethernet/mytenant/public/myvethernet

Update vEthernet

This API enables you to update information for a specific virtual Ethernet.

Note:
You can only update IPoIB vEthernets.

Method

PUT

REST Resource

/vethernet/name

URI

https://api_endpoint/vethernet/name

URI Parameter

Parameter

Description

name

Unique hierarchical name for the vEthernet. For example, /cloud/public/myvEthernet.

Request Body Parameter

Parameter

Description

description

(Optional)A description for a vEthernet

type

Type of vEthernet (supported types: ipoib).

id

(Optional)Unique identifier for this vEthernet (vLAN ID for eoib/vlan type). This field is ignored for type ipoib

Example URI

https://api.oc.example.com/vethernet/mytenant/public/IPoIB2

Example Request Body

{
"description": "Updated Desc for IPoIB vethernet for mytenant",
"name": "/mytenant/public/IPoIB2",
"type": "ipoib",
"id": 0
}

Example Response Body

{
"account": "/mytenant/default",
"infranet": false,
"description": "Updated Desc for IPoIB vethernet for mytenant",
"svcnet": null,
"uri": "db://bnet/vethernet/mytenant/public/IPoIB2",
"vDhcpd_name": null,
"name": "/mytenant/public/IPoIB2",
"vEthernet_uri": null,
"type": "ipoib",
"id": 0,
"cluster_uri": null,
"switchports": null
}

Retrieve vEthernet Details

You can retrieve vEthernet details by using the REST API.

Topics:

- Discover vEthernets

- List vEthernets

Discover vEthernets

This API enables you to discover virtual Ethernets configured 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

/vethernet/container/

URI

https://api_endpoint/vethernet/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for vEthernets

Example URI

https://api.oc.example.com/vethernet/oracle/public

Example Response Body

{"result": ["/oracle/public/IPoIB-virt-admin-c2", "/oracle/public/default"]}

List vEthernets

This API enables you to retrieve information for the configured virtual Ethernets in a specific container or subcontainer.

Method

GET

REST Resource

/vethernet/container/

URI

https://api_endpoint/vethernet/container?type=typeValue&id=idValue

URI Parameters

Note:
The output of this command is filtered based on the optional parameters (if specified).

Parameter

Description

container

Hierarchical name-space for virtual Ethernet

type=typeValue

(Optional) Type of vEthernet (supported type: ipoib)

Example URI

https://api.oc.example.com/vethernet/oracle/public/

Example Response Body

{
"account": null,
"infranet": true,
"description":
"Infrastructure vEthernet: oracle/public/IPoIB-virt-admin-c2",
"svcnet": "oracle/public/IPoIB-virt-admin-c2",
"uri": "https://api.oc.example.com/vethernet/oracle/public/IPoIB-virt-admin-c2",
"vDhcpd_name": null,
"name": "/oracle/public/IPoIB-virt-admin-c2",
"vEthernet_uri": null,
"type": "ipoib",
"id": 0,
"cluster_uri": null,
"switchports": {}
},
{
"account": null,
"infranet": false,
"description": "Default vethernet for flat IP space.",
"svcnet": null,
"uri": "https://api.oc.example.com/vethernet/oracle/public/default",
"vDhcpd_name": "",
"name": "/oracle/public/default",
"vEthernet_uri": null,
"type": "vlan",
"id": 0,
"cluster_uri": null,
"switchports": {}
}

Managing vNET

A virtual network (vNET) is deployed in the scope of a service network or tenant network. vNET represents an IP subnet and defines an IP address range. You require a vEthernet to create a vNET.

Topics:

- Add vNET

- Delete vNET

- Update vNet

- Retrieve vNET Details

Add vNET

This API enables you to add a new virtual network for a tenant.

Note:
The tenant users can only add vNETs that are tied to IPoIB vEthernets. However, if EoIB vNET is needed the Oracle Cloud Administrator must create it in the tenancy for the tenant user to use.

Method

POST

REST Resource

/vnet/

URI

https://api_endpoint/vnet/

Request Body Parameters

Parameter

Description

name

An unique hierarchical name for a vNET . For example, /mytenant/public/myvnet
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

vethernet

vEthernet to be associated with this vNET. For tenant user, only IPoIB vEthernet is supported.

cidr

(Optional) Specifies the subnet Classless Inter-Domain Routing (CIDR) for vNET. Optional for IPoIB network.
Format: ip_address/#. For example, 192.0.1.0/24

If cidr is not specified for IPoIB type networks, then global_ip_num parameter must be specified.

ipranges

(Optional) IP address range for the vNET. It is a comma separated list and can have individual IP addresses or ranges using “-“ as a separator. For example, 192.0.1.10, 192.0.1.20-192.0.1.30
If no IP range is provided, the entire CIDR is used for IP addresses, that is from .1 to .254.

description

(Optional) Description to correlate this vNET with internal tenant schema.

global_ip_num

(Optional) Specifies the number of IP addresses to be used from the global IP pool. Not valid for EoIB network.
If the global IP pool is enabled in Oracle Compute, using this option will create a vNET by allocating a specified number of IP addresses from the global pool of IP addresses to guarantee uniqueness. This option is mutually exclusive of cidr and ipranges options.

Example URI

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

Example Request Body

{"global_ip_num": 30, "name": "/mytenant/public/IPoIB-Test", "vethernet": "/mytenant/public/default", "description": "Testing vnet creation"}

Example Response Body

{
"status": {"total": 30, "reserved": 0, "failed_allocations": 0, "used": 0},
"account": "/mytenant/default",
"infranet": false,
"description": "Testing vnet creation",
"uri": "http://api.oc.example.com/vnet/mytenant/public/IPoIB-Test",
"eth_idx": null,
"global_ip_num": 30,
"ipranges": ["192.168.160.1-192.168.160.30"],
"vethernet": "/mytenant/public/default",
"free_ipranges": ["192.168.160.1-192.168.160.30"],
"cidr": "192.168.160.0/27",
"gateway": null,
"name": "/mytenant/public/IPoIB-Test"
}

Delete vNET

This API enables you to delete an existing vNET entity. You cannot delete a vNET if it is used by any instance, or if there is an existing vNET Reservation associated with the vNET.

Method

DELETE

REST Resource

/vnet/name

URI

https://api_endpoint/vnet/name

URI Parameter

Parameter

Description

name

An unique hierarchical name for a vNET. For example, /mytenant/public/myvnet

Example URI

https://api.oc.example.com/vnet/mytenant/public/IPoIB-service-manager

Update vNet

This API enables you to update information for a specific tenant vNET.

Note:
The tenant users can only update vNETs that are tied to IPoIB vEthernets.

Method

PUT

REST Resource

/vnet/name

URI

https://api_endpoint/vnet/name

URI Parameter

Parameter

Description

name

An unique hierarchical name for a vNET . For example, /mytenant/public/myvnet
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

Request Body Parameters

Parameter

Description

vethernet

vEthernet to be associated with this vNET. For tenant user, only IPoIB type vEthernet is supported.

cidr

(Optional) Specifies the subnet Classless Inter-Domain Routing (CIDR) for vNET. Optional for IPoIB type network.
Format: ip_address/#. For example, 192.0.1.0/24

ipranges

(Optional) IP address range for the vNET. It is a comma separated list and can have individual IP addresses or ranges using “-“ as a separator. For example, 192.0.1.10, 192.0.1.20-192.0.1.30
If no IP range is provided, the entire CIDR is used for IP addresses, that is from .1 to .254.

description

(Optional) Description to correlate this vNET with internal tenant schema.

global_ip_num

(Optional) Specifies the number of IP addresses to be used from the global IP pool. Not valid for EoIB type network.
If the global IP pool is enabled in Oracle Compute, using this option will create a vNET by allocating a specified number of IP addresses from the global pool of IP addresses to guarantee uniqueness. This option is mutually exclusive of cidr and ipranges options.

Example URI

http://api.oc.example.com/vnet/mytenant/public/IPoIB-Test

Example Request Body

{
"global_ip_num":62,
"description": "Updated Desc.",
"vethernet": "/mytenant/public/default",
"name": "/mytenant/public/IPoIB-Test"
}

Example Response Body

{
"status": {"total": 62, "reserved": 0, "failed_allocations": 0, "used": 0},
"account": "/mytenant/default",
"infranet": false,
"description": "Updated Desc.",
"uri": "http://api.oc.example.com/vnet/mytenant/public/IPoIB-Test",
"eth_idx": null,
"global_ip_num": 62,
"ipranges": ["192.168.160.65-192.168.160.126"],
"vethernet": "/mytenant/public/default",
"free_ipranges": ["192.168.160.65-192.168.160.126"],
"cidr": "192.168.160.64/26",
"gateway": null,
"name": "/mytenant/public/IPoIB-Test"
}

Retrieve vNET Details

You can retrieve vNET details by using the REST API.

Note:
You can view the details of any vNET in your own tenancy, as well as vNETs you have been given access to by the Oracle Cloud Administrator.

Topics:

- Discover vNET

- Get vNET

- List vNET

Discover vNET

This API enables you to discover a list of configured vNETs in a specific container or subcontainer.

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

/vnet/container/

URI

https://api_endpoint/vnet/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for vNET. For example, /mytenant/public/

Example URI

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

Example Response Body

{
"result":
[
"/mytenant/public/IPoIB-instance-storage-c2",
"/mytenant/public/IPoIB-ldap-internal-c2",
"/mytenant/public/IPoIB-load-balancer-c2",
"/mytenant/public/IPoIB-management-c2",
"/mytenant/public/IPoIB-service-manager-c2"
]
}

Get vNET

This API enables you to retrieve information for a specific vNET.

Method

GET

REST Resource

/vnet/name

URI

https://api_endpoint/vnet/name

URI Parameter

Parameter

Description

name

An unique hierarchical name for a vNET . For example, /mytenant/public/myvnet

Example URI

https://api.oc.example.com/vnetaccess/mytenant/public/IPoIB-OMS-c2

Example Response Body

{
"permissions": {"object": [...]},
"vnet": "/mytenant/public/IPoIB-OMS-c2",
"uri": "https://api.oc.example.com/vnetaccess/mytenant/public/IPoIB-OMS-c2",
"name": "/mytenant/public/IPoIB-OMS-c2",
"provider": false
}

List vNET

This API enables you to retrieve information for all the vNETs in a specific container.

Method

GET

REST Resource

/vnet/container/

URI

https://api_endpoint/vnet/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for vNET. For example, /mytenant/public/myvNET

Example URI

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

Example Response Body

{"result":
[{
"status": {"total": 32766, "reserved": 6, "failed_allocations": 0, "used": 9},
"account": null,
"infranet": true,
"description": "Infrastructure vNet: mytenant/public/IPoIB-virt-admin-c2",
"uri": "https://api.oc.example.com/vnet/mytenant/public/IPoIB-virt-admin-c2",
"eth_idx": null,
"global_ip_num": null,
"ipranges": ["10.0.0.1-10.0.127.254"],
"vethernet": "/mytenant/public/IPoIB-virt-admin-c2",
"cidr": "10.0.0.0/17",
"gateway": null,
"name": "/mytenant/public/IPoIB-virt-admin-c2"
}]
}

Viewing vNET Access

Virtual network access (vNET Access) allows sharing of vNETs between tenants. View the vNET Access objects in your own tenancy to determine what vNETs you have permission to use when configuring virtual machines. Tenant users and administrators can fetch the vNET Access information to determine the vNETs that they can use.

Topics:

- Discover vNET Access

- Get vNET Access

- List vNET Access

Discover vNET Access

This API enables you to discover a list of vNet Access entities configured 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

/vnetaccess/container/

URI

https://api_endpoint/vnetaccess/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for vNET access.

Example URI

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

Example Response Body

Data:
{"result": [
"/mytenant/public/IPoIB-instance-storage-c2",
"/mytenant/public/IPoIB-load-balancer-c2",
"/mytenant/public/IPoIB-management-c2",
"/mytenant/public/IPoIB-service-manager-c2",
"/mytenant/public/IPoIB-virt-admin-c2"
]}

List vNET Access

This API enables you list information for all the vNet Access entities in a container.

Method

GET

REST Resource

/vnetaccess/container/

URI

https://api_endpoint/vnetaccess/container?vnet=vnetValue

URI Parameters

Parameter

Description

container

Hierarchical name-space for vNET Access

vnet=vnetValue

(Optional) Name of the associated virtual network

Example URI

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

Example Response Body

{
"result":
[{
"permissions": {"object": ["...."]},
"vnet": "/cloud/public/EoIB-OMS",
"uri": "https://api.oc.example.com/vnetaccess/mytenant/public/EoIB-OMS",
"name": "/mytenant/public/EoIB-OMS",
"provider": false
}]
}

Get vNET Access

This API enables you to retrieve information for a specific vNET access entity in a specific container.

Method

GET

REST Resource

/vnetaccess/name

URI

https://api_endpoint/vnetaccess/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the virtual network access. For example, /mytenant/public/myvnetworkaccess

Example URI

https://api.oc.example.com/vnetaccess/mytenant/public/EoIB-OMS

Example Response Body

{
"permissions":
{"object": ["b8c73cc2-1600-592...... "774ec529-acaf-5d53-bd1c-46726d7e091a", "95e5b59d-cde4-5530-a334-81b22095e19c"]},
"vnet": "/cloud/public/EoIB-OMS",
"uri": "https://api.oc.example.com/vnetaccess/mytenant/public/EoIB-OMS",
"name": "/mytenant/public/EoIB-OMS",
"provider": false
}

Managing vNET Reservations

A vNET Reservation enables the user to reserve an IP address for an instance.

Topics:

- Add vNET Reservation

- Delete vNET Reservation

- Retrieve vNET Reservation Details

Add vNET Reservation

This API enables you to add new vNET Reservation.

Method

POST

REST Resource

/vnetreservation/

URI

https://api_endpoint/vnetreservation/

Request Body Parameters

Parameter

Description

name

A unique hierarchical name for vNET Reservation . For example, /mytenant/public/myvnetreservation
Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.

vnet

vNET name from where the IP address will be reserved

ip

(Optional) IP address allocated for this IP entry. By default, a random IP address will be taken from the vNET IP range. If an IP address is specified, then the API will attempt to allocate the specified address from the vNET pool.

Example URI

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

Example Request Body

{
"name": "/mytenant/public/vnetres-1",
"vnet": "/mytenant/public/IPoIB-Test"
}

Example Response Body

{
"account": "/mytenant/default",
"used": false,
"name": "/mytenant/public/vnetres-1",
"ip": "192.168.160.65",
"uri": "http://api.oc.example.com/vnetreservation/mytenant/public/vnetres-1",
"quota": null,
"quota_reservation": null,
"vnet": "/mytenant/public/IPoIB-Test"
}

Delete vNET Reservation

This API enables you to delete a specific vNET Reservation.

Method

DELETE

REST Resource

/vnetreservation/name

URI

https://api_endpoint/vnetreservation/name

URI Parameter

Parameter

Description

name

A unique hierarchical name for the vNET Reservation. For example, /mytenant/public/myvnetreservation

Example URI

http://api.oc.example.com/vnetreservation/mytenant/public/vnetres-1

Retrieve vNET Reservation Details

You can retrieve vNET Reservation details by using the REST API.

Topics:

- Discover vNET Reservation

- Get vNET Reservation

- List vNET Reservations

Discover vNET Reservation

This API enables you to discover all the vNET Reservations listed in a specific container or subcontainer.

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

/vnetreservation/container/

URI

https://api_endpoint/vnetreservation/container/

URI Parameter

Parameter

Description

container

Hierarchical name-space for vNET Reservation.

Example URI

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

Example Response Body

{"result": ["/mytenant/public/myreserve", "/mytenant/public/mysecondreserve"]}

Get vNET Reservation

This API enables you to retrieve information for a specific vNET Reservation.

Method

GET

REST Resource

/vnetreservation/name

URI

https://api_endpoint/vnetreservation/{name}

URI Parameters

Parameter

Description

name

A unique hierarchical name for vNET Reservation. For example, /mytenant/public/myreservation

Example URI

https://api.oc.example.com/vnetreservation/mytenant/public/myreserve

Example Response Body

{
"result":
[{
"account": "/mytenant/default",
"used": false,
"name": "/mytenant/public/myreserve",
"ip": "192.168.192.17",
"uri": "https://api/vnetreservation/mytenant/public/myreserve",
"quota": null,
"quota_reservation": null,
"vnet": "/mytenant/public/vnet_1"
}]
}

List vNET Reservations

This API enables you to retrieve information for all the vNET Reservations in a specific container.

Method

GET

REST Resource

/vnetreservation/container/

URI

https://api_endpoint/vnetreservation/container?ip=ipValue&quota=quotaValue

URI Parameters

Parameter

Description

container

A unique hierarchical namespace for vNET Reservation . For example, /mytenant/public/

ip=ipValue

(Optional) IP address allocated for this IP entry. By default, a random IP address will be taken from the vNET pool. If specified, then the results are filtered based on the value of this parameter.

quota=quotaValue

(Optional) The quota against which this reservation is created. If specified, then the results are filtered based on the value of this parameter.

Example URI

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

Example Response Body

{"result": [
{
"account": "/docstenant/default",
"used": false,
"name": "/docstenant/public/myreserve",
"ip": "192.168.192.17",
"uri": "https://api/vnetreservation/docstenant/public/myreserve",
"quota": null,
"quota_reservation": null,
"vnet": "/docstenant/public/vnet_1"},

{
"account": "/docstenant/default",
"used": false,
"name": "/docstenant/public/mysecondreserve",
"ip": "192.168.192.18",
"uri": "https://api/vnetreservation/docstenant/public/mysecondreserve",
"quota": null,
"quota_reservation": null,
"vnet": "/docstenant/public/vnet_1"
}
]}

Viewing vCables

A virtual cable (vCable) is an internal representation of the link between an instance's network interface and a specific network. A vCable is created automatically when an instance is launched and is deleted when the instance is deleted. When a vCable is deleted (on instance termination), entities that depend on them are also deleted.

Topics:

- Discover vCables

- Get vCable

- List vCables

Discover vCables

This API enables you to discover vCable objects 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

/vcable/container/

URI

https://api_endpoint/vcable/container/

URI Parameter

Parameter

Description

container

Hierarchical namespace for vCables. For example, /mytenant/public/myvcable

Example URI

http://api.oc.example.com/vcable/mytenant/public

Example Response Body

{
"result": [
"/mytenant/public/450e9885-42a0-44ec-b102-9bbaf9c2c1e0",
"/mytenant/public/c65ccbbd-80b1-40c5-a100-356434c17374",
"/mytenant/public/dca6695a-7b72-49cb-9a70-20369b24a3d5",
"/mytenant/public/e8ec90f9-95a0-444f-bafe-ec5c87518d77"
]
}

Get vCable

This API enables you to retrieve information for a specific vCable.

Method

GET

REST Resource

/vcable/name

URI

https://api_endpoint/vcable/name

URI Parameter

Parameter

Description

name

Name of vCable.

Example URI

http://api.oc.example.com/vcable/mytenant/public/450e9885-42a0-44ec-b102-9bbaf9c2c1e0

Example Response Body

{
"net_config":
{
"owner": {"type": "tenant", "name": "mytenant"},
"ip": "192.168.160.67",
"netmask": "255.255.255.192",
"type": "IPoIB"
},
"vethernet_id": "-1",
"vnetreservation": "/mytenant/public/vnetres2",
"uri": "http://api.oc.example.com/vcable/mytenant/public/450e9885-42a0-44ec-b102-9bbaf9c2c1e0",
"options": {},
"instance": "/mytenant/public/32970825-74b9-4a19-aa84-570eabed8325",
"vnet": "/mytenant/public/IPoIB-Test",
"vethernet": "/mytenant/public/default",
"address": [null, "192.168.160.67"],
"model": "",
"vethernet_type": "ipoib",
"id": "/mytenant/public/450e9885-42a0-44ec-b102-9bbaf9c2c1e0",
"dhcp_options": []
}

List vCables

This API enables you to retrieve information for vCables in a specific container.

Method

GET

REST Resource

/vcable/container/

URI

https://api_endpoint/vcable/container?vnet=vnetValue&vethernet_id=vethrenet_idValue&vethernet_type=vethernet_typeValue&id=idvalue&instance=instanceValue&vethernet=vethernetValue

URI Parameters

Parameter

Description

container

Hierarchical namespace for vCables. For example, /mytenant/public/myvcable

vnet=vnetValue

(Optional) The path of the vNET used to create the vCable.
If specified, the vCable listing is scoped to only include vCables linked to the specified vNET.

vethernet_id=vethernet_idValue

(Optional) The vEthernet Id for the vCable. If specified, the vCable listing is scoped to only include vCables with the specified Id. The parameter is always set to -1 for infiniband networks.

vethernet_type=vethernet_typeValue

(Optional) The type of vEthernet for the vCable. Possible values are ipoib or eoib.
If specified, the vCable listing will be scoped to only include vCables linked to vEthernets of the specified type.

id=idValue

(Optional) Unique identifier of the particular vCable for which you want to retrieve info.

instance=instanceValue

(Optional)  A specific instance you want to list vCables for.
If specified, the listing will be scoped to only include vCables linked to this specific instance.

vethernet=vethernetValue

(Optional) The path of the vEthernet used to create the vCable.
If specified, the listing will be scoped to only include vCables linked to this specific vEthernet.

Example URI

https://api.oc.example.com/vcable/mytenant/?vethernet=/oracle/public/default

Example Response Body

{
"result":
[{
"vethernet_id": "0",
"uri": "http://api.oc.example.com/vcable/mytenant/public/06202d2e-3c30-42ca-974f-61cfdeb37120",
"proxyuri": null,
"instance": "/mytenant/public/917385c0-7951-4463-bafa-d817b9174bf5",
"vethernet": "/oracle/public/default",
"address": ["c6:b0:3a:0a:bf:6c", "0.0.0.0"],
"model": "",
"vethernet_type": "vlan",
"id": "/mytenant/public/06202d2e-3c30-42ca-974f-61cfdeb37120"
}]
}

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Pre-General Availability Draft Documentation Notice

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Pre-General Availability Draft Documentation Notice

If this document is in private pre-General Availability status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.