Create Instances Using Launch Plans
/launchplan/
A launch plan specifies the provisioning sequence and attributes of the instances that you want to create. Note that while you can reuse your launch plan JSON file to create new instances based on the attributes and provisioning sequence specified in the JSON file, the launch plan itself doesn't persist in Compute Classic.
For information about the attributes you can specify in a launch plan JSON file, see Creating Instances Using Launch Plans in Using Oracle Cloud Infrastructure Compute Classic.
Required Role: To complete this task, you must have the Compute_Operations
role. If this role isn't assigned to you or you're not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud My Services. See Modifying User Roles in Managing and Monitoring Oracle Cloud.
Request
- application/oracle-compute-v3+json
-
Cookie: string
The Cookie: header must be included with every request to the service. It must be set to the value of the set-cookie header in the response received to the POST /authenticate/ call.
object
-
instances:
array instances
A list of instances.
Each instance is defined using the instance attributes.
-
relationships(optional):
array relationships
The relationships between various instances.
Valid values:
- same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.
- different_node: The specified instances aren't created on the same physical server. This is useful if you want to isolate instances for security or redundancy.
array
A list of instances.
Each instance is defined using the instance attributes.
-
Array of:
object Instance-post-request
The request body contains details of the instance that you want to create.
array
The relationships between various instances.
Valid values:
- same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.
- different_node: The specified instances aren't created on the same physical server. This is useful if you want to isolate instances for security or redundancy.
-
Array of:
object items
Additional Properties Allowed: additionalProperties
object
-
attributes(optional):
object attributes
Additional Properties Allowed: additionalPropertiesA JSON object or dictionary of user-defined attributes to be made available to the instance.
-
boot_order(optional):
array boot_order
The index number of the bootable storage volume that should be used to boot the instance. The only valid value is 1. If you set this attribute, you must also specify a bootable storage volume with index number 1 in the volume sub-parameter of storage_attachments. When you specify boot_order, you don't need to specify the imagelist attribute, because the instance is booted using the image on the specified bootable storage volume. If you specify both boot_order and imagelist, the imagelist attribute is ignored.
-
desired_state(optional):
string
Desired state for the instance.
* Set the value of the
desired_state
parameter asshutdown
to shut down the instance.* Set the value of the
desired_state
parameter asrunning
to restart an instance that you had previously shutdown. The instance is restarted without losing any of the instance data or configuration. -
entry(optional):
integer
Optional imagelistentry number (default will be used if not specified).
-
hostname(optional):
string
The host name assigned to the instance. On an Oracle Linux instance, this host name is displayed in response to the hostname command. Only relative DNS is supported. The domain name is suffixed to the host name that you specify. The host name must not end with a period. If you don't specify a host name, then a name is generated automatically.
-
imagelist(optional):
string
The three-part name (
/Compute-identity_domain/user/object
) of the image list containing the image to be used. You must use this attribute if you don't specify a bootable storage volume by using the boot_order attribute. If you specify the imagelist attribute as well as the boot_order attribute, then the imagelist attribute is ignored. -
label(optional):
string
A label assigned by the user, specifically for defining inter-instance relationships.
-
name(optional):
string
The three-part name of the instance(
/Compute-identity_domain/user/object
). If you don't specify this parameter, it will be autogenerated. -
networking(optional):
object networking
Additional Properties Allowed: additionalPropertiesMapping of device name to network specifiers for virtual NICs to be attached to this instance.
-
reverse_dns(optional):
boolean
If set to true (default), then reverse DNS records are created. If set to false, no reverse DNS records are created.
-
shape:
string
The name of the shape that defines the number of CPUs and the RAM that you require for the instance.
-
sshkeys(optional):
array sshkeys
A list of the SSH public keys that you want to associate with the instance.
-
storage_attachments(optional):
array storage_attachments
If you specify the storage_attachments parameter, then specify the following subparameters for each attachment:
volume: The three-part name (
/Compute-identity_domain/user/object
) of the storage volume that you want to attach to the instance. Note that volumes attached to an instance at launch time can't be detached.index: The index number for the volume. The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as 1. The index determines the device name by which the volume is exposed to the instance.
-
tags(optional):
array tags
A JSON array or list of strings used to tag the instance. By assigning a human-friendly tag to an instance, you can identify the instance easily when you perform an instance listing. These tags aren't available from within the instance.
object
array
object
array
array
volume: The three-part name (/Compute-identity_domain/user/object
) of the storage volume that you want to attach to the instance. Note that volumes attached to an instance at launch time can't be detached.
index: The index number for the volume. The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as 1. The index determines the device name by which the volume is exposed to the instance.
object
object
object
Response
- application/oracle-compute-v3+json
201 Response
-
set-cookie: string
The cookie value is returned if the session is extended
object
-
instances(optional):
array instances
A list of instances.
Each instance is defined using the instance attributes.
-
relationships(optional):
array relationships
The relationships between various instances.
Valid values:
- same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.
- different_node: The specified instances aren't created on the same physical server. This is useful if you want to isolate instances for security or redundancy.
array
A list of instances.
Each instance is defined using the instance attributes.
array
The relationships between various instances.
Valid values:
- same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.
- different_node: The specified instances aren't created on the same physical server. This is useful if you want to isolate instances for security or redundancy.
-
Array of:
object items
Additional Properties Allowed: additionalProperties
object
-
account(optional):
string
Shows the default account for your identity domain.
-
attributes(optional):
object attributes
Additional Properties Allowed: additionalPropertiesA dictionary of attributes to be made available to the instance. A value with the key "userdata" will be made available in an EC2-compatible manner.
-
availability_domain(optional):
string
The availability domain the instance is in
-
boot_order(optional):
array boot_order
Boot order list.
-
desired_state(optional):
string
Desired state for the instance. The value can be
shutdown
orrunning
to shutdown an instance or to restart a previously shutdown instance respectively. -
disk_attach(optional):
string
A label assigned by the user to identify disks.
-
domain(optional):
string
The default domain to use for the hostname and for DNS lookups.
-
entry(optional):
integer
Optional imagelistentry number (default will be used if not specified).
-
error_reason(optional):
string
The reason for the instance going to error state, if available.
-
fingerprint(optional):
string
SSH server fingerprint presented by the instance.
-
hostname(optional):
string
The hostname for this instance.
-
hypervisor(optional):
object hypervisor
Additional Properties Allowed: additionalPropertiesA dictionary of hypervisor-specific attributes.
-
image_format(optional):
string
The format of the image.
-
imagelist(optional):
string
Name of imagelist to be launched.
-
ip(optional):
string
IP address of the instance.
-
label(optional):
string
A label assigned by the user, specifically for defining inter-instance relationships.
-
name(optional):
string
Multipart name of the instance.
-
networking(optional):
object networking
Additional Properties Allowed: additionalPropertiesMapping of
to network specifiers for virtual NICs to be attached to this instance. -
placement_requirements(optional):
array placement_requirements
A list of strings specifying arbitrary tags on nodes to be matched on placement.
-
platform(optional):
string
The OS platform for the instance.
-
priority(optional):
string
The priority at which this instance will be run.
-
quota(optional):
string
Not used
-
relationships(optional):
array relationships
A list of relationship specifications to be satisfied on this instance's placement
-
resolvers(optional):
array resolvers
Resolvers to use instead of the default resolvers.
-
reverse_dns(optional):
boolean
Add PTR records for the hostname.
-
shape(optional):
string
A shape is a resource profile that specifies the number of CPU threads and the amount of memory (in MB) to be allocated to an instance.
-
sshkeys(optional):
array sshkeys
SSH keys that will be exposed to the instance.
-
start_time(optional):
string
Start time of the instance.
-
state(optional):
string
State of the instance.
-
storage_attachments(optional):
array storage_attachments
List of dictionaries containing storage attachment Information.
-
tags(optional):
array tags
Comma-separated list of strings used to tag the instance.
-
uri(optional):
string
Uniform Resource Identifier
-
vcable_id(optional):
string
vCable for this instance.
-
vnc(optional):
string
IP address and port of the VNC console for the instance.
object
object
object
array
array
-
Array of:
object items
Additional Properties Allowed: additionalProperties
array
array
object
object
object
object
object
Examples
cURL Command
The following example shows how to create instances using a launch plan by submitting a POST request on the launchplan
REST resource using cURL. For more information about cURL, see Use cURL.
Enter the command on a single line. Line breaks are used in this example for readability.
curl -i -X POST -H "Cookie: $COMPUTE_COOKIE" -H "Content-Type: application/oracle-compute-v3+json" -H "Accept: application/oracle-compute-v3+json" -d "@launchplan.json" https://api-z999.compute.us0.oraclecloud.com/launchplan/
-
COMPUTE_COOKIE
is the name of the variable in which you stored the authentication cookie earlier. For information about retrieving the authentication cookie and storing it in a variable, see Authentication. -
api-z999.compute.us0.oraclecloud.com
is an example REST endpoint URL. Change this value to the REST endpoint URL of your Compute Classic site. For information about finding out REST endpoint URL for your site, see Send Requests.
Example of Request Body
The following shows an example of the request body content in the launchplan.json
file to create two instances with the specified instance attributes.
{ "instances": [ { "shape": "oc3", "imagelist": "/oracle/public/oel_6.4_2GB_v1", "name": "/Compute-acme/jack.jones@example.com/dev-vm", "label": "dev-vm", "sshkeys": [ "/Compute-acme/jack.jones@example.com/dev-key1" ] }, { "shape": "oc4", "imagelist": "/oracle/public/oel_6.4_2GB_v1", "name": "/Compute-acme/jack.jones@example.com/prod-vm", "label": "prod-vm", "sshkeys": [ "/Compute-acme/jack.jones@example.com/prod-key1" ] } ] }
Example of Response Body
The following example shows the response body in JSON format.
Some lines may be truncated with ellipses (...) for readability.
{ "relationships": [ ], "instances": [ { "domain": "compute-acme...", "placement_requirements": [ "/system/compute/placement/default", "/system/compute/allow_instances" ], "ip": "0.0.0.0", "fingerprint": "", "site": "", "last_state_change_time": null, "cluster": null, "shape": "oc3", "vethernets": null, "imagelist": "/oracle/public/oel_6.4_2GB_v1", "image_format": "raw", "id": "437b72fd-b870-47b1-9c01-7a2812bbe30c", "cluster_uri": null, "networking": { "eth0": { "model": "", "seclists": [ "/Compute-acme/default/default" ], "dns": [ "d9dd5d.compute-acme.oraclecloud.internal." ], "nat": null, "vethernet": "/oracle/public/default" } }, "seclist_associations": null, "hostname": "d9dd5d.compute-acme.oraclecloud.internal.", "state": "queued", "disk_attach": "", "label": "dev-vm", "priority": "/oracle/public/default", "platform": "linux", "quota_reservation": null, "suspend_file": null, "node": null, "resource_requirements": { "compressed_size": 727212045, "ram": 7680, "cpus": 2.0, "root_disk_size": 0, "io": 200, "decompressed_size": 2277507072 }, "virtio": null, "vnc": "", "storage_attachments": [], "start_time": "2016-04-06T18:03:12Z", "storage_attachment_associations": [], "quota": "/Compute-acme", "vnc_key": null, "numerical_priority": 100, "suspend_requested": false, "entry": 1, "error_reason": "", "nat_associations": null, "sshkeys": ["/Compute-acme/jack.jones@example.com/dev-key1"], "tags": [], "resolvers": null, "metrics": null, "account": "/Compute-acme/default", "node_uuid": null, "name": "/Compute-acme/jack.jones@example.com/dev-vm/437b72fd-b870-47b1-9c01-7a2812bbe30c", "vcable_id": null, "hypervisor": {"mode": "hvm"}, "uri": "https://api-z999.compute.us0.oraclecloud.com/instance/Compute-acme/jack.jones@example.com/dev-vm/437b72fd-b870-47b1-9c01-7a2812bbe30c", "console": null, "reverse_dns": true, "delete_requested": null, "hypervisor_type": null, "attributes": { "sshkeys": ["ssh-rsa AAAAB3..."] }, "boot_order": [], "last_seen": null }, { "domain": "compute-acme...", "placement_requirements": [ "/system/compute/placement/default", "/system/compute/allow_instances" ], "ip": "0.0.0.0", "fingerprint": "", "site": "", "last_state_change_time": null, "cluster": null, "shape": "oc4", "vethernets": null, "imagelist": "/oracle/public/oel_6.4_2GB_v1", "image_format": "raw", "id": "8e37d700-c63c-46f7-bfc0-eea5d788bd04", "cluster_uri": null, "networking": { "eth0": { "model": "", "seclists": [ "/Compute-acme/default/default" ], "dns": [ "...compute-acme..." ], "nat": null, "vethernet": "/oracle/public/default" } }, "seclist_associations": null, "hostname": "...compute-acme...", "state": "queued", "disk_attach": "", "label": "prod-vm", "priority": "/oracle/public/default", "platform": "linux", "quota_reservation": null, "suspend_file": null, "node": null, "resource_requirements": { "compressed_size": 727212045, "ram": 15360, "cpus": 4.0, "root_disk_size": 0, "io": 400, "decompressed_size": 2277507072 }, "virtio": null, "vnc": "", "storage_attachments": [], "start_time": "2016-04-06T18:03:12Z", "storage_attachment_associations": [], "quota": "/Compute-acme", "vnc_key": null, "numerical_priority": 100, "suspend_requested": false, "entry": 1, "error_reason": "", "nat_associations": null, "sshkeys": ["/Compute-acme/jack.jones@example.com/prod-key1"], "tags": [], "resolvers": null, "metrics": null, "account": "/Compute-acme/default", "node_uuid": null, "name": "/Compute-acme/jack.jones@example.com/prod-vm/8e37d700-c63c-46f7-bfc0-eea5d788bd04", "vcable_id": null, "hypervisor": {"mode": "hvm"}, "uri": "https://api-z999.compute.us0.oraclecloud.com/instance/Compute-acme/jack.jones@example.com/prod-vm/8e37d700-c63c-46f7-bfc0-eea5d788bd04", "console": null, "reverse_dns": true, "delete_requested": null, "hypervisor_type": null, "attributes": { "sshkeys": ["ssh-rsa AAAA..."] }, "boot_order": [], "last_seen": null } ] }