Create Instances Using Launch Plans

post

/launchplan/

A launch plan is a JSON-formatted file that defines the properties of one or more instances. You can use a launch plan to quickly create and start multiple, non-persistent instances in Compute Classic.

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

Supported Media Types
Header Parameters
Body ()
The request body contains details of the launch plan that you want to create.
Root Schema : LaunchPlan-post-request
Type: object
The request body contains details of the launch plan that you want to create.
Show Source
  • instances

    A list of instances.

    Each instance is defined using the instance attributes.

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

Nested Schema : instances
Type: array

A list of instances.

Each instance is defined using the instance attributes.

Show Source
Nested Schema : relationships
Type: 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.

Show Source
Nested Schema : Instance-post-request
Type: object
The request body contains details of the instance that you want to create.
Show Source
  • attributes
    Additional Properties Allowed: additionalProperties
    A JSON object or dictionary of user-defined attributes to be made available to the instance.
  • 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 for the instance.

    * Set the value of the desired_state parameter as shutdown to shut down the instance.

    * Set the value of the desired_state parameter as running to restart an instance that you had previously shutdown. The instance is restarted without losing any of the instance data or configuration.

  • Optional imagelistentry number (default will be used if not specified).
  • 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.
  • 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.
  • A label assigned by the user, specifically for defining inter-instance relationships.
  • The three-part name of the instance(/Compute-identity_domain/user/object). If you don't specify this parameter, it will be autogenerated.
  • networking
    Additional Properties Allowed: additionalProperties
    Mapping of device name to network specifiers for virtual NICs to be attached to this instance.
  • If set to true (default), then reverse DNS records are created. If set to false, no reverse DNS records are created.
  • The name of the shape that defines the number of CPUs and the RAM that you require for the instance.
  • sshkeys
    A list of the SSH public keys that you want to associate with the instance.
  • 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
    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.
Nested Schema : attributes
Type: object
Additional Properties Allowed
Show Source
A JSON object or dictionary of user-defined attributes to be made available to the instance.
Nested Schema : boot_order
Type: array
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.
Show Source
Nested Schema : networking
Type: object
Additional Properties Allowed
Show Source
Mapping of device name to network specifiers for virtual NICs to be attached to this instance.
Nested Schema : sshkeys
Type: array
A list of the SSH public keys that you want to associate with the instance.
Show Source
Nested Schema : storage_attachments
Type: array
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.

Show Source
Nested Schema : tags
Type: array
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.
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : additionalProperties
Type: object
Nested Schema : items
Type: object
Additional Properties Allowed
Show Source
Nested Schema : additionalProperties
Type: object

Response

Supported Media Types

201 Response

Created. See Status Codes for information about other possible HTTP status codes.
Headers
Body ()
Root Schema : LaunchPlan-response
Type: object
Show Source
  • instances

    A list of instances.

    Each instance is defined using the instance attributes.

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

Nested Schema : instances
Type: array

A list of instances.

Each instance is defined using the instance attributes.

Show Source
Nested Schema : relationships
Type: 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.

Show Source
Nested Schema : Instance-response
Type: object
Show Source
Nested Schema : attributes
Type: object
Additional Properties Allowed
Show Source
A 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.
Nested Schema : boot_order
Type: array
Boot order list.
Show Source
Nested Schema : hypervisor
Type: object
Additional Properties Allowed
Show Source
A dictionary of hypervisor-specific attributes.
Nested Schema : networking
Type: object
Additional Properties Allowed
Show Source
Mapping of to network specifiers for virtual NICs to be attached to this instance.
Nested Schema : placement_requirements
Type: array
A list of strings specifying arbitrary tags on nodes to be matched on placement.
Show Source
Nested Schema : relationships
Type: array
A list of relationship specifications to be satisfied on this instance's placement
Show Source
Nested Schema : resolvers
Type: array
Resolvers to use instead of the default resolvers.
Show Source
Nested Schema : sshkeys
Type: array
SSH keys that will be exposed to the instance.
Show Source
Nested Schema : storage_attachments
Type: array
List of dictionaries containing storage attachment Information.
Show Source
Nested Schema : tags
Type: array
Comma-separated list of strings used to tag the instance.
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : additionalProperties
Type: object
Nested Schema : additionalProperties
Type: object
Nested Schema : items
Type: object
Additional Properties Allowed
Show Source
Nested Schema : additionalProperties
Type: object
Nested Schema : items
Type: object
Additional Properties Allowed
Show Source
Nested Schema : additionalProperties
Type: 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
    }
  ]
}